This is the officially supported .NET library for using Adyen's APIs.
The library supports all APIs under the following services:
API | Description | Service Name | Supported version |
---|---|---|---|
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 | v70 |
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 |
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 |
Payouts API | A set of API endpoints that allow you to store payout details, confirm, or decline a payout. | Payouts | v68 |
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 |
Stored Value API | Manage both online and point-of-sale gift cards and other stored-value cards. | StoredValue | v46 |
Legal Entity Management API | The Legal Entity Management API enables you to manage legal entities that contain information required for verification | LegalEntityManagement | v3 |
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 | v3 |
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 |
Data Protection API | Our Data Protection API allows you to process Subject Erasure Requests as mandated in General Data Protection Regulation (GDPR). | DataProtection | v1 |
Terminal API (Cloud communications) | Our point-of-sale integration. | Cloud-based Terminal API | Cloud-based Terminal API |
Terminal API (Local communications) | Our point-of-sale integration. | Local-based Terminal API | Local-based Terminal API |
POS Terminal Management API | This API provides endpoints for managing your point-of-sale (POS) payment terminals. You can use the API to obtain information about a specific terminal, retrieve overviews of your terminals and stores, and assign terminals to a merchant account or store. | POSTerminalManagement | v1 |
For more information, refer to our documentation or the API Explorer.
- Adyen test account
- API key. For testing, your API credential needs to have the API PCI Payments role.
- Adyen dotnet API Library supports .net standard 2.0 and above
- In order for Adyen dotnet 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
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
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 = "your-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 paymentsRequest = 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(paymentsRequest);
Or in case you would like to make an asynchronous /payments call with idempotency key and cancellation token, the last line would be instead:
Task<PaymentResponse> paymentResponse = checkout.PaymentsAsync(
paymentRequest,
requestOptions: myIdempotencyKey,
cancellationToken: myCancellationToken);
Navigate to adyen-dotnet-api-library folder and run the following commands.
dotnet build
dotnet test
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. The Endpoints are available as contacts in ClientConfig For more information please read our documentation
//Example for EU based Endpoint Syncronous
using Adyen;
using Adyen.Constants;
var config = new Config
{
XApiKey = "Your merchant XAPI key",
CloudApiEndPoint = ClientConfig.CloudApiEndPointEULive
};
var client = new Client(config);
To parse the terminal API notifications, please 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);
using System;
using Adyen.Model.Nexo;
using Adyen.Model.Nexo.Message;
using Adyen.Service;
using Environment = Adyen.Model.Environment;
namespace Adyen.Terminal
{
public static class Program
{
private static string XApiKey = "YOUR-API-KEY";
private static void Main(string[] args)
{
var client = new Client(XApiKey, Environment.Test);
TerminalCloudApi terminalCloudApi = new TerminalCloudApi(client);
SaleToPOIResponse response = terminalCloudApi.TerminalRequestSync(PaymentRequest());
PaymentResponse paymentResponse = (PaymentResponse) response.MessagePayload;
Console.WriteLine(paymentResponse.Response.Result);
}
private static SaleToPOIRequest PaymentRequest()
{
var serviceID = "SERVICE_ID"; // ServiceId should be unique for every request
var saleID = "SALE_ID";
var POIID = "SERIAL_NUMBER";
var transactionID = "123459";
var 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(10.9)
},
},
}
};
return saleToPOIRequest;
}
}
}
The request and response payloads are identical to the Cloud Terminal API, however an additional encryption details object is required to send the requests.
var encryptionCredentialDetails = new EncryptionCredentialDetails
{
AdyenCryptoVersion = 1,
KeyIdentifier = "CryptoKeyIdentifier12345",
Password = "p@ssw0rd123456"
};
var config = new Config
{
Environment = Model.Environment.Live,
LocalTerminalApiEndpoint = @"https://_terminal_:8443/nexo/"
};
var client = new Client(config);
var terminalLocalApi = new TerminalLocalApi(client);
var saleToPOIResponse = terminalLocalApi.TerminalRequest(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.
var client = new Client(config);
var terminalLocalApiUnencrypted = new TerminalLocalApiUnencrypted(client);
var saleToPOIResponse = terminalLocalApiUnencrypted.TerminalRequest(paymentRequest);
To parse the terminal API notifications, please 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);
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.
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.
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.
This repository is available under the MIT license.