Skip to content

Latest commit

 

History

History

authorisation-adjustment-example

readme.md

Adyen Authorisation Adjustment Integration Demo

This repository includes an adjust authorisation example for the following three use cases after a pre-authorised payment: incremental, decremental adjustments. Within this demo app, you'll find a simplified version of a hotel booking, where the shopper perform a booking and administrators can [1] adjust (increase/decrease) the payment amount, [2] extend the authorisation expiry date, [3] capture the final amount and [4] reverse (cancel or refund) an authorised payment

Note: We've included a technical blog post that explains every step of this demo.

Authorisation Adjustment Demo

This demo leverages Adyen's API Library for .NET (GitHub | Docs).

Run integration on Gitpod

  1. Open your Adyen Test Account and create a set of API keys.

  2. Go to Gitpod Environmental Variables and set the following variables: ADYEN_API_KEY, ADYEN_CLIENT_KEY and ADYEN_MERCHANT_ACCOUNT with a scope of */*

  3. To allow the Adyen Drop-In and Components to load, add https://*.gitpod.io as allowed origin by going to your ADYEN_MERCHANT_ACCOUNT in the Customer Area: Developers → API credentials → Find your ws_user → Client settings → Add Allowed origins.

Warning You should only allow wild card (*) domains in the test environment. In a live environment, you should specify the exact URL of the application.

This demo provides a simple webhook integration at /api/webhooks/notifications. For it to work, you need to provide a way for Adyen's servers to reach your running application on Gitpod and add a standard webhook in the Customer Area.

  1. To receive notifications asynchronously, add a webhook:

    • In the Customer Area go to Developers → Webhooks and add a new Standard notification webhook
    • Define username and password (Basic Authentication) to protect your endpoint - Basic authentication only guarantees that the notification was sent by Adyen, not that it wasn't modified during transmission
    • Generate the HMAC Key and set the ADYEN_HMAC_KEY in your Gitpod Environment Variables with a scope of */* - This key is used to verify whether the HMAC signature that is included in the notification, was sent by Adyen and not modified during transmission
    • For the URL, enter https://gitpod.io for now, we will need to update this webhook URL in step 6
    • Make sure the webhook is Enabled to send notifications

  2. Click the button below to launch the application in Gitpod.

Open in Gitpod

  1. Update your webhook in the Customer Area with the public url that is generated by Gitpod
    • In the Customer Area, go to Developers → Webhooks → Select your Webhook that is created in step 4 → Server Configuration
    • Update the URL of your application/endpoint (e.g. https://8080-myorg-myrepo-y8ad7pso0w5.ws-eu75.gitpod.io/api/webhooks/notifications/
    • Hit Apply → Save changes and Gitpod should be able to receive notifications

Note When exiting Gitpod a new URL is generated, make sure to update the Webhook URL in the Customer Area as described in the final step. You can find more information about webhooks in this detailed blog post.

Run integration on localhost using a proxy

You will need .NET Core SDK 6.x. to run this application locally.

  1. Clone this repository.
git clone https://github.com/adyen-examples/adyen-dotnet-online-payments.git

  1. Open your Adyen Test Account and create a set of API keys.

  2. To allow the Adyen Drop-In and Components to load, add https://localhost:5001 as allowed origin by going to your MerchantAccount in the Customer Area: Developers → API credentials → Find your ws_user → Client settings → Add Allowed origins.

Warning You should only allow wild card (*) domains in the test environment. In a live environment, you should specify the exact URL of the application.

This demo provides a simple webhook integration at /api/webhooks/notifications. For it to work, you need to provide a way for Adyen's servers to reach your running application and add a standard webhook in the Customer Area. To expose this endpoint locally, we have highlighted two options in step 4 or 5. Choose one or consider alternative tunneling software.

  1. Expose your localhost with Visual Studio using dev tunnels.
    • Add https://*.devtunnels.ms to your allowed origins
    • Create your public (temporary/persistent) dev tunnel by following the guide here

If you use Visual Studio 17.4 or higher, the webhook URL will be the generated URL (i.e. https://xd1r2txt-5001.euw.devtunnels.ms).

  1. Expose your localhost with tunneling software (i.e. ngrok).
    • Add https://*.ngrok.io to your allowed origins

If you use a tunneling service like ngrok, the webhook URL will be the generated URL (i.e. https://c991-80-113-16-28.ngrok.io/api/webhooks/notifications/).

  $ ngrok http 8080
  
  Session Status                online                                                                                           
  Account                       ############                                                                      
  Version                       #########                                                                                          
  Region                        United States (us)                                                                                 
  Forwarding                    http://c991-80-113-16-28.ngrok.io -> http://localhost:8080                                       
  Forwarding                    https://c991-80-113-16-28.ngrok.io -> http://localhost:8080

  1. To receive notifications asynchronously, add a webhook:

    • In the Customer Area go to Developers → Webhooks and add a new Standard notification webhook
    • Define username and password (Basic Authentication) to protect your endpoint - Basic authentication only guarantees that the notification was sent by Adyen, not that it wasn't modified during transmission
    • Generate the HMAC Key - This key is used to verify whether the HMAC signature that is included in the notification, was sent by Adyen and not modified during transmission
    • See script below that allows you to easily set your environmental variables
    • For the URL, enter https://ngrok.io for now - We will need to update this webhook URL in step 10
    • Make sure the webhook is enabled to send notifications

  2. Set the following environment variables in your terminal environment: ADYEN_API_KEY, ADYEN_CLIENT_KEY, ADYEN_MERCHANT_ACCOUNT and ADYEN_HMAC_KEY. Note that some IDEs will have to be restarted for environmental variables to be injected properly.

export ADYEN_API_KEY=yourAdyenApiKey
export ADYEN_MERCHANT_ACCOUNT=yourAdyenMerchantAccount
export ADYEN_CLIENT_KEY=yourAdyenClientKey
export ADYEN_HMAC_KEY=yourAdyenHmacKey

On Windows CMD you can use this command instead.

set ADYEN_API_KEY=yourAdyenApiKey
set ADYEN_MERCHANT_ACCOUNT=yourAdyenMerchantAccount
set ADYEN_CLIENT_KEY=yourAdyenClientKey
set ADYEN_HMAC_KEY=yourAdyenHmacKey
  1. Start the application and visit localhost.
dotnet run --project authorisation-adjustment-example
  1. Update your webhook in your Customer Area with the public url that is generated.
    • In the Customer Area go to Developers → Webhooks → Select your Webhook that is created in step 6 → Server Configuration
    • Update the URL of your application/endpoint (e.g. https://c991-80-113-16-28.ngrok.io/api/webhooks/notifications/ or https://xd1r2txt-5001.euw.devtunnels.ms)
    • Hit Apply → Save changes and Gitpod should be able to receive notifications

Note When exiting ngrok or Visual Studio a new URL is generated, make sure to update the Webhook URL in the Customer Area as described in the final step. You can find more information about webhooks in this detailed blog post.

Usage

To try out this application with test card numbers, visit Test card numbers. We recommend saving multiple test cards in your browser so you can test your integration faster in the future.

  1. Make a booking in the Booking View
  2. Visit the Admin Panel to see the incoming webhooks and perform operations on the initial preauthorisation.

A success scenario for a payment followed by two adjustments, a capture and a reversal looks like:

AUTHORISATION (preauthorisation) → AUTHORISATION_ADJUSTMENT (adjust) → AUTHORISATION_ADJUSTMENT (adjust) → CAPTURE (capture) → CANCEL_OR_REFUND (reversal)

Adyen expires an authorisation request automatically after XX days depending on the card brand. The EXTEND operation in this sample is used to extend the expiry date manually, for the exact days, refer to the documentation (section: validity).

When CAPTURE is executed, it will perform the operation on the latest amount. You'll have to wait for the AUTHORISATION_ADJUSTMENT response, before making the capture once it's final.

  1. Make sure to have your webhooks configured and wait for a while to confirm that the changes have been received by your application (f.e. a CAPTURE_FAILED event can take several hours to process).