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:

API	Description	Service Name	Supported version
Adyen BinLookup API	Endpoints for retrieving information, such as cost estimates, and 3D Secure supported version based on a given BIN. Current supported version	BinLookup	v54
Balance Control API	The Balance Control API lets you transfer funds between merchant accounts that belong to the same legal entity and are under the same company account.	BalanceControl	v1
Capital API	Provides endpoints for embedding Adyen Capital into your marketplace or platform.	Capital	v1
Checkout API	Adyen Checkout API provides a simple and flexible way to initiate and authorise online payments. You can use the same integration for payments made with cards (including 3D Secure), mobile wallets, and local payment methods (for example, iDEAL and Sofort).	Checkout	v71
Configuration API	The Configuration API enables you to create a platform where you can onboard your users as account holders and create balance accounts, cards, and business accounts.	BalancePlatform	v2
Data Protection API	Our Data Protection API allows you to process Subject Erasure Requests as mandated in General Data Protection Regulation (GDPR).	DataProtection	v1
Disputes API	You can use the Disputes API to automate the dispute handling process so that you can respond to disputes and chargebacks as soon as they are initiated. The Disputes API lets you retrieve defense reasons, supply and delete defense documents, and accept or defend disputes.	Disputes	v30
Legal Entity Management API	The Legal Entity Management API enables you to manage legal entities that contain information required for verification	LegalEntityManagement	v4
Management API	Configure and manage your Adyen company and merchant accounts, stores, and payment terminals.	Management	v3
Payments API	A set of API endpoints that allow you to initiate, settle, and modify payments on the Adyen payments platform. You can use the API to accept card payments (including One-Click and 3D Secure), bank transfers, ewallets, and many other payment methods.	Payments	v68
Payments App API	The Payments App API is used to Board and manage the Adyen Payments App on your Android mobile devices.	PaymentsAppApi	v1
POS Mobile API	The POS Mobile API is used in the mutual authentication flow between an Adyen Android or iOS POS Mobile SDK and the Adyen payments platform. Use instead SoftPOS configuration API.	POS Mobile	v68
Payouts API	A set of API endpoints that allow you to store payout details, confirm, or decline a payout. Check Payouts and Payments guide.	Payout	v68
Recurring API	The Recurring APIs allow you to manage and remove your tokens or saved payment details. Tokens should be created with validation during a payment request.	Recurring	v68
Session Authentication API	Create and manage the JSON Web Tokens (JWT) required for integrating Onboarding and Platform Experience components.	SessionAuthentication	v1
Stored Value API	Manage both online and point-of-sale gift cards and other stored-value cards.	StoredValue	v46
Terminal API (Cloud communications)	Our point-of-sale integration.	Cloud-based Terminal API	v1
Terminal API (Local communications)	Our point-of-sale integration.	Local-based Terminal API	v1
Transfers API	The Transfers API provides endpoints that you can use to get information about all your transactions, move funds within your balance platform or send funds from your balance platform to a transfer instrument.	Transfers	v4

Supported Webhook versions

The library supports all webhooks under the following model directories:

Webhooks	Description	Model Name	Supported Version
Authentication Webhooks	You can use the same integration for payments made with cards (including 3D Secure), mobile wallets, and local payment methods (for example, iDEAL and Sofort).	AcsWebhooks	v1
Balance Webhooks	Adyen sends webhooks to inform you of balance changes in your balance platform.	BalanceWebhooks	v1
Configuration Webhooks	You can use these webhooks to build your implementation. For example, you can use this information to update internal statuses when the status of a capability is changed.	ConfigurationWebhooks	v2
Management Webhooks	Adyen uses webhooks to inform your system about events that happen with your Adyen company and merchant accounts, stores, payment terminals, and payment methods when using Management API.	ManagementWebhooks	v3
Negative Balance Warning Webhooks	Adyen sends this webhook to inform you about a balance account whose balance has been negative for a given number of days.	NegativeBalanceWarningWebhooks	v1
Notification Webhooks	We use webhooks to send you updates about payment status updates, newly available reports, and other events that you can subscribe to. For more information, refer to our documentation	Notification	v1
Relayed Authorization Webhooks	Adyen sends webhooks to inform your system about events related to transaction authorizations.	RelayedAuthorizationWebhooks	v4
Report Webhooks	You can download reports programmatically by making an HTTP GET request, or manually from your Balance Platform Customer Area	ReportWebhooks	v1
Tokenization Webhooks	Adyen sends webhooks to inform you about the creation and changes to the recurring tokens.	TokenizationWebhooks	v1
Transaction Webhooks	Adyen sends webhooks to inform your system about incoming and outgoing transfers in your platform. You can use these webhooks to build your implementation. For example, you can use this information to update balances in your own dashboards or to keep track of incoming funds.	TransactionWebhooks	v4
Transfer Webhooks	You can use these webhooks to build your implementation. For example, you can use this information to update balances in your own dashboards or to keep track of incoming funds.	TransferWebhooks	v4

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 8.0

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

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.Checkout.Models;
using Adyen.Checkout.Services;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Adyen.Core.Extensions;
using Adyen.Checkout.Extensions;
using AdyenEnvironment = Adyen.Core.Model.Environment;

IHost host = Host.CreateDefaultBuilder()
          .ConfigureCheckout(
              (context, services, config) =>
              {
                  config.ConfigureAdyenOptions(options =>
                  {
                      options.AdyenApiKey = context.Configuration["ADYEN_API_KEY"];
                      options.Environment = AdyenEnvironment.Test;
                  });

                  services.AddPaymentsService();
              })
          .Build();

var paymentsService = host.Services.GetRequiredService<IPaymentsService>();

var request = new PaymentRequest(
    amount: new Amount("EUR", 1999),
    merchantAccount: "MY_MERCHANT_ACCOUNT",
    reference: "reference",
    returnUrl: "https://adyen.com/",
    paymentMethod: new CheckoutPaymentMethod(
        new CardDetails(
            type: CardDetails.TypeEnum.Scheme,
            encryptedCardNumber: "test_4111111111111111",
            encryptedExpiryMonth: "test_03",
            encryptedExpiryYear: "test_2030",
            encryptedSecurityCode: "test_737",
            holderName: "John Smith"
            )
        )
    );

var response = await paymentsService.PaymentsAsync(request);
if (response.TryDeserializeOkResponse(out var result);
{
    Console.WriteLine(result); // result.ResultCode 
}

Use the RequestOptions object to pass additional headers like the IdempotencyKey or other custom request header:

var response = await paymentsService.PaymentsAsync(request, new RequestOptions().AddIdempotencyKey(Guid.NewGuid().ToString()));

Serializing and Deserializing JSON Strings

The library uses custom JSON converters for all model types (handling oneOf polymorphism, optional-field omission, enum mapping, etc.). These converters are registered in the JsonSerializerOptionsProvider that is set up by the DI host. Always pass jsonSerializerOptionsProvider.Options when calling JsonSerializer.Serialize or JsonSerializer.Deserialize — using the default options will produce incorrect JSON (e.g. nested action wrappers, unexpected null fields).

A common use case is serializing or deserializing JSON strings when working with Drop-in/Components. First, build the host and resolve the JsonSerializerOptionsProvider from the service container:

using Adyen.Checkout.Client;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System.Text.Json;
using Adyen.Checkout.Models;

IHost host = Host.CreateDefaultBuilder()
          .ConfigureCheckout(
              (context, services, config) =>
              {
                  config.ConfigureAdyenOptions(options =>
                  {
                      options.AdyenApiKey = context.Configuration["ADYEN_API_KEY"];
                      options.Environment = AdyenEnvironment.Test;
                  });
              })
          .Build();

var jsonSerializerOptionsProvider = host.Services.GetRequiredService<JsonSerializerOptionsProvider>();

// Deserialize using the library's options
var paymentRequest = JsonSerializer.Deserialize<PaymentRequest>("YOUR_JSON_STRING", jsonSerializerOptionsProvider.Options);

// Serialize using the library's options
var paymentResponse = new PaymentResponse(); // Replace with your actual PaymentResponse object
var json = JsonSerializer.Serialize(paymentResponse, jsonSerializerOptionsProvider.Options);

Logging response bodies

Here's an example how you can log API responses using {{classname}}Events. Consider logging responses only on TEST to prevent logging confidential data.

In case of Payments the snippet would be:

var events = new PaymentsEvents;
services.AddSingleton(events);

// Create a new logger

events.OnPayments += (sender, eventArgs) =>
{
    ApiResponse apiResponse = eventArgs.ApiResponse;
    logger.LogInformation("{TotalSeconds,-9} | {Path} | {StatusCode} |", (apiResponse.DownloadedAt - apiResponse.RequestedAt).TotalSeconds, apiResponse.Path, apiResponse.StatusCode);
};

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,
    new SaleToPoiMessageSerializer(),
    new SaleToPoiMessageSecuredEncryptor(),
    new SaleToPoiMessageSecuredSerializer()
);
// 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 webhooks

The library supports three categories of webhooks, each with a different handler and HMAC validation approach.

1. Payment webhooks

Payment webhooks (classic notifications) use IWebhooksHandler. HMAC validation here takes a NotificationRequestItem object.

using Adyen.Webhooks.Models;
using Adyen.Webhooks.Handlers;
using Adyen.Webhooks.Extensions;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;

IHost host = Host.CreateDefaultBuilder()
    .ConfigureWebhooks(
        (context, services, config) =>
        {
            config.ConfigureAdyenOptions(options =>
            {
                options.AdyenHmacKey = context.Configuration["ADYEN_HMAC_KEY"];
            });
            services.AddWebhooksHandler();
        })
    .Build();

var handler = host.Services.GetRequiredService<IWebhooksHandler>();
NotificationRequest notificationRequest = handler.DeserializeNotificationRequest(json);

foreach (NotificationRequestItem item in notificationRequest.NotificationItems)
{
    if (handler.IsValidHmacSignature(item))
    {
        // Your logic here based on the notification item
    }
}

2. Platform webhooks

Platform webhooks (e.g. Authentication, Configuration, Balance, Transfer, Tokenization webhooks) use dedicated handlers per webhook type. HMAC validation takes the raw JSON string — the same bytes as received in the HTTP request body.

Important: Do not use ASP.NET Core automatic model binding (e.g. [FromBody] MyWebhookRequest) for these endpoints. Re-serializing a deserialized object may produce different JSON and invalidate the signature. Read the raw request body manually instead:

[HttpPost("api/webhooks/tokenization")]
public async Task<IActionResult> ProcessTokenizationWebhook()
{
    using var reader = new StreamReader(Request.Body);
    string json = await reader.ReadToEndAsync();

    if (!_handler.IsValidHmacSignature(json, Request.Headers["HmacSignature"]))
        return Unauthorized();

    TokenizationDisabledDetailsNotificationRequest r =
        _handler.DeserializeTokenizationDisabledDetailsNotificationRequest(json);
    // Your logic here
}

Example using Authentication webhooks (AcsWebhooks):

using Adyen.AcsWebhooks.Models;
using Adyen.AcsWebhooks.Handlers;
using Adyen.AcsWebhooks.Extensions;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;

IHost host = Host.CreateDefaultBuilder()
    .ConfigureAcsWebhooks(
        (context, services, config) =>
        {
            config.ConfigureAdyenOptions(options =>
            {
                options.AdyenHmacKey = context.Configuration["ADYEN_HMAC_KEY"];
            });
            services.AddAcsWebhooksHandler();
        })
    .Build();

var handler = host.Services.GetRequiredService<IAcsWebhooksHandler>();

// webhookPayload is the raw JSON string from the HTTP request body
if (handler.IsValidHmacSignature(webhookPayload, "hmacSignature from header"))
{
    AuthenticationNotificationRequest r = handler.DeserializeAuthenticationNotificationRequest(webhookPayload);
    // Your logic here based on the deserialized webhook
}

3. Management webhooks

Management webhooks follow the same raw-JSON HMAC validation approach as platform webhooks:

using Adyen.ManagementWebhooks.Extensions;
using Adyen.ManagementWebhooks.Models;
using Adyen.ManagementWebhooks.Handlers;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;

IHost host = Host.CreateDefaultBuilder()
    .ConfigureManagementWebhooks(
        (context, services, config) =>
        {
            config.ConfigureAdyenOptions(options =>
            {
                options.AdyenHmacKey = context.Configuration["ADYEN_HMAC_KEY"];
            });
            services.AddManagementWebhooksHandler();
        })
    .Build();

var handler = host.Services.GetRequiredService<IManagementWebhooksHandler>();

// webhookPayload is the raw JSON string from the HTTP request body
if (handler.IsValidHmacSignature(webhookPayload, "hmacSignature from header"))
{
    MerchantCreatedNotificationRequest r = handler.DeserializeMerchantCreatedNotificationRequest(webhookPayload);
    // Your logic here based on the deserialized webhook
}

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