DEV Community: Kwok He Chu

Sweeps on the Adyen Balance Platform for Developers

Kwok He Chu — Mon, 20 Nov 2023 15:18:06 +0000

TL;DR In this blog post, we show you how you can configure sweeps to automate payouts to your user's verified bank accounts. We’ll explain the different types of sweeps, outline the scenarios they are designed for, and explain the process of setting up sweeps through either the Customer Area or using APIs.

Adyen for Platforms offers a comprehensive solution tailored for marketplaces that aim to deliver a flexible, robust and fully-featured platform to support their merchants and end users on a large scale. The core of every successful platform is the unique relationship built over time between the platform and its customers. Merchants process a vast number of complex transactions everyday, with different attributes and configurations, like currency, payment methods, split amounts and fees. They also need easy access to their funds, making fast and reliable payouts an indispensable tool of the platform.

In this blog, we’ll answer the following questions:

What are sweeps?
What types of sweeps exist and their use cases.
How to configure sweeps.

What are sweeps?

Let’s start with an example. Jan runs a very successful marketplace that allows users to buy and sell their cars in Amsterdam. As their user base grows, Jan is having trouble with making sure his users are paid out consistently at a set interval. This has proven quite troublesome as more and more users join their marketplace. Jan is looking for some kind of automation. This is where sweeps come into play, an Adyen feature that allows him full control of his payout functionality. Sweeps pull in or push out funds from a balance account based on a predefined schedule, amount, currency, and a source or a destination.

Before we delve into the specifics, let’s clarify two key terms:

Account holder: This refers to the user entity within the balance platform. Depending on your account structure, the account holder can either be your company, or your customers.
Balance account: This is the account where funds are held for an account holder. All financial activity happens through balance accounts. Each account holder can have one or more balance accounts for accounting flexibility, but in most use cases, a single balance account is sufficient.

An account holder can be one of the following legal entities: Individual, Business, Nonprofit, Partnership, or Public company. To create an account holder, send a request to the /createAccountHolder endpoint. Refer to this documentation page to understand the different request parameters for each legal entity.

Account holders rely on the platforms for the benefit of their business but also for features like reliability and ease of access to their funds. The skeleton of reliability, trust and ease are equal parts of a massive pillar in this business model. The core of this trust relies on the payout functionality being spot on and easy for both the account holders and the platforms to configure and customize based on their needs.

What types of sweeps exist?

A sweep automatically pushes out or pulls in funds from a balance account based on a predefined schedule, amount, and source or destination. There are two types of sweeps that exist as part of the Adyen Balance Platform.

The push sweep
The pull sweep

The push sweep

The push sweep is the type of sweep used for configuring payouts. Platforms use this type of sweep to send a payout to the account holders based on a configurable schedule and other additional parameters such as the currency.

The push sweep is configured for the balance account of the account holder. This means that an account holder with multiple balance accounts can define sweeps with different configurations, based on the preferences of the business case.

The pull sweep

The pull sweep is the type of sweep used for the auto-funding functionality on the balance platform for account holders. Platforms can use this type of sweep to pull funds into a designated balance account when a certain threshold is reached.

Auto-funding use cases are those as old as time, where an account holder needs funds to process refunds but is below a threshold to process them successfully. At this point, the autofunding functionality configured via a pull sweep comes to the rescue by pulling in funds for operational ease.

How to configure sweeps

You can configure sweeps for balance accounts through two primary methods:

Customer Area
API functionality

Customer Area

You can directly configure sweeps for balance accounts via the Customer Area by performing the following steps:

Log into the Customer Area using your credentials.
Navigate to the account holder.
Navigate to the balance account you want to configure the sweep for.
On the balance account page, use the button as shown below to add a sweep configuration for the balance account. Choose the type of sweep you would like to configure. For the purpose of this example, we will be proceeding with the push sweeps for payouts.

Once the type of sweep has been selected, you will proceed to a page with an extensive range of customization options that allow you to tailor the structure of your sweep according to your preferences.

Finally confirm the configuration by clicking next and viewing the summary of the sweep you are ready to create.

API functionality

For developers, it is possible to use the Adyen Platform Configuration APIs for automating the sweep configurations for account holders.

You can create a sweep by specifying its type and send a POST request to the /balanceAccounts/{balanceAccountId}/sweeps endpoint. You can configure the request parameters in the body of the API call as shown below. For a more detailed overview on what each of these parameters do, read our API documentation here.

Create a push sweep using a POST request:

{
    "counterparty": {
      "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B" // The destination of the funds
    },
    "currency": "EUR", // The currency of the sweep
    "schedule": {
      "cronExpression": "30 9 * * 3", // The cron expression for the schedule when the sweep is validated
      "type": "cron" // The schedule when the sweep is evaluated
    },
    "type": "push", // The direction of the sweep
    "description": "Internal funds transfer every Wednesday at 0930"
}

A successful request returns the newly created push sweep.

{
  "id": "SWPC4233T22337JX5JVZGSP39S4M7K",
  "schedule": {
    "type": "cron",
    "cronExpression": "30 9 * * 3"
  },
  "status": "active",
  "targetAmount": {
    "currency": "EUR",
    "value": 0
  },
  "triggerAmount": {
    "currency": "EUR",
    "value": 0
  },
  "type": "push",
  "counterparty": {
    "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B"
  },
  "currency": "EUR",
  "description": "Internal funds transfer every Wednesday at 0930"
}

Adyen will also asynchronously send the "balancePlatform.balanceAccountSweep.created" webhook with the sweep response. You can find an example of the webhook payload below.

{
  "data": {
    "balancePlatform": "YOUR_BALANCE_PLATFORM",
    "accountId": "BA3233T22337JX5JVZGSPD9B9",
    "sweep": {
      "id": "SWPC4233T22337JX5JVZGSP39S4M7K",
      "schedule": {
        "type": "weekly"
      },
      "status": "active",
      "targetAmount": {
        "currency": "EUR",
        "value": 0
      },
      "triggerAmount": {
        "currency": "EUR",
        "value": 0
      },
      "type": "push",
      "counterparty": {
        "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B"
      },
      "currency": "EUR"
    }
  },
  "environment": "test",
  "type": "balancePlatform.balanceAccountSweep.created"
}

Summary

In summary, we've covered sweeps using a real-life example and discussed the two types of sweeps: push and pull. We've shown how to set these up through the Adyen Customer Area or using API calls. Going back to our introduction, Jan now has a better understanding of how this works and he can now feel more confident about the functionality as it allows him just the right amount of control over the payouts for his customers. This means that his users can continue selling and buying cars on his platform without having to worry whether they get their money on time.

Are you looking for more developer-related content? Have a look at developers.adyen.com today or let us know on Twitter what you’d like to see next!

Using Adyen to Implement Payment Pre-authorizations and Authorization Adjustments

Kwok He Chu — Wed, 18 Oct 2023 16:43:20 +0000

This technical blog post explains how developers can implement a hotel booking payment process using Adyen's API. It covers pre-authorizations, amount adjustments, extending authorization expiry dates, capturing payments, refunding payments and webhook payloads.

At Adyen, we understand that modern businesses across different industries require various payment solutions for different use cases. In a basic payment flow, the amount from your payment request is authorized and then captured. But sometimes you may want to change the amount or extend the length of the authorization. This is known as a pre-authorization, followed by an authorization adjustment.

Introduction

The use of authorization adjustment in various industries may differ. One could increase the amount, decrease the amount after a successful pre-authorization or extend the expiry date of the authorization.

In the hospitality sector, for example, hotels use pre-authorizations to facilitate payment processes before a guest checks into their hotel. During their stay, if the guest incurs additional expenses at the hotel, these expenses can be added to the pre-authorized amount by adjusting the authorization. Once the guest checks out, the hotel captures the final amount or, optionally, cancels the payment if the guest prefers to settle their bill with a different payment method.

In other cases such as taxi rides, car rentals, or parking, you can use pre-authorizations to handle situations where the final amount for the service is not known at the time of payment.

Another common use-case is in the United States. As tax regulation can differ widely between states, it is common that the final amount of an order for clothing and apparel deliveries has to be adjusted due to tax regulation changes in applicable tax due to last minute changes of origin or destination of the package.

Overview

Let’s start by taking a look at a high-level technical overview where a guest reserves a hotel room for $249.99 and chooses to accumulate extra costs during their stay. Here’s an overview of the three main request:

Pre-authorization request: The merchant initiates a pre-authorization request of $249.99.
Authorization adjustment request: Once the pre-authorization is successfully authorized, the merchant sends an authorization adjustment request of $500.
- Extension request: Once a pre-authorization request is successfully authorized, the merchant can optionally extend the authorization to increase the expiry window of this authorization.
Capture request: Once the authorization adjustment is successful. The merchant confirms the final payment by sending a capture request of $500. This will finalize the payment.
- Reversal request: Optionally, a merchant can cancel or refund the authorization with a reversal request.

1. Pre-authorization

First, we create a pre-authorization request to the /payments endpoint. We specify a merchant reference to keep track of the payment throughout the whole payment lifecycle.

Pre-authorization request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d", // Your unique reference
  "channel": "Web",
  "amount": {
    "currency": "USD",
    "value": 24999 // 249.99 USD in minor units
  },
  "returnUrl": "https://your-company.example.com/api/handleRedirect?orderRef=7a5d8be7-cceb-4442-b17f-3a10a8fa396d", // We redirect to our domain
  "countryCode": "NL",
  "paymentMethod": { 
     "type": "scheme",
      "number":"4111111111111111",
      "cvc":"737",
      "expiryMonth":"03",
      "expiryYear":"2023",
      "holderName":"John Smith"
  },
  "additionalData": {
    "allow3DS2": "true",
    "authorisationType": "PreAuth"
  }
}

A successful response contains the “Authorised” result code.

Pre-authorization response:

{
   "additionalData" : {
      // …
   },
   "pspReference" : "TJ5MXF5SK3RZNN82",
   "resultCode" : "Authorised",
   "amount" : {
      "currency" : "USD",
      "value" : 24999 // 249.99 USD in minor units
   },
   "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
   "paymentMethod" : {
      "brand" : "visa",
      "type" : "scheme"
   }
}

Adyen will send a webhook asynchronously, check the notification success-flag to see whether the authorization has succeeded.

"AUTHORISATION" webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
      // …
               "hmacSignature" : ""**********************",",
             // …
            },
            "amount" : {
               "currency" : "USD",
               "value" : 24999 // 249.99 USD in minor units
            },
            "eventCode" : "AUTHORISATION",
            "eventDate" : "2023-07-06T15:07:38+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "operations" : [
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "paymentMethod" : "visa",
            "pspReference" : "TJ5MXF5SK3RZNN82",
            "reason" : "052031:1111:03\/2030",
            "success" : "true"
         }
      }
   ]
}

The webhook contains a PspReference that can be used in the subsequent authorization adjustment call.

2. Authorization Adjustment

To adjust the amount asynchronously, we create a request object to the /payments/TJ5MXF5SK3RZNN82/amountUpdate endpoint. The

Authorization adjustment request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 50000 // 500 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Authorization adjustment response:

{
    "industryUsage": "delayedCharge",
    "status": "received",
    "amount": {
        "currency": "USD",
        "value": 50000
    },
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "paymentPspReference": "TJ5MXF5SK3RZNN82",
    "pspReference": "WBG6F4K25HXXGN82",
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

The call is received by Adyen when the response status matches the expected "received" status.

Later on, Adyen sends a webhook with an “AUTHORISATION_ADJUSTMENT” event code that contains the result of the authorization adjustment. Check the success-flag to see whether the adjustment has been successful and save this accordingly in your backend.

"AUTHORISATION_ADJUSTMENT" webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : "********************",
               "bookingDate" : "********************" // This is a DateTime
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000
            },
            "eventCode" : "AUTHORISATION_ADJUSTMENT",
            "eventDate" : "2023-07-06T16:01:28+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "WBG6F4K25HXXGN82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

Validity and authorization expiry dates

Card schemes set specific rules around which businesses (f.e. travel, restaurants, public transportation) are able to adjust an authorization. Your merchant category code (MCC) determines the eligibility, together with the card scheme. You can find an extensive table on availability here.

Adyen expires authorization requests automatically after 28 days from the day the payment is authorized. Note: Please refer to the documentation to see a table as these vary per card scheme. The default expiry period can be adjusted and ensures that Adyen does not automatically expire the authorization after the default 28 days. Our support team can configure this for your merchant account.

If you try to capture a transaction after the allowed time, it's more likely to fail. However, you can often capture a payment successfully after an authorization has expired. Depending on the card scheme, there can be a fee for late captures, and an increase in interchange and/or scheme fees charged for the transaction. There's also a higher risk of chargebacks from card holders.

To manually extend the expiry date of an authorization, make a request to the same endpoint but leave the amount unchanged.

Authorization adjustment extend request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 24999 // 249.99 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Authorization adjustment extend response:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 24999 // 249.99 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

“AUTHORIZATION_ADJUSTMENT” extend webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : "********************",
               "bookingDate" : "********************" // This is a DateTime
            },
            "amount" : {
               "currency" : "USD",
               "value" : 24999
            },
            "eventCode" : "AUTHORISATION_ADJUSTMENT",
            "eventDate" : "2023-07-06T16:21:28+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "WBG6F4K25HXXGN82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

3. Capture

To finalize the payment, make sure you’ve received the webhook for each authorization adjustment that you’ve made. Make a request to the endpoint /payments/TJ5MXF5SK3RZNN82/captures with the final amount of $500 that you wish to capture. Notice that we're using the PspReference of the initial pre-authorization.

Capture request:

{
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "amount":{
          "Currency": "USD",
          "Value": 50000 // 500 USD in minor units
       },
   "reference":"7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Capture response:

{
   "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
   "paymentPspReference" : "TJ5MXF5SK3RZNN82",
   "pspReference" : "FVNHBFGDFVTFWR82",
   "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
   "status" : "received",
   "amount" : {
      "currency" : "USD",
      "value" : 50000 // 500 USD in minor units
   }
}

Adyen sends a webhook with the event code “CAPTURE” when successful or unsuccessful. In some rare cases a "CAPTURE_FAILED" event code (with a success-flag) can occur as well. This can happen because it was either rejected by a card scheme, technical issue, or when capture expires. For a full list of failed capture reasons, refer to this documentation page on what to do next.

Successful “CAPTURE” webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : ""********************"",
               "bookingDate" : "********************"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000 // 500 USD in minor units
            },
            "eventCode" : "CAPTURE",
            "eventDate" : "2023-07-06T16:50:16+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "FVNHBFGDFVTFWR82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

If you use an invalid PspReference (f.e. when you use the PspReference from an authorization adjustment response), you’ll receive a webhook containing a "transaction not found" message. Likewise, if you attempt to recapture a payment that has already been captured, you will receive an unsuccessful webhook notification with the reason field indicating "Insufficient balance on payment."

Unsuccessful “CAPTURE” webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : ""********************"",
               "bookingDate" : "********************"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000
            },
            "eventCode" : "CAPTURE",
            "eventDate" : "2023-07-06T16:45:55+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "WBG6F4K25HXXGN82",
            "pspReference" : "N99H9LX8NV5X8N82",
            "reason" : "Transaction not found",
            "success" : "false"
         }
      }
   ]
}

Reversals
To cancel or refund a payment, send a request to the /payments/TJ5MXF5SK3RZNN82/reversals endpoint. Notice that we're still using the PspReference TJ5MXF5SK3RZNN82 from the initial pre-authorization. This request is useful when you want to return the funds to your guest, but are not certain whether the payment has been captured or not.

This will either:

Cancel the payment – in case it has not yet been captured.
Refund the payment – in case it has already been captured.

Reversal request:

{
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}

Reversal response:

{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "paymentPspReference": "TJ5MXF5SK3RZNN82", // The original pre-authorization pspReference
    "pspReference" : "GF445R8G6L2GWR82",
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
    "status" : "received"
}

“CANCEL_OR_REFUND” webhook

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "modification.action": "refund"
            },
            "amount":{
               "currency": "USD",
               "value": 50000
            },
            "eventCode":"CANCEL_OR_REFUND",
            "eventDate":"2023-07-06T17:25:23+02:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "originalReference":"TJ5MXF5SK3RZNN82", // The original pre-authorization pspreference
            "paymentMethod":"mc",
            "pspReference":"GF795R5G6L2GWR82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

Now that we’ve seen the flow, here’s a diagram containing the success scenarios.

You send a pre-authorization request to Adyen.
After some time, Adyen sends an AUTHORISATION webhook.
A successful AUTHORISATION webhook can be adjusted.
- (3A) A successful AUTHORISATION webhook can be captured.
- (3B) successful AUTHORISATION webhook can be canceled or. refunded
A successful AUTHORISATION_ADJUSTMENT webhook can be captured.
- (4A) A successful AUTHORISATION_ADJUSTMENT webhook can be canceled or refunded.
A successful CAPTURE webhook can be canceled or refunded.
After receiving a successful CANCEL_OR_REFUND webhook, the refund can still be rejected by the card scheme. There are two webhooks that may be sent afterwards.
- REFUND_FAILED webhook.
- REFUNDED_REVERSED webhook.

"REFUND_FAILED" webhook
When Adyen sends a successful REFUND webhook, it means that our validations were successful and we sent the refund request to the card scheme. However, the card scheme can still reject the refund. This can happen even a few days after you submitted the refund request. To handle these failure reasons, refer to our documentation on what to do next.

To test failed refunds, you can make a pre-authorization request and enter the holder name “refund failed”, to test this scenario.

"REFUNDED_REVERSED" webhook
For some payment methods, for example bank transfers, iDEAL, or Bancontact, the status of the payment can change from “REFUND” to “REFUNDED_REVERSED”. This means that the funds have been returned to Adyen, and are back in your account. This can happen, for example, if the bank account is no longer valid.

Below you can find a full chart of the webhooks with the different event codes. Red indicates that the “success”-flag is set to false, while green indicates that the webhook was successful.

You can find a fully working integration-example on our Github page.

Summary

We’ve seen how you can use Adyen pre-authorizations and authorization adjustments to implement a hotel booking use case. We’ve gone over the API responses and webhooks that a developer can encounter. The following steps were described in-depth:

Perform the pre-authorization request
Increase or decrease the amount using authorization adjustments; optionally extend the expiry date of the authorization
Capture the final amount
Perform payment reversals (cancel or refund)

We’re always looking for ways to improve our existing integration examples or build new integrations for our developers.

Have a look at developers.adyen.com today or let us know on Twitter what you’d like to see next!

The Migration Guide to Upgrading to Adyen .NET Library 10.0.0

Kwok He Chu — Thu, 08 Jun 2023 15:40:32 +0000

This migration guide is intended for developers who are planning to upgrade to .NET Adyen Library version 10.0.0. We'll cover new features and breaking changes from 9.x.x to ensure your upgrade goes as smoothly as possible.

The new version allows for an easy integration of new products and features as they become available on the Adyen platform, and it introduces naming conventions that are consistent across other libraries and our Adyen endpoints.

The goal is to make the library comprehensive (all API versions are updated to the latest release, there is support for Adyen for Platforms and Embedded Financial Services), fast (providing built-in methods for JSON processing) and easy (added adapter classes mapping each payment method).

TL;DR: In this migration guide, we'll go over what has changed and why we've made these changes to ensure that developers can migrate as smoothly as possible.

Coding Conventions

The following changes have been implemented to better align with Microsoft's C# Coding Conventions.

1. Interface support on service-level
It's common practice to use names with an I-prefix to indicate that they are interfaces. This helps to distinguish interfaces from classes and other types, and makes it clear that the type represents an interface. For example: IPaymentsService.cs indicates that the type represents an interface for the Payments API. We've introduced these interfaces in our service classes. Developers can make use of these interfaces, which expose only the set of public methods required for integration purposes.

2. Service classes
It's also common practice to suffix classes with -Service on service-level. This helps developers distinguish service classes from other classes such as requests, responses, other models and types. For example: Recurring is now renamed to RecurringService, which now inherits from the IRecurringService interface.

3. Asynchronous methods
To handle asynchronous requests, we've added the -Async()-suffix to all asynchronous methods. On top of that, we allow developers to pass on cancellation tokens to these methods. This enables cooperative cancellation between threads, thread pool work items, or Task objects, freeing up remaining resources if a request is canceled manually or unexpectedly.

4. HttpClient support
System.Net.Http.HttpClient has replaced System.Net.HttpWebRequest to conform to Microsoft's best practices. The System.Net.Http.HttpClient class sends and receives HTTP requests and handles these responses from a resource that can be identified by a URI. An HttpClient instance consists of a collection of settings that are applied to all requests executed by that instance. Additionally, each instance operates its own connection pool, which isolates its requests from others. Starting in .NET Core 2.1, the The underlying SocketsHttpHandler class provides the implementation, making behavior consistent across all platforms when using the HttpClient.

When creating the AdyenClient, developers can now inject their own HttpClient on the constructor level. If a custom HttpClient is not provided, a default one will be provided by the HttpClientFactory. We have also marked username and password authentication as obsolete to ensure best practices when working with our APIs. Instead, it's recommended to pass the API-Key as part of the Config class in the constructor. Here's what the initial client configuration looks like when working with our APIs in .NET:

Example of using direct object instantiation in C#:

var httpClient = new HttpClient(); // Reuse the HttpClient, see below why.

var adyenClient = new Adyen.Client(
   new Config()
   {
      XApiKey = "ADYEN_API_KEY",
      HmacKey = "ADYEN_HMAC_KEY",
      MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
      Environment = Environment.Test
 },
   httpClient // Do not instantiate a new one for every request.
);

Adyen.Service.Checkout.IPaymentsService service = new Adyen.Service.Checkout.PaymentsService(adyenClient);

Note: Please keep in mind that it's best practice to reuse the HttpClient. To prevent socket exhaustion, the HttpClient is intended to be instantiated once per application, rather than per-use. We highly recommend using the HttpClientFactory for this reason and have the factory provide the client. You can read more details here on StackOverflow. We recommend the following for Dependency Injection:

Example instantiation using Dependency Injection in ASP.NET Core:

string httpClientName = "YourCustomHttpClientName";

// Register the Adyen.Client with the HttpClientFactory in ASP.NET Core.

services.AddSingleton(
   new Adyen.Client(
      new Config()
      {
         XApiKey = "ADYEN_API_KEY",,
         HmacKey = "ADYEN_HMAC_KEY",
         MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
         Environment = Environment.Test
      }, 
      provider.GetRequiredService<IHttpClientFactory>(),
      httpClientName
   )
);

// Add the named HttpClient.
services.AddHttpClient(httpClientName, httpClient =>
{
    /// Customize your HttpClient here.
    //using Microsoft.Net.Http.Headers;
    //httpClient.DefaultRequestHeaders.Add("accept", "application/json");
    //httpClient.DefaultRequestHeaders.Add("user-agent", "YourUserAgent");
});

services.AddSingleton<Adyen.Service.Checkout.IPaymentsService, Adyen.Service.Checkout.PaymentsService>();

5. Models generation from OpenAPI specifications
Another significant change is the adoption of OpenAPI-driven code generation.

The models are now generated from the latest OpenAPI specifications. C# classes that map the request and response payloads are now generated using OpenAPI Generator, ensuring that the code complies with the contract, and avoiding errors and inconsistencies. This also ensures that other Ayden libraries will have consistent naming amongst them.

To improve the maintainability of the library easier for the long run, we've removed several properties that are no longer there and reduced boilerplate code. You can find them in our release notes.

With the automation project, our team at Adyen can now deliver faster to our developers. They can use the latest endpoints when including the latest version of the library in their application.

Feel free to take a look at the following model and service-generation. The following new services and respective endpoints have been generated using the OpenAPI specifications:

New endpoints support

Deprecated

Hosted Payment Pages (HPP) has been deprecated and are no longer available. The classic Hosted Payment Pages integration has reached end-of-life and we are no longer processing transactions through HPP.

Quick Cheat Sheet

Most of the services, some examples "Balance", "Payout" or "BinLookup" have been renamed to "BalanceService", "PayoutService" and "BinLookupService" respectively. Because they're quite straightforward to find when applying the above mentioned naming conventions, they're not listed in the table below.

We've highlighted a couple of commonly used services, models and methods that have been moved, and are less trivial to find.

// Before (.NET 9.x.x)
Checkout.cs

// After (.NET 10.x.x) - Renamed
Adyen.Services.Checkout.PaymentsService.cs  // Service
Adyen.Services.Checkout.IPaymentsService.cs // Interface

// Before (.NET 9.x.x)
Checkout.PaymentLinks(…) // Method

// After (.NET 10.x.x) - This has been moved to its own service
Adyen.Services.Checkout.PaymentLinksService.cs  // Service
Adyen.Services.Checkout.IPaymentLinksService.cs // Interface

// Before (.NET 9.x.x)
Recurring.cs

// After (.NET 10.x.x) - Renamed
Adyen.Services.RecurringService.cs  // Service
Adyen.Services.IRecurringService.cs // Interface

// Before (.NET 9.x.x)
Checkout.PaymentsAsync(…) method

// After (.NET 10.x.x)
// Adyen.Model.Checkout.PaymentRequest contains a PaymentMethod parameter.
// When making a payment, using the recurringDetailReference retrieved from tokenization, use: 
PaymentMethod = new CheckoutPaymentMethod(new StoredPaymentMethodDetails(storedPaymentMethodId: recurringDetailReference));

// Before (.NET 9.x.x)
Adyen.Model.Checkout.Details.IPaymentMethodDetails

// After (.NET 10.x.x) - Have a look at our .NET checkout-example-advanced flow 
// on github.com/adyen-examples to see how you can pass this as part of its request.
Adyen.Model.Checkout.CheckoutPaymentMethod

// Before (.NET 9.x.x)
namespace Adyen.Model.Enum.Environment

// After (.NET 10.x.x) - Moved to another namespace
namespace Adyen.Model.Environment

// Before (.NET 9.x.x)
Adyen.Model.Checkout.PaymentsDetailsRequest.cs

// After (.NET 10.x.x) - Renamed
// This will be correctly renamed to PaymentDetailsRequest in a later release
// A `PaymentDetailRequest` model should have an equivalent `PaymentDetailResponse` for consistency
Adyen.Model.Checkout.DetailsRequest.cs

// Before (.NET 9.x.x)
new Adyen.Client(username, password, environment) // or
new Adyen.Client(xapikey, environment)

// After (.NET 10.x.x)
var httpClient = new HttpClient(); // Reuse the HttpClient, we explained the why above.

var client = new Client(
   new Config()
   {
      XApiKey = "ADYEN_API_KEY",
      HmacKey = "ADYEN_HMAC_KEY",
      MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
      Environment = Environment.Test
 },
   httpClient // Do not instantiate a new one for every request.
);

var adyenClient = new Adyen.Client(config);

// Before (.NET 9.x.x)
Adyen.Service.PosPaymentLocalApi
Adyen.Service.PosPaymentCloudApi

// After (.NET 10.x.x) - Using POS with HttpClient:
var httpClient = new HttpClient(
   // See Adyen.HttpClient.HttpClientExtension.cs to configure the certificate.
   HttpClientExtensions.ConfigureHttpMessageHandler(config)
); 

// You can also  optionally configure your HttpClient timeouts here.
// httpClient.Timeout = …;

IPosPaymentLocalApi = new PosPaymentLocalApi(new Client(config, httpClient)); // or
IPosPaymentCloudApi = new PosPaymentCloudApi(new Client(config, httpClient));

// After (.NET 10.x.x) - Setting Local Terminal API endpoint
new Config() {
   // ...
   LocalTerminalApiEndpoint = "https://192.168.1.10:8443/nexo"
   // ...
}

If you have an existing integration implementing one of the Checkout (sessions / payments endpoints), Subscription (tokenization), Pay by Link or Gift Card use cases, you can have a look at the this pull request to see a detailed list of all changes necessary to migrate to v10.0.0.

Feel free to open an issue on GitHub if you're encountering any problems or ping us on Twitter (@AdyenDevs).

Happy migration! 🛠️

Use Adyen Tokenization to Implement Subscriptions in .NET

Kwok He Chu — Fri, 10 Feb 2023 10:18:59 +0000

In this blog post, we’ll explain the concept of Adyen tokenization, its usage, and how you can use tokenization to implement a recurring billing service for your customers. This post comes with an example integration in .NET that can be found on GitHub. Even though we use .NET in this example, the concepts apply to other programming languages as well.

Recurring payments, top-ups, and subscriptions are popular payment flows used by lots of merchants in various industries such as streaming services, Software as a Service (SaaS), and subscription services. In this blog post, we go over the technical details of tokenizing payment details and issuing payment requests on behalf of a shopper.

Payment Service at Adyen

Adyen offers payment services for businesses that operate with subscription models and other recurring payments. We receive payment requests from our merchants, and our systems try to honor the payment authorization. Depending on your use case, the implementation for subscriptions may look differently. Think about the following questions:

Do you want to charge the shopper for the first month?
When do you want to charge the shopper?
What happens when the transaction fails (e.g. insufficient balance or other reasons)? Let’s take a look at these questions in this blog.

If you don’t want to implement and maintain a subscription billing service yourself, we have partnerships with third-providers that offer these types of billing services. You can find our partners on our website.

Tokenization

With Adyen, you can securely store one or more payment details per shopper in the form of tokens. This process is what we refer to as tokenization. There are three ways you can use tokens:

One-off payments: One-off transactions where the cardholder can pay using their previously saved payment details. We refer to this recurring process model in our API as “CardOnFile”.
Subscriptions: Recurring transactions made at regular intervals for a product or a service. We refer to this recurring process model in our API as “Subscription”.
Automatic top-ups (and other non-fixed schedule contracts): Contracts that occur on a non-fixed schedule using stored card details. This includes automatic top-ups when the cardholder's balance drops below a certain amount. We refer to this recurring process model in our API as “UnscheduledCardOnFile”.

Subscription Flow

In the next section, we look at the subscription use case and the flow of events that involve the cardholder, the merchant, and the Adyen platform.

Step 1. After a Customer Initiated Transaction (CIT) we collect payment information from the cardholder.

Step 2. The merchant sends an initial authorisation request to Adyen for tokenization.

Step 3. Adyen replies with the authorisation result.

Note: After step 1, the shopper may be required to perform a Strong Customer Authentication (SCA) step where the shopper authenticates to the issuing bank. SCA is a European requirement introduced to make online payments more secure and reduce fraud. This requirement applies to online payments made in the European Economic Area (EEA), Monaco, and the UK. These levels of authentication involve asking customers for two of the three following: something they know, something they own, and something they are. For more details visit this self-service guide.

Step 4. At a later point in time, Adyen sends the token and the shopper reference through an asynchronous notification (webhook) to the merchant. The merchant should save this token and the shopper reference. These are used to make future payment requests for every billing event.

Step 5. The merchant can now, at a set interval, initiate a payment request on behalf of the customer using the token and the shopper reference. This is known as a Merchant Initiated Transaction (MIT).

Finally, the merchant receives an asynchronous notification (webhook) with the outcome of the payment request.

Let’s see this in action in our .NET integration example. In our example integration we’ve implemented two views.

One view allows the shopper to tokenize their payment details in the payment request.
Another separate view allows an administrator to make payments on behalf of the shopper. Note that in a production environment, you would automate this process. For demo purposes, we allow an administrator to make immediate payments on behalf of the shopper with the press of a button.

Initial payment request

The initial authorisation request is performed using the sessions endpoint. The merchant sends a payment request to Adyen, in our case using the .NET library. This is what the C# request looks like:

/// In CheckoutClient.cs
public async Task<CreateCheckoutSessionResponse> CheckoutSessionsAsync(string shopperReference, CancellationToken cancellationToken)
{
    // Generate a unique Guid for your order.
    var orderRef = Guid.NewGuid();

    // The sessionRequest holds the data you need to send to Adyen.
    var sessionsRequest = new CreateCheckoutSessionRequest();

    // Set the merchant account.
    sessionsRequest.MerchantAccount = _merchantAccount;

    // Make a “0” payment. See Zero Auth section below.
    var amount = new Amount("EUR", 0); 
    sessionsRequest.Amount = amount;
    sessionsRequest.Reference = orderRef.ToString();

    // It’s good practice to send where this request came from
    sessionsRequest.Channel = CreateCheckoutSessionRequest.ChannelEnum.Web;

    // Specify the Shopper Interaction
    sessionsRequest.ShopperInteraction = CreateCheckoutSessionRequest.ShopperInteractionEnum.Ecommerce;

    // Set the RecurringProcessingModel to Subscription
    sessionsRequest.RecurringProcessingModel = CreateCheckoutSessionRequest.RecurringProcessingModelEnum.Subscription;

    // Enable recurring.
    sessionsRequest.EnableRecurring = true;

    // This is an Id that uniquely identifies your shopper.
    sessionsRequest.ShopperReference = shopperReference;

    // Specify the returnUrl that is required for 3ds2 redirect flow
    sessionsRequest.ReturnUrl = $"https://localhost:5001/redirect?orderRef={orderRef}";

    try
    {
        // Sends the requests and returns its response.
        var sessionResponse = await _paymentsService.SessionsAsync(sessionsRequest);
        return sessionResponse;
    }
    catch (Adyen.HttpClient.HttpClientException e)
    {
        _logger.LogError($"Request for Payments failed::\n{e.ResponseBody}\n");
        throw;
    }
}

Note (out-of-scope): For India, we have to specify a Mandate field. See the documentation for more information on which fields to include.

Now that the shopper's payment details are collected, let’s take a look at how Adyen authorizes the initial payment request and generates the token. One thing you notice in this example, is that the merchant sends a value of “0” (zero) to Adyen.

This is known as Zero Auth and brings us to the next topic: Dynamic Zero Auth.

Dynamic Zero Auth

A typical use case is when merchants need to verify the card details and account holder without charging the shopper. This might be at the start of a trial subscription, or for a pay-as-you-go model where the shopper is only charged for what is used. By sending a Zero Auth transaction to Adyen, we can do an authorisation with a zero-amount. When this Zero-Auth is accepted, it serves as a validation to the merchant that the shopper is legitimate.

However, Zero-Auths aren’t supported by every issuer. Some issuers require specific values for these authorisations. iDeal, for example, requires an amount greater than 0. Adyen takes care of this complexity by introducing Dynamic Zero Auth (also known as Dynamic Card Validation) to prevent the refusal by automatically adjusting the value to the correct amount for the authorisation.

Finally, Adyen stores the card details safely and initializes a token (also known as the “recurringDetailReference”) that the merchant will be using to make future recurring payment requests.

The tokens never expire but they can be disabled manually through the disable API endpoint.

Making payments on behalf of the shopper

When you are ready to charge the shopper for a subscription, this is what the request looks like in C#.

/// In CheckoutClient.cs
public async Task<PaymentResponse> MakePaymentAsync(string shopperReference, string recurringDetailReference, CancellationToken cancellationToken)
{
    // The payment amount.
    var amount = new Amount("EUR", 1199);

    // In v10.0.0+ of the Adyen .NET library, this has changed to:
    // var details = new StoredPaymentMethodDetails(storedPaymentMethodId: recurringDetailReference);
    var details = new DefaultPaymentMethodDetails
    {
       // The token (also known as: recurringDetailReference).
        StoredPaymentMethodId = recurringDetailReference
    };

    var paymentsRequest = new PaymentRequest
    {
        Reference = Guid.NewGuid().ToString(),
        Amount = amount,
        MerchantAccount = _merchantAccount,
        // Set the interaction to ContAuth.
        ShopperInteraction = PaymentRequest.ShopperInteractionEnum.ContAuth,
        // Set the Subscription model.
        RecurringProcessingModel = PaymentRequest.RecurringProcessingModelEnum.Subscription,
        // The unique ShopperReference.
        ShopperReference = shopperReference,
        // In v10.0.0+ of the Adyen .NET library, this has changed to:
        // PaymentMethod = new CheckoutPaymentMethod(storedPaymentMethodDetails) // Set the payment method.
        PaymentMethod = details
    };

    try
    {
        // Make a payment on behalf of your shopper.
        var paymentResponse = await _paymentsService.PaymentsAsync(paymentsRequest);
        return paymentResponse;
    }
    catch (Adyen.HttpClient.HttpClientException e)
    {
        _logger.LogError($"Request for Payments failed::\n{e.ResponseBody}\n");
        throw;
    }
}

If the payment succeeds, the customer is charged and the service is delivered. But what if the payment request fails? This brings us to the next two topics: Real-time Account Updater and Auto Rescue.

Account Updater

When you submit a payment that is refused for certain refusal reasons (e.g. expired card), the Adyen Real Time Account Updater instantly checks for updated card details with the card schemes (Visa, Mastercard, etc.). If there's an update, the payment is immediately retried with the updated card details. This all happens as the payment is being processed and appears as a single transaction. The token is also automatically updated to ensure it refers to the newest details.

Adyen also automatically handles cases such as expired cards. The Adyen Batch Account Updater automatically looks up the latest card that belongs to this shopper so we can continue charging the shopper even though their old card expired.

Auto Rescue

Adyen's Auto Rescue automatically retries refused or charged back shopper-not-present transactions such as subscription renewals. It uses smart logic to decide which payments can succeed when retried later, and performs these retries at optimal times.

A payment can be refused for many reasons. In some cases, when the shopper's account has insufficient funds, the payment may still succeed when submitted again at a later point in time. In other scenarios, when the shopper's account has been closed, the payment is declined permanently.

Auto Rescue schedules retries for refused or charged back payments that have a chance of succeeding. It may take several retry attempts to rescue a payment. These attempts occur within a rescue window.

Obtaining the token

Following a successful tokenization request, Adyen sends the token via an asynchronous webhook notification. Let’s take a look at how we consume the webhook notification and obtain the token (referred here as “recurringDetailReference”) in the code. This is what the C# webhook controller looks like:

/// In WebhookController.cs
[HttpPost("api/webhooks/notifications")]
public ActionResult<string> ReceiveWebhooksAsync(NotificationRequest notificationRequest)
{
    var hmacValidator = new HmacValidator(); // Preferably, dependency-inject this is as a singleton in your constructor.

    foreach(NotificationRequestItemContainer container in notificationRequest.NotificationItemContainers)
    {
        // We always recommend to activate HMAC validation in the webhooks for security reasons.
        // Read more here: https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures & https://docs.adyen.com/development-resources/webhooks#accept-notifications
        try
        {
            if (!hmacValidator.IsValidHmac(container.NotificationItem, _hmacKey))
            {
                return BadRequest("[not accepted invalid hmac key]");
            }

            // Get the recurringDetailReference and shopperReference from the additionalData property in the webhook. Note that the shopperReference is a uniqueId that the merchant has to provide Adyen
            // We store it, so that we can make payment requests on behalf of the shopper in the future.
            if (container.NotificationItem.AdditionalData.TryGetValue("recurring.recurringDetailReference", out string recurringDetailReference))
            {
                if (container.NotificationItem.AdditionalData.TryGetValue("recurring.shopperReference", out string shopperReference))
                {
                    _repository.Upsert(container.NotificationItem.PaymentMethod, shopperReference, recurringDetailReference);
                }
            }
        }
        catch (Exception e)
        {
            _logger.LogError($"Error while calculating HMAC signature::\n{e}\n");
            throw;
        }
    }

    return Ok("[accepted]");
}

Demo

You can find our .NET integration-example on GitHub. Start the application by following the steps in the readme. Once the application is started, you'll find two views here: the shopper view and the admin panel.

In the shopper view, the shopper can purchase a music subscription. This starts the tokenization process.
In the admin panel, an administrator can execute a payment request on behalf of the shopper (MIT) or choose to disable an existing token.

You can find the stored tokens in the admin panel. Keep in mind that the application keeps the tokens in a local memory cache. Once you restart the application, the tokens are lost.

Our sample application provides you with an admin panel to make payment requests on behalf of the shopper for demo purposes only. On production it would obviously not be the case: integrate the business logic and use the .NET library to bill the customer at predefined intervals by initiating the payment request using the token and the associated shopper reference.

Common Issues and Troubleshooting

While implementing this myself, I ran into several errors. I’ve highlighted some of the most common issues below for troubleshooting purposes.

First, let's make sure you enable “Recurring details” in Webhooks: Under Additional Data in your Customer Area , make sure you have “Recurring details” (under “Payments”) enabled to receive the notification which contains your recurringDetailReference. This reference is used to make future payment requests. Below, you can find examples of what a successful and unsuccessful webhook look like.

Secondly, make sure that the "RECURRING_CONTRACT" eventCode is enabled. This can be found in the Webhook settings page in the Customer Area.

Webhook - Successful authorisation
After performing the Zero-auth payment. Adyen will send a webhook containing the authorisation response. Here are some examples:

{
   "live" : "false",
   "notificationI tems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "expiryDate" : "*******",
               "authCode" : "******",
               "recurring.recurringDetailReference" : "JRGCCCKTR6KXWD82",
               "cardSummary" : "0010",
               "threeds2.cardEnrolled" : "false",
               "checkoutSessionId" : "******************",
               "recurringProcessingModel" : "Subscription",
               "recurring.shopperReference" : "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
               "checkout.cardAddedBrand" : "*****************",
               "hmacSignature" : "*****************************"
            },
            "amount" : {
               "currency" : "EUR",
               "value" : 0
            },
            "eventCode" : "AUTHORISATION",
            "eventDate" : "2023-01-16T16:20:51+01:00",
            "merchantAccountCode" : "YourMerchantAccount",
            "merchantReference" : "f7dee104-a1e4-4d7f-9d87-e1298e59aac4",
            "operations" : [
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "paymentMethod" : "mc",
            "pspReference" : "TPJHFH85JKMLNK82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

Webhook - Unsuccessful authorisation

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "amount": {
              "currency": "EUR",
              "value": 0
            },
            "eventCode": "AUTHORISATION",
            "eventDate": "2023-01-16T16:20:51+01:00",
            "merchantAccountCode": "YourMerchantAccount",
            "merchantReference": "f7dee104-a1e4-4d7f-9d87-e1298e59aac4",
            "paymentMethod":"mc",
            "pspReference":"TPJHFH85JKMLNK82",
            "reason":"Insufficient balance on payment", 
            "success":"false"
         }
      }
   ]
}

Webhook - Recurring Contract
When successfully authorised, Adyen will send a webhook containing the "RECURRING_CONTRACT" event code (if it's enabled in your Customer Area/webhook settings) with the recurringDetailReference. Note that this may take some time.

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "recurring.shopperReference" : "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
               "recurring.recurringDetailReference" : "JRGCCCKTR6KXWD82",
               "hmacSignature" : "******************",
               "shopperReference" : "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
               "checkoutSessionId" : "******************"
            },
            "amount" : {
               "currency" : "EUR",
               "value" : 0
            },
            "eventCode" : "RECURRING_CONTRACT",
            "eventDate" : "2023-01-16T16:23:32+01:00",
            "merchantAccountCode" : "YourMerchantAccount",
            "merchantReference" : "f7dee104-a1e4-4d7f-9d87-e1298e59aac4",
            "originalReference" : "TPJHFH85JKMLNK82",
            "paymentMethod" : "mc",
            "pspReference" : "JRGCCCKTR6KXWD82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

Error 803: If you get this error after trying to execute a recurring payment request, this means that the stored card details (token), indicated by the recurringDetailReference, is not available for this shopperReference. Either the recurringDetailReference doesn’t exist, or the contract type is not configured properly for this recurringDetailReference.

Double-check which flags you’re sending in the documentation. You can always check which contract types are stored for a specific shopperReference, using the paymentMethods endpoint or the listRecurringDetails endpoint.

Error 422: If you get this error with errorCode '14_019', please make sure you specify the correct recurringDetailReference in your request. The sdkVersion should automatically be provided by the library.

Admin Panel issues: If nothing is showing up in the Admin Panel after making a payment request in the Shopper View. Here’s a list of steps that may help you:

Double-check if you’ve done the steps in the readme properly.
Is the webhook pointed to the right URL?
Have you set up your HMAC Key correctly? If you provide an invalid key, the signature validation-check will fail and the received notification won’t be processed properly.
Are you running on localhost? If so, you need a proxy to allow our Adyen servers to reach your endpoint. We have another "blogpost about this.
Under "Additional Data" in your Customer Area, make sure you have “Recurring details” (under Payments) to receive the notification which contains your “recurringDetailReference”. This reference is used to make future payment requests. Check your error messages in your console.

If you’ve tried all of the above, and none of the solutions work, open an issue on GitHub.

Summary

We’ve seen how you can use Adyen tokenization to implement subscriptions in .NET along with how you can:

Collect the shopper’s payment information
Retrieve the recurringDetailReference asynchronously
Make a payment request using this recurringDetailReference on behalf the shopper.

We’re always looking for ways to improve the integration-example and scale it to multiple languages that are relevant for our merchants. Have a look at our repository today and let us know on Twitter how we can improve. Alternatively, feel free to open an issue on GitHub and we’ll get to it!

How You Can Stay Up-To-Date with Adyen Tech

Kwok He Chu — Wed, 28 Dec 2022 13:42:09 +0000

In this blog post, we’ll take a look at how our Developer Relations Team at Adyen supports our developer community and how you can stay up-to-date with us through GitHub, StackOverflow, Twitter, blogs, newsletters and several other platforms.

Have you ever wondered how you can stay up-to-date with Adyen Tech? Allow me to introduce you to the Developer Relations Team at Adyen.

During lunch, maybe take a minute and ask your colleagues to define this role. There is a good chance you will get different answers or will not get an answer at all. Every company has a different perspective on how this role fits within their organization.

Our Developer Relations Team at Adyen enables developers to become successful with our APIs, platforms, technologies and other development tools. In the long term, we try to maximize product value for developers so they can integrate easier and faster by acting as a tech-focused bridge between Adyen and its merchants through the concept of Code, Content and Community.

Code

Find us on GitHub. We actively maintain a list of example integrations which showcase some of the core functionalities that our open source libraries and plugins offer. To enhance the developer experience, it’s possible for any developer to spin up our example integration on Gitpod, a remote cloud development environment. We have set up the required .yml files to allow you to run and debug the source code in your browser. Take one of our repositories and launch it by following the instructions in our readme file. Of course, running it on your localhost is possible as well!

We currently support the following languages: Java (Spring), Kotlin (Spring), Node.js, Angular, Vue.js, React, Ruby on Rails, PHP (Laravel), .NET, Python, Golang and Android.

We also monitor our open issues and pull requests the best we can. Is it a bug? Is it a feature request? Is it a configuration issue? We help our developer community by answering these questions and provide the solution they need to continue with their integrations. Depending on the issue, we make sure that we improve our documentation (or integration example itself) so that developers are less likely to run into the issue again.

With a team of four, maintaining and updating these integration examples comes with several challenges:

Maintain an up-to-date version of the latest Adyen Web Components/Drop-in.
Maintain the Adyen Ecommerce plugin demo applications.
Maintain up-to-date documentation that allow our developer community to use it as a reference.
Adding new functionalities to our example integrations.
Upgrade dependencies within the integration example (f.e. libraries or other framework dependencies). This includes vulnerabilities alerts identified by Dependabot.
Provide an end-to-end testing suite for our integration examples.

Content

Below you can find a list of tech articles, blog posts and a monthly newsletter that might be relevant to you.

Blogs
You can stay up-to-date with us by checking out our latest tech blogs. Aside from writing the blogs ourselves, we also encourage our engineers to write about topics that are worth sharing. We have highlighted several interesting ones below.

We also release content on Medium and Dev.to for other topics that are relevant in the industry.

Monthly Newsletter
Sign up for our monthly developer newsletter to get all our announcements. This newsletter informs you about our upcoming events, past events, library releases notes and other useful resources. We handcraft these newsletters every month, so you can be assured that there will be no spam.

Community

Next to GitHub, we are also active on several other platforms.

StackOverflow
You can find us on StackOverflow of course! This is a community-driven space. While we actively monitor questions it is great to see that other contributors answer questions and help fellow developers move forward with their integration. It has also become a valuable knowledge base. Many answers that have helped developers in the past are still applicable to this day.

Meetups and Conferences
Catch us at meetups and conferences! We support local initiatives and are part of events that are relevant to Adyen and our technology stack. We share knowledge during these events and connect with other developers. At conferences, we often give talks or attend and engage with our developer community. Sometimes, we find our merchants there as well!

Twitter
You can find us on Twitter @AdyenDevs! We give out regular community updates and show what we are up to at events, meetups or conferences.

Some food for thought

If you have a developer relations team in your company, feel free to book some time with them and share what your current challenges are within your role. Think about improvements in API documentation, better example integrations or improving existing processes that will benefit the overall developer experience. These important feedback loops are essential for building better and healthier products.

That’s why I’d like to leave you with the following question that may help you get the conversation started: “If there’s one thing that would make your life as a developer easier, what could that be and how can we help you achieve that today?”

Feedback is very valuable to us and we actively listen to our developer community. Let us know on Twitter @AdyenDevs!

Summary

GitHub Integration Examples — Our example integration demos.

GitHub Libraries/Plugins — Our libraries and plugins.

Twitter — Our semi real-time updates.

Stackoverflow — You ask questions, we answer.

Developer Newsletter — Our monthly handcrafted updates.

Meetups — Our events and meetups.

Our technical resources for developers on Adyen, Medium and Dev.to.

Adyen Tech Academy: Taking Onboarding and Upskilling to The Next Level

Kwok He Chu — Fri, 23 Dec 2022 15:21:49 +0000

by Maurício Aniche, Alexander Tiplea, Carianne Pretorius and Erik de Gooijer.

Helping engineers get up to speed quickly and get even better at their jobs is a must for any tech company. It's also an enormous challenge. Fortunately, we at the Adyen Tech Academy are here and ready to help our engineers on their learning journey!

We're currently celebrating our first year of existence in the company and we have learned a lot during this time. In the next sections, we'll convince you why having a tech academy is important, explain how we handle onboarding and upskilling, and outline some of the challenges we have faced when building our academy.

Why do we need a Tech Academy?

Any company that wants to scale up needs to think about how they will onboard (many) new engineers, effectively, within short periods of time. Throwing new joiners into teams and hoping they will catch up is rarely productive. Moreover, proactively supporting engineers in becoming a better version of themselves is imperative for their growth. This is not only beneficial for engineers, but for employers as well. Engineers update their skills and increase their market value, and Adyen benefits from having stronger engineers who are better equipped to tackle our ever-growing technical challenges.

With this in mind, the Tech Academy was born, our broad objective being to support engineers during their onboarding process and thereafter. We have boldly set our mission to be:

Making the onboarding of the new engineers an enjoyable and effective experience.
Enabling engineers to develop their technical skills within Adyen.
Fostering a learning culture where engineers feel safe to learn and share.

In stark contrast with academies that are typically organized by Learning and Development (L&D) departments, Adyen Tech Academy emerged from within the engineering department itself. In practice, this means that we're a new team under the engineering umbrella, and fall directly below our CTO. This embodies our view that "we are tech for tech," and we strongly believe that much of our current success can be attributed to our ability to work closely with our own engineers who understand the challenges of onboarding and upskilling.

Onboarding: getting engineers up to speed

Onboarding is the first adventure that all new engineers embark on. Research shows that a great onboarding experience can almost double your chances of retaining new employees, and even increase their productivity by 70% during the first year. Equipped with fuzzy directions and some kind of map (if they're lucky), new joiners must wander about the company to their final destination. But what is this destination, exactly? And how can we best equip our engineers to make it there? These are the two major questions that we try to address.

We really want our engineers at Adyen to have a cohesive, stimulating, and fun experience in their first weeks. At the same time, we aim to equip them with tools and resources to confidently face any challenges that might arise in their new role.

We view our engineering onboarding at Adyen as a process that spans approximately six months, though in practice it can vary per role and per specific engineer. There are three primary groups that facilitate this process: (1) The HR and L&D departments who provide new joiners with a glimpse of what Adyen is, (2) the team that the engineer is joining together with their assigned buddy and (3) us at the Tech Academy focusing on the tech side of things. We outline the process broadly below.

First three days
The first three days at Adyen are super busy for all new joiners, but even more so for engineers. On day one, new joiners spend their morning being introduced to the company by HR and meeting each other as fellow colleagues. After a nice social lunch, they spend most of the afternoon setting up their laptops. There's so much to configure, including access to email, internal communication, access to code repositories, and security-related software. Our amazing Business Infrastructure team has recorded a step-by-step video tutorial which new joiners follow. If any question emerges, they will be available to help. In the remainder of the day, the new joiners are welcomed by the HR and L&D teams. They talk mostly about how life at Adyen is and where to go in case of any HR-related questions. The new joiners end their first day with meeting their teams. The second day is a similar format.

On day three, it is time for engineering new joiners to get to know the Tech Academy. We also give them a warm welcome to the company and explain what their technical onboarding will look like. Although tech is the focus of our onboarding, the major part of this first session is focused on the interpersonal and organizational side of things. We make sure they understand that joining a new company is always challenging and that here at Adyen, they will have enough time and space to get up to speed. We also make sure that they get to know each other a bit better through small conversation circles. After all, it's always nice to meet someone facing the same new challenges as you.

First two weeks
The next two weeks for engineering new joiners involve a mixture of technical presentations from the Tech Academy, rolling up their sleeves and exploring the codebase, conversations with team members, and company-wide presentations from HR.

We tell new joiners that their main focus should be working together with their buddy. We always assign someone from the new joiner's team to be their buddy. The responsibilities of the buddy encompass supporting the person in getting up to speed. They explain what their team does in detail, point the new joiner to the right setup guides and documentation, walk them through the code base, work on some first tasks with the new joiner, and help them increase their network within the team and the company.

At this point, new joiners also start taking our training sessions. In the first two weeks, our focus is more high-level; there is no need to overwhelm new joiners with information they don't yet need or have the ability to fully grasp at that moment. After all, they are just starting. Instead, we give talks about our engineering principles, how our release processes work, our databases, social etiquette when doing code reviews, and how to use our build tools. These presentations are role-specific. A data scientist will not learn about how we scale our financial platform, but will learn about how we scale our data platform. These presentations are often given by (senior) engineers in the company; this also allows new joiners to meet "go-to people" in case they have questions about specific topics.

Depending on their team, new joiners may benefit from specific HR presentations more than others. For example, if an engineer joins a team that does In-Person Payments (IPP) development, they may benefit from hearing the business presentation about IPP more than someone that joins, say, our banking teams. We give new joiners a list of presentations that they should follow right at the start, as well as which ones they only need to follow later on.

First month
After the first two weeks have passed, the new joiner has more clarity on how Adyen works and what they should focus on in terms of learning. Suppose an engineer is in a team that heavily uses technology X. Even if a new joiner already knows technology X from previous experience, they still need to learn how Adyen uses it, our best practices, and lessons learned. For that, the new joiner can subscribe to one of the many sessions about elements of our tech stack that the Tech Academy offers. We currently offer more than 20 different courses covering our tech stack.

Something that sets us apart from companies that "require" new joiners to follow courses and even assign them from day one, is that we take the approach of suggesting that the new joiners are the ones responsible for enrolling themselves. Why do we do this? Because there's no-one better than the new joiner (along with their buddy) to decide when it's time to learn about a specific technology. If the person isn't going to use a technology for the next six months, why learn about it at this moment when there is already so much to learn that impacts their daily work now?

We also make sure to synchronize with new joiners regularly to see how they are going. In particular, at the end of the first month, we host a gathering where we openly discuss how they are doing, as well as things that they liked and disliked in the onboarding process, so that we can keep improving. Around their fourth week, new joiners also have the chance to meet our CTO Alexander Matthey. In this session, new joiners can ask him any questions they want on the spot. Questions vary from "why did we choose this tech?" to "what's our next big impactful solution?" or "what does a CTO do?". Having the opportunity to chat informally with the CTO inspires new joiners to see that they are already valued as colleagues, and emphasizes the reality that they are capable of making an impact at Adyen no matter how new they are to the company.

First six months
Around six months, we expect the new joiner to be confident as an engineer, and know their way around the company and our tech stack. It is time to start working on becoming an even better engineer. Or to upskill, as we call it.

All-in-all, the onboarding goes from high-level presentations on how engineering works at Adyen, up to how our tech stack works, up to how the specific team works. New joiners start from the more generic to the more specific, as you see in the figure below.

We believe that the new joiner is strongly responsible for their own onboarding. That is why we let the new joiners decide when it's time to take courses (differently from other companies who force a strict schedule!), join some upskilling activity, or when it's time to ask for help.

Upskilling: making engineers better

Improving as an engineer is also a must, not only for the engineers themselves as they keep improving their market value, but also for companies as their challenges keep growing. At Adyen Tech Academy, we do our best to keep offering activities for engineers to further their own learning. In particular, we offer workshops, organize reading clubs, and promote talks from internal and external experts.

Workshops
We offer workshops on topics that our engineers are often curious and like to talk about, such as testing, architecture, and software design. We organize these workshops not as "lectures", where one person speaks for 90% of the time. Rather, these workshops are designed to ensure participants are active, share their experiences from their teams, and discuss how we can have an even bigger impact at Adyen as engineers. This means that every offering is essentially unique, inspired by the participants.

The moderator of the workshop is mostly responsible for guiding the discussion. We also make sure to pick a moderator that deeply understands the topic, so if there's any misunderstanding about a principle or a technique, the moderator can help facilitate a common understanding.

Reading clubs
There are so many interesting books worth reading in the tech space, but so little time. To keep reading and learning, it really helps to be accountable to a friend who is reading along and discussing with you. With this in mind, we organize different reading clubs about books our engineers are curious about. These reading clubs usually take four to six weeks, where each week focuses on one or more pre-selected chapters of the book. Monoliths to Microservices, Observability Engineering, and Software Engineering at Google are just a few examples of the books we collectively read. We have also started experimenting with reading clubs focusing on the interpersonal and organizational side of software engineering either directly or indirectly, such as HBR Guide to Women at Work.

We have no prescriptive format to run these reading clubs and they vary a lot, usually according to the wishes of the participants. In some reading clubs, we nominate a person to be responsible for making a short presentation about the chapter(s) for the session. In others, it's a free format and people just talk about what they think about the chapter(s), for example, what they like and dislike, or agree and disagree with.

Talks
There's so much knowledge inside our company, and we do our best to make sure this knowledge gets out of its bubble for others to learn from. Whenever an engineer has an interesting topic, we help the person to create a presentation and deliver it to our engineers. What engineers usually need to get it done is just a little bit of support and encouragement, so our approach is to just walk with them through this journey. When the person is less experienced in creating and giving talks, we give them more comprehensive tips on how to present.

There's also a whole bunch of knowledge that exists outside the company, and hearing different ideas always helps us to sharpen our perspectives. To that end, we do our best to invite world-class engineers to give talks at Adyen. Sam Newman (the author of Monoliths to Microservices), Steve Freeman (Growing Object-Oriented Systems Guided by Tests), Yehonathan Sharvit (Data-Oriented Programming), and Gergely Orosz (The Pragmatic Engineer) are a few of the names we had this year. We also have invited academics to talk about their research. Michael Hilton (who spoke about mob programming), Jonathan Bell (flaky tests) and Burcu Kulahcioglu Ozkan (testing distributed systems) are among the speakers.

In our approach we keep our activities as engaging as possible, with a strong emphasis on live and in-person meetings. We feel that this contributes to an environment where knowledge is easily shared and true connections between engineers are built. Of course, engineers working from home are always welcome to join any session!

Challenges in building a Tech Academy

We are proud of what we have built in this first year! We still have many challenges ahead of us. Here, we outline three of them: build team-specific onboarding experiences, keep people engaged, and find better ways to measure the impact of our activities.

Team-specific onboarding. Although we can build courses that are relevant for all engineers, a lot of the challenges related to onboarding are very specific to the team that the person is joining. We have many teams at Adyen, and building a tailor-made onboarding experience for each of them is costly.
Consistent engagement. Keeping engineers excited about learning requires a continuous investment. Otherwise, it's just too easy for them to "focus on their work", especially engineers that have been at the company for a long time.
Scaling to our other dev hubs. Adyen has multiple development hubs all over the world, including Chicago, Brazil, Madrid, and Singapore. This means that we need to scale our offerings as these hubs emerge and grow.
Better measuring our impact. This blog post describes our current learning strategies, but we are always experimenting with different things every onboarding session. However, precisely measuring the impact that our onboarding process has on, say, how long it takes for someone to be fully productive in their time, is tough.

This is just the beginning!

Having effective onboarding procedures in place, and successfully supporting engineers in their upskilling are first-class citizens for any tech-first company, and especially the ones that want to grow fast! Our Tech Academy exists for this reason, and we are absolutely committed to helping our engineers onboard and grow.
We learned a lot during our first year! Based on the numbers from our activity and offering back office application (that we built ourselves), here is a sneak peek of how far we've come:

We developed and offered 81 distinct activities.
These activities, all together, were offered 237 times.
We had a total of 4,068 engineers taking part of all these activities.
763 unique engineers joined at least one of the activities, a significant part of our engineering population.
62 different trainers facilitating all these activities.
138,000 minutes of video or pages collectively read in O'Reilly.

… all in the span of around six months (as our back office went live on 3 May 2022).

Nevertheless, while we have made great improvements in the process, we still have a long way to go. Do not fret if you are yearning to know more alongside us, we'll keep sharing our learnings with you.

How To Use Visual Studio Dev Tunnels to Receive Webhooks on Localhost

Kwok He Chu — Mon, 19 Dec 2022 12:50:02 +0000

TL;DR: In this blog post, I'll show you how you can use Visual Studio Dev Tunnels to receive webhooks on your localhost. There are many alternative third-party proxy tools out there; this is just one of them.

One of my many frustrations when working with webhooks is the process to debug applications on my localhost. I've considered several alternatives: third-party proxies, tunnels, hosting it on a cloud service and attaching my debugger to it. My workflow looks something like this:

Download a third-party tool.
Make my localhost publicly available through this third-party tool.
Update/configure the webhook URL.
Repeat the previous step when my laptop goes into standby mode or the tunnel breaks.

A quick note: some companies don't allow you to set up a third-party proxy, especially when you're connected to their intranet!

In an ideal world, I'd like to press the Run-button and start debugging my application right away where everything is already set up. Configure once. Run and debug for as long as I am working on the application. This is where I came across Visual Studio dev tunnels (formerly known as port tunneling).

Visual Studio Dev Tunnels

To receive webhooks, it boils down to two main things:

Make my endpoints publicly available through a proxy.
Configure/update the webhook URL so that my endpoint can receive events through this proxy.

With the release of Visual Studio 17.4 or higher, they have introduced a new feature "Visual Studio Dev Tunnels" that allows you to create a proxy to your local machine. It also keeps the tunnel up and running until you close it. It has significantly improved my developer experience and sped up my workflow.

Update: As of Visual Studio 17.6+, you can now create a (public/private) persistent or temporary tunnel within the Visual Studio wizard. You will no longer need the extra configuration in your project.

For earlier versions, we'll use an ASP.NET Core project in Visual Studio and set up a tunnel. The following guide can be applied to any webhook. For your convenience, a fully working integration example can be found in the .NET Adyen examples repository. Let's take a look at the steps needed to configure your tunnel.

Sign in to Visual Studio.
Under Options → Environment → Preview Features → Check Enable dev tunnels for Web Application.

Enable dev tunnels for Web Applications in the Visual Studio Preview Features screen.3. In your launchSettings.json, add the following two properties:



devTunnelsEnabled: <Boolean> [true, false]
devTunnelAccess: <String> [ "public", "private", "org"]
//public: Anyone can access this tunnel.
//private: Only the logged-in user can access this tunnel.
//org: Only users within the same organization as the logged-in user can access this tunnel.

See an example of a launchSetting.json profile below.



{
  "DevTunnelsProfile": {
    "commandName": "Project",
    "launchBrowser": true,
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "applicationUrl": "https://localhost:5001;http://localhost:8080",
    "devTunnelEnabled": true,
    "devTunnelAccess": "public"
}

The next step is to configure your webhook. You usually configure this in some kind of portal that is provided by the organization you're trying to receive webhooks from. Your webhook URL should point to this temporary auto-generated URL that is created when you start the application (e.g. https://*.euw.devtunnels.ms). As long as you do not close Visual Studio, this URL will remain the same. In future updates, we will be able to create a durable URL which persists even after you restart or close Visual Studio.

Retrieving the URL dynamically

Visual Studio exposes this URL as an environmental variable VS_TUNNEL_URL at run-time. This allows developers to programmatically update the webhook URL if needed. For multiple projects, the environmental variable looks like VS_TUNNEL_URL_PROJECTNAME where PROJECTNAME is the name of your project.

For an ASP.NET project, you retrieve it like this:



// From Microsoft.Extensions.Configuration.IConfiguration 
Configuration["VS_TUNNEL_URL"];
Configuration["VS_TUNNEL_URL_PROJECTNAME"];



// From System.Environment.GetEnvironmentVariable(...)
Environment.GetEnvironmentVariable("VS_TUNNEL_URL");
Environment.GetEnvironmentVariable("VS_TUNNEL_URL_PROJECTNAME");

All that's left is starting your application. Once started, you'll see the created tunnel and the auto-generated URL in the output window.

That's it. Happy debugging!