• Stars
    star
    99
  • Rank 331,238 (Top 7 %)
  • Language
    C#
  • License
    MIT License
  • Created over 6 years ago
  • Updated 6 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Adyen API Library for .NET

NET api

Adyen .NET API Library

nuget nuget .NET Core

This is the officially supported .NET library for using Adyen's APIs.

Supported API versions

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 v71
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
Management API Configure and manage your Adyen company and merchant accounts, stores, and payment terminals. Management 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 v4
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
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
Classic Platforms Account API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. PlatformsAccount v6
Classic Platforms Fund API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. PlatformsFund v6
Classic Platforms Hosted Onboarding Page API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. PlatformsHostedOnboardingPage v6
Classic Platforms Notification Configuration API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. PlatformsNotificationConfiguration v6
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

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
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 v1
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
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
Report Webhooks You can download reports programmatically by making an HTTP GET request, or manually from your Balance Platform Customer Area ReportWebhooks v1
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
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
Classic Platform Webhooks The Notification API sends notifications to the endpoints specified in a given subscription. Subscriptions are managed through the Notification Configuration API. The API specifications listed here detail the format of each notification. PlatformWebhooks v6

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

Prerequisites

  • 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

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;
    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);

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

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. 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);

Example Cloud Terminal API integration

using System;
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 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;
        }
    }
}

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.

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);

Since the terminal API CardAcquisition AdditionalResponse could be either based64 encoded string or key-value pair, there is a helper class to deserialise it to a custom model AdditionalResponse.

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("yourHmacKey", "yourHmacSignature", 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

More Repositories

1

adyen-web

Adyen Web Drop-in and Components
TypeScript
163
star
2

adyen-ios

Adyen iOS Drop-in and Components
Swift
148
star
3

adyen-magento2

Adyen Payment plugin for Magento2
PHP
145
star
4

adyen-php-api-library

Adyen API Library for PHP
PHP
144
star
5

adyen-android

Adyen Android Drop-in and Components
Kotlin
113
star
6

adyen-java-api-library

Adyen API Library for Java
Java
107
star
7

adyen-node-api-library

Adyen API Library for Node.js
TypeScript
96
star
8

adyen-salesforce-commerce-cloud

Salesforce Commerce Cloud (formerly Demandware)
JavaScript
85
star
9

adyen-openapi

OpenAPI specification for the Adyen APIs
65
star
10

adyen-python-api-library

Adyen API Library for Python
Python
57
star
11

adyen-components-js-sample-code

Sample code of Adyen Components
JavaScript
53
star
12

adyen-go-api-library

Adyen API Library for Go
Go
49
star
13

adyen-ruby-api-library

Adyen API Library for Ruby
Ruby
45
star
14

adyen-commercetools

commercetools-adyen-integration provides an integration between the commercetools and Adyen payment service provider based on the concept of Adyen Web Components.
JavaScript
43
star
15

adyen-react-native

Adyen React Native
Kotlin
37
star
16

adyen-barcoder-ios

Use Verifone Barcode scanner over MFi
Swift
30
star
17

lume

Lume is a component library for visual representations of data, built for Vue with D3.
TypeScript
29
star
18

adyen-cse-ios

[Deprecated] Sample code for client-side encryption on iOS
Objective-C
28
star
19

adyen-3ds2-android

27
star
20

adyen-hybris

Adyen Payment plugin for Hybris
Java
23
star
21

adyen-3ds2-js-utils

Helper functions to get 3DS 2.0 integrated on the front-end
JavaScript
21
star
22

adyen-cse-android

[Deprecated] Sample code for client-side encryption on Android
Java
21
star
23

adyen-shopware6

Adyen Payment plugin for Shopware 6
PHP
21
star
24

adyen-3ds2-ios

Objective-C
20
star
25

adyen-postgres-partitioning

Functions to manage partitions in PostgreSQL with minimal impact for applications
PLpgSQL
20
star
26

adyen-cse-web

[DEPRECATED] Client-side encryption on JavaScript
JavaScript
15
star
27

adyen-prestashop

Adyen Payment plugin for Prestashop
PHP
13
star
28

feast-spark-offline-store

This repo contains a plugin for feast to run an offline store on Spark
Python
13
star
29

adyen-shopware5

PHP
11
star
30

adyen-flutter

Dart
11
star
31

adyen-postman

Postman files for the Adyen APIs
Shell
9
star
32

adyen-secured-fields-sample-code

JavaScript
9
star
33

adyen-pos-mobile-ios

Adyen POS Mobile SDK for iOS enabling the integration of TapToPay and the NYC1 card reader.
HTML
8
star
34

adyen-terminal-api-ios

Adyen Terminal API for iOS
Swift
8
star
35

adyen-oracle-commerce-cloud

Adyen plugin for Oracle Commerce Cloud
JavaScript
8
star
36

adyen-salesforce-b2b-commerce

Adyen app for Salesforce B2B Commerce
Apex
7
star
37

adyen-web-sdk-sample-code

Sample code for Adyen Web SDK
PHP
7
star
38

adyen-magento2-express-checkout

Adyen Magento 2 Express Checkout Module
PHP
6
star
39

adyen-wechatpay-ios

Adyen WeChat Pay SDK Wrapper
Objective-C
5
star
40

adyen-openapi-generator

Generate OpenApi models from Adyen Services APIs
JavaScript
5
star
41

php-webhook-module

PHP Webhook Helper Module for Adyen Payment Integrations
PHP
4
star
42

adyen-salesforce-headless-commerce-pwa

B2C Commerce Headless Integration Composable Storefront
JavaScript
4
star
43

adyen-integration-tools-tests

JavaScript
3
star
44

adyen-networking-ios

Swift
3
star
45

adyen-document-viewer

Adyen Document Viewer
TypeScript
3
star
46

.github

Organization-wide community health files in the @adyen organization
3
star
47

adyen-authentication-ios

AdyenAuthentication SDK Provides reusable and easy to use two factor authentication for security sensitive use cases like banking, issuing and PSD2 strong customer authentication.
C++
3
star
48

adyen-apple-pay-provisioning-ios

Resources to help integrate Apple Pay Provisioning for Adyen issued card partners
C++
1
star
49

adyen-pos-mobile-android

Kotlin
1
star
50

adyen-apex-api-library

Adyen API Library for Apex
Apex
1
star
51

adyen-salesforce-b2b-lightning

Apex
1
star