Adyen 23.0.0

Adyen .NET API Library

This is the officially supported .NET library for the Adyen's APIs. Are you looking for examples? You can find our .NET Integration examples on GitHub here.

Supported API versions

The library supports all APIs under the following services:

Supported Webhook versions

The library supports all webhooks under the following model directories:

For more information, refer to our documentation or the API Explorer.

Prerequisites

• Adyen Test Account
• Adyen API key. For testing, your API credential needs to have the API PCI Payments role.
• Adyen .NET API Library supports .NET Standard 2.0 and .NET 6.0
• In order for Adyen .NET API Library to support local terminal api certificate validation the application should be set to .net core 2.1 and above or .net framework 4.6.1 and above

Installation

Simply download and restore nuget packages https://www.nuget.org/packages/Adyen/ or install it from package manager

PM> Install-Package Adyen -Version x.x.x

❗Disclaimer on Enum Values

Please note that the integer value (index) of the enums used in this library may change in future releases. These values are not guaranteed to remain static, and they may be modified, added, or removed as the library evolves.

⚠️ We advise against hard-coding or relying on specific enum integer values in your implementation, as they may break compatibility with future versions of this library. Use instead the string value of the enums.

Upon upgrade check the Release Notes and the associated PRs to understand the changes and any potential impact on your integration.

Using the library

In order to submit http request to Adyen API you need to initialize the client. The following example makes a checkout payment request:

using Adyen;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;
using Environment = Adyen.Model.Environment;

var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);
var paymentsService = new PaymentsService(client);
var amount = new Model.Checkout.Amount("USD", 1000);
var cardDetails = new CardDetails
{
    EncryptedCardNumber = "test_4111111111111111",
    EncryptedSecurityCode = "test_737",
    EncryptedExpiryMonth = "test_03",
    EncryptedExpiryYear = "test_2030",
    HolderName = "John Smith",
    Type = CardDetails.TypeEnum.Card
};
var paymentRequest = new Model.Checkout.PaymentRequest
{
    Reference = "Your order number ",
    ReturnUrl = @"https://your-company.com/...",
    MerchantAccount = "your-merchant-account",
    Amount = amount,
    PaymentMethod = new CheckoutPaymentMethod(cardDetails)
};
var paymentResponse = paymentsService.Payments(paymentRequest);

Or in case you would like to make an asynchronous /payments request with idempotency key and cancellation token, the last line would be instead:

var requestOptions = new RequestOptions();
requestOptions.IdempotencyKey = "YourGeneratedUniqueGuid";
PaymentResponse paymentResponse = await paymentsService.PaymentsAsync(paymentRequest, requestOptions: requestOptions, cancellationToken: new CancellationToken());

Deserializing JSON Strings

In some setups you might need to deserialize JSON strings to request objects. For example, when using the libraries in combination with Dropin/Components. Please use the built-in deserialization functions:

// Import the required model class
using Adyen.Model.Checkout;

// Deserialize using built-in function
PaymentRequest paymentRequest = PaymentRequest.FromJson("YOUR_JSON_STRING");

Running the tests

Navigate to adyen-dotnet-api-library folder and run the following commands.

dotnet build
dotnet test

[!IMPORTANT] We have split and renamed TerminalCloudApi.cs to:

1. TerminalApiAsyncService.cs (which sends requests to terminal-api.adyen.com/async) and
2. TerminalApiSyncService.cs (which sends requests to terminal-api.adyen.com/sync)
3. TerminalApiLocalService.cs (which sends requests to your custom endpoint, f.e. https://198.51.100.1:8443/nexo)

Using the Cloud Terminal API

In order to submit POS request with Cloud Terminal API, you need to initialize the client with the endpoints that it is closer to your region when going live. The Endpoints are available as contacts in ClientConfig. For more information, visit our documentation

// Example for EU based region
using Adyen;
using Adyen.Constants;

var config = new Config
{
    XApiKey = "ADYEN_API_KEY",
    CloudApiEndPoint = ClientConfig.CloudApiEndPointEULive
};
var client = new Client(config);

To parse the terminal API notifications, you can use the following custom deserializer. This method will throw an exception for non-notification requests.

SaleToPoiMessageSerializer serializer = new SaleToPoiMessageSerializer();
SaleToPOIRequest saleToPoiRequest = serializer.DeserializeNotification(your_terminal_notification);

Example Cloud Terminal API integration /sync-endpoint

using System;
using Adyen.Model;
using Adyen.Model.TerminalApi;
using Adyen.Model.TerminalApi.Message;
using Adyen.Service;
using Environment = Adyen.Model.Environment;
 
namespace Adyen.Terminal
{
   public static class Program
   {
        private static void Main(string[] args)
        {
            var config = new Config() {
                XApiKey = "ADYEN_API_KEY",
                Environment = Environment.Test
            };
            var client = new Client(config, Environment.Test);
        }
       
        // Terminal-api `/sync` - `https://terminal-api-test.adyen.com/sync`
        private static SyncEndpointExample(Client client) {
            ITerminalApiSyncService terminalApiSyncService = new TerminalApiSyncService(client, new SaleToPoiMessageSerializer(), new SaleToPoiMessageSecuredEncryptor(), new SaleToPoiMessageSecuredSerializer());
            SaleToPOIResponse response = terminalApiSyncService.Request(GetPaymentRequest()); // Use: await terminalApiSyncService.RequestAsync(GetPaymentRequest()) for asynchronous communications.
            PaymentResponse paymentResponse = response.MessagePayload as PaymentResponse;
            Console.WriteLine(paymentResponse?.Response?.Result);
        }
       
        // Terminal-api `/async` - `https://terminal-api-test.adyen.com/async`
        private static AsyncEndpointExample(Client client) {
            ITerminalApiAsyncService terminalApiAsyncService = new TerminalApiAsyncService(client, new SaleToPoiMessageSerializer(), new SaleToPoiMessageSecuredEncryptor(), new SaleToPoiMessageSecuredSerializer());
            String response = terminalApiAsyncService.Request(GetPaymentRequest()); // Use: await terminalApiAsyncService.RequestAsync(GetPaymentRequest()) for asynchronous communications.
            Console.WriteLine(response);
        }
       
        private static SaleToPOIRequest GetPaymentRequest()
        {
            var serviceID = "SERVICE_ID"; // ServiceId should be unique for every request
            var saleID = "SALE_ID";
            var POIID = "SERIAL_NUMBER";
            var transactionID = "123459";
            SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest()
            {
                MessageHeader = new MessageHeader()
                {
                    MessageClass = MessageClassType.Service,
                    MessageCategory = MessageCategoryType.Payment,
                    MessageType = MessageType.Request,
                    ServiceID = serviceID,
                    SaleID = saleID,
                    POIID = POIID
                },
                MessagePayload = new PaymentRequest()
                {
                    SaleData = new SaleData()
                    {
                        SaleTransactionID = new TransactionIdentification()
                        {
                            TransactionID = transactionID,
                            TimeStamp = DateTime.Now
                        }
                    },
                    PaymentTransaction = new PaymentTransaction()
                    {
                        AmountsReq = new AmountsReq()
                        {
                            Currency = "EUR",
                            RequestedAmount = new decimal(13.37)
                        },
                    },
                }
            };
            return saleToPOIRequest;
        }
    }
}

Using the Local Terminal API

The request and response payloads are identical to the Cloud Terminal API, however an additional encryption details object is required to send the requests. You can retrieve these details from the Customer Area, make sure you update your terminal to the latest version if you've updated these keys.

using Adyen;
using Adyen.Security;

var encryptionCredentialDetails = new EncryptionCredentialDetails
{
    KeyVersion = 1,
    AdyenCryptoVersion = 1,
    KeyIdentifier = "CryptoKeyIdentifier12345",
    Password = "p@ssw0rd123456"
};
var config = new Config
{
    Environment = Model.Environment.Test,
    LocalTerminalApiEndpoint = @"https://_terminal_:8443/nexo/" // _terminal_ example: `https://198.51.100.1:8443/nexo` (can be found in the WIFI settings of your terminal)
};
var client = new Client(config);
ITerminalApiLocalService terminalApiLocalService = new TerminalApiLocalService(client);
// Asynchronous call (preferred)
var saleToPOIResponse = await terminalApiLocalService.RequestEncryptedAsync(paymentRequest, encryptionCredentialDetails, new CancellationToken()); // Pass cancellation token or create a new one.
// Synchronous (blocking) call
//var saleToPOIResponse = terminalApiLocalService.RequestEncrypted(paymentRequest, encryptionCredentialDetails);

Alternatively one can use the local terminal API without encryption. This is only allowed in the TEST environment and in order for this to work one has to remove any encryption details from the Customer Area. When sending requests to a local (unknown) endpoint, you may run into System.Net.Http.HttpRequestException: The SSL connection could not be established due to certificate issues. For local testing purposes, developers can override the System.Net.Http.HttpClientHandler and always returns true when validating the certificate.

[!CAUTION] Follow the guide in the Adyen documentation to install the root certificate on TEST and on LIVE.

using Adyen;
using Adyen.Security;

// Override the HttpClientHandler to always return true, for LOCAL TESTING PURPOSES, NEVER run this on live. 
var handler = new System.Net.Http.HttpClientHandler { ServerCertificateCustomValidationCallback = (message, certificate2, arg3, arg4) => true };
var client = new Client(config, new System.Net.Http.HttpClient(handler));

ITerminalApiLocalService terminalApiLocalService = new TerminalApiLocalService(client, new SaleToPoiMessageSerializer(), new SaleToPoiMessageSecuredEncryptor(), new SaleToPoiMessageSecuredSerializer());
SaleToPOIResponse response = await terminalApiLocalService.RequestEncryptedAsync(PaymentRequest());
PaymentResponse paymentResponse = response.MessagePayload as PaymentResponse;
Console.WriteLine(paymentResponse?.Response?.Result);

To parse the terminal API notifications, use the following custom deserializer. This method will throw an exception for non-notification requests.

var serializer = new SaleToPoiMessageSerializer();
var saleToPoiRequest = serializer.DeserializeNotification(your_terminal_notification);

Note that the AdditionalResponse field, when performing a CardAcquisition request could be either a based64 encoded-string or key-value-pair. You can use the CardAcquisitionUtil.AdditionalResponse(...)-function to deserialize it.

AdditionalResponse additionalResponse = CardAcquisitionUtil.AdditionalResponse(jsonString);

Parsing BalancePlatform and Management Webhooks

In order to parse banking webhooks, first validate the webhooks (recommended) by retrieving the hmac key from the webhook header and the hmac signature from the Balance Platform CA configuration page respectively.

using Adyen.Model.ConfigurationWebhooks;
using Adyen.Webhooks;
using Adyen.Util;

...
var hmacValidator = new HmacValidator();
var handler = new BalancePlatformWebhookHandler();
bool isValid = hmacValidator.IsValidWebhook("hmacSignature", "ADYEN_HMAC_KEY", webhookPayload);

if (isValid) {
    dynamic webhook = handler.GetGenericBalancePlatformWebhook(webhookPayload);
}

If you want to handle specific webhook types you're expecting to receive, check the type and retrieve if the type is correct:

var handler = new BalancePlatformWebhookHandler();
bool isAccountHolderNotification = handler.GetAccountHolderNotificationRequest(json_payload, out AccountHolderNotificationRequest webhook)
// Your logic here based on whether the webhook parsed correctly or not

Validating management webhooks is identical to validating the balance platform webhooks. To parse the management webhooks, however, one calls the following handler:

var handler = new ManagementWebhookHandler();
if(handler.GetMerchantCreatedNotificationRequest(json_payload, out MerchantCreatedNotificationRequest webhook))
{ 
    // Your logic here using the passed through webhook variable
}

Feedback

We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out our feedback form to share your thoughts, suggestions or ideas.

Contributing

We encourage you to contribute to this repository, so everyone can benefit from new features, bug fixes, and any other improvements. Have a look at our contributing guidelines to find out how to raise a pull request.

Support

If you have a feature request, or spotted a bug or a technical problem, create an issue here.

For other questions, contact our Support Team.

Licence

This repository is available under the MIT license.

See also

• Adyen .NET Integration Examples
• Adyen Docs
• API Explorer