PAYONE Commerce Platform .NET SDK

Welcome to the .NET SDK for the PAYONE Commerce Platform! This repository contains a powerful, easy-to-use software development kit (SDK) designed to simplify the integration of online payment processing into your applications.

Table of Contents

• Features
• Installation
• Usage
  • General
  • Error Handling
  • Client Side
  • Apple Pay
• Demo App
• Contributing
• Releasing the library
  • Preparing the Release
  • Changelog Generation with Conventional Changelog
  • Merging the Release Branch
  • GitHub Action for Release
  • Optional: Creating a GitHub Release
• License

Features

• Easy Integration: Easily add online payment processing to your application.
• Secure: Designed with security in mind to protect transactions.
• Well-Documented: Detailed documentation to help you get started.
• Open Source: Community-driven and open source.

Requirements

This SDK requires .NET 7 or higher.

Installation

Currently this package is not available on NuGet.
You need to download the package from the Github Releases Page and install it locally.

dotnet add package pcp-serversdk-dotnet --source /path/to/your/packages/directory

back to top

Usage

General

To use this SDK you need to construct a CommunicatorConfiguration which encapsulate everything needed to connect to the PAYONE Commerce Platform.

using PCPServerSDKDotNet;

string? apiKey = Environment.GetEnvironmentVariable("API_KEY");
string? apiSecret = Environment.GetEnvironmentVariable("API_SECRET");

CommunicatorConfiguration config = new(apiKey, apiSecret, "api.preprod.commerce.payone.com", null);

All payloads and responses are availabe as C# classes within the PCPServerSDKDotNet.Models package. The serialization and deserialization is handled by the SDK internally. For example, to create an empty commerce case you can pass a CreateCommerceCaseRequest instance:

string? apiKey = Environment.GetEnvironmentVariable("API_KEY");
string? apiSecret = Environment.GetEnvironmentVariable("API_SECRET");
string? merchantId = Environment.GetEnvironmentVariable("MERCHANT_ID");

CommunicatorConfiguration config = new(apiKey, apiSecret, "api.preprod.commerce.payone.com", null);

CommerceCaseApiClient client = new(config);

CreateCommerceCaseResponse res = await client.CreateCommerceCaseRequestAsync(merchantId, new CreateCommerceCaseRequest());

The models directly map to the API as described in PAYONE Commerce Platform API Reference. For an in depth example you can take a look at the demo app.

Error Handling

When making a request any client may throw a ApiException. There two subtypes of this exception:

• ApiErrorReponseException: This exception is thrown when the API returns an well-formed error response. The given errors are deserialized into APIError objects which are availble via the GetErrors() method on the exception. They usually contain useful information about what is wrong in your request or the state of the resource.
• ApiResponseRetrievalException: This exception is a catch-all exception for any error that cannot be turned into a helpful error response. This includes malformed responses or unknown responses.

Client Side

For most payment methods some information from the client is needed, e.g. payment information given by Apple when a payment via ApplePay suceeds. PAYONE provides client side SDKs which helps you interact the third party payment providers. You can find the SDKs under the PAYONE GitHub organization. Either way ensure to never store or even send credit card information to your server. The PAYONE Commerce Platform never needs access to the credit card information. The client side is responsible for safely retrieving a credit card token. This token must be used with this SDK.

Apple Pay

When a client is successfully made a payment via ApplePay it receives a ApplePayPayment. This structure is accessible as the ApplePayPayment class. You can use the ApplePayTransformer to map an ApplePayPayment to a MobilePaymentMethodSpecificInput which can be used for payment executions or order requests. The transformer has a static method transformApplePayPaymentToMobilePaymentMethodSpecificInput() which takes an ApplePayPayment and returns a MobilePaymentMethodSpecificInput. The transformer does not check if the response is complete, if anything is missing the field will be set to null.

using PCPServerSDKDotNet.Transformer;

ApplePayPayment payment = JsonConvert.DeserializeObject<ApplePayPayment>(GetJsonStringFromRequestSomehow());
MobilePaymentMethodSpecificInput input = TransformApplePayPaymentToMobilePaymentMethodSpecificInput(payment);

back to top

Demo App

API_KEY=api_key API_SECRET=api_secret MERCHANT_ID=123 COMMERCE_CASE_ID=234 CHECKOUT_ID=345 ./scripts.sh run

back to top

Contributing

See Contributing

back to top

Releasing the library

Preparing the Release

• Checkout develop branch
• Create release branch (release/0.1.0)

git checkout -b release/0.1.0

• Run scripts.sh script to set correct version

./scripts.sh version 0.1.0

Changelog Generation with Conventional Changelog

When calling the ./scripts.sh version script, the changelog will now be generated automatically using conventional-changelog.

1. Conventional Commit Messages:

   • Ensure all commit messages follow the conventional commit format, which is crucial for automatic changelog generation.
   • Commit messages should be in the format: type(scope): subject.

2. Enforcing Commit Messages:

   • We enforce conventional commit messages using Lefthook with commitlint.
   • This setup ensures that all commit messages are validated before they are committed.

3. Automatic Changelog Generation:

   • The ./scripts.sh version script will automatically generate and update the CHANGELOG.md file.
   • After running the script, review the updated changelog to ensure accuracy before proceeding with the release.

Merging the Release Branch

• Create PR on develop branch
• Merge develop in main branch

GitHub Action for Release

After successfully merging all changes to the main branch, an admin can trigger a GitHub Action to finalize and publish the release. This action ensures that the release process is automated, consistent, and deploys the new release from the main branch.

Triggering the GitHub Action:

• Only admins can trigger the release action.
• Ensure that all changes are committed to the main branch.
• Navigate to the Actions tab on your GitHub repository and manually trigger the release action for the main branch.

Optional: Creating a GitHub Release

Once the release has been published to NuGet, developers can start using the latest version of the SDK. However, if you want to make the release more visible and include detailed release notes, you can optionally create a GitHub release.

1. Navigate to the Releases Page: Go to the "Releases" section of your repository on GitHub.
2. Draft a New Release: Click "Draft a new release".
3. Tag the Release: Select the version tag that corresponds to the version you just published on npm (e.g., v0.1.0).
4. Release Title: Add a descriptive title for the release (e.g., v0.1.0 - Initial Release).
5. Auto-Generated Release Notes: GitHub can automatically generate release notes based on merged pull requests and commit history. You can review these notes, adjust the content, and highlight important changes.
6. Publish the Release: Once you're satisfied with the release notes, click "Publish release".

Creating a GitHub release is optional, but it can provide additional context and visibility for your users. For detailed guidance, refer to the GitHub documentation on managing releases.

back to top

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Thank you for using our SDK for Online Payments! If you have any questions or need further assistance, feel free to open an issue or contact us.