Use relayed authorisation

How it works

Relayed authorisation allows you to make a real-time decision on whether to approve or decline a transaction. When we receive a payment authorisation request, we send you a relayed authorisation webhook with the relevant transaction data, including transaction rules and validation checks.

With each relayed authorisation webhook we send, you have up to 2000 milliseconds to reply with an approval or a refusal. For the best customer experience, you should respond as quickly as possible and aim for a low average response time. If you do not respond within 2000 milliseconds, you can specify which fallback logic you want:

• Default approval
• Default refusal

To set up relayed authorisation

1. Expose a webhook endpoint
2. Configure a relayed authorisation webhook
3. Respond to the webhook

Expose a webhook endpoint

To start receiving relayed authorisation webhooks, expose an endpoint on your server that:

• Can receive a JSON object.
• Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
• Can handle basic authentication.

Configure the relayed authorisation webhook

When you have an endpoint ready, configure the webhook in your Balance Platform Customer Area. To do this, your user account must have the Manage relayed authorisation configuration role. For more information, see the user roles.

To configure relayed authorisation webhooks:

1. Log in to your Balance Platform Customer Area.
2. Go to Issuing > Relayed authorisation.
3. Select the toggle to enable relayed authorisation and edit configuration settings.
4. Under General, select the edit icon , configure the following server configuration fields, and select Apply:
   • URL: Enter your HTTPS URL.
   • SSL level: Select the validation level you want for certificates:
     • Default
     • Accept all (including expired)
     • Accept all
     • Valid chain (including expired)
     • Valid chain
     • Allow expired
     • Check all
5. Under Security, select the edit icon , configure the following fields, and select Apply:
   • Basic authentication: Enter your server's username and password for basic authentication. We include these details in the header of the webhook to authenticate with your server.
   • HMAC Key: Select Generate to create a hex-encoded HMAC key. You need this key to receive HMAC-signed webhooks. Save the HMAC key securely in your system — you will not be able to copy it later.
6. Under Decision on error, select the edit icon , set the following fields to configure the fallback logic you want Adyen to take in case of errors, and select Apply:
   • Connection error: Choose to automatically approve or decline in case of timeouts.
   • Invalid response: Choose to automatically approve or decline in case Adyen receives an invalid response from your server.
7. Select Save when you are done editing your configuration.

Respond to the webhook

When a payment attempt comes in, we will send an HTTP POST with a relayed authorisation message to the endpoint you set up when configuring a webhook. Your server must respond to the webhook within 2000 milliseconds.

The response must contain an appropriate HTTP status code and response body:

• HTTP 200: you processed the transaction and are providing your decision. In the response body, send the following fields:
  • status: set to Authorised if you are allowing the transaction or Refused if you are refusing the transaction.
  • metadata: object that contains key-value pairs that you can use in your reporting or other business process.
• HTTP 4xx: you are unable to process the authorisation because you received an unexpected request. The response body can be empty.
• HTTP 5xx: you are unable to process the authorisation because of a problem on your server. The response body can be empty.

If we receive an HTTP 4xx or HTTP 5xx error code, we will apply your default fallback logic.

Here is an example of a relayed authorisation webhook from Adyen:

If you decide to approve the transaction, your server must respond with an HTTP 200 status code with a message containing status Authorised.

If you decide to reject a transaction, your server must respond with an HTTP 200 status code with a message containing status Refused.

Fallback

If you do not respond within 2000 milliseconds, you can specify which fallback logic you want:

• Default approval
• Default refusal

Adyen domain and IP addresses

Depending on your network and security requirements, you might need to add our network to your firewall's allowlist to receive relayed authorisation webhooks.

We do not provide a list of IP addresses. IP addresses change over time due to various reasons, such as ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded.

To make sure you can communicate with our network, you can either:

• Use a domain allowlist. Include our domain out.adyen.com if your network configuration allows domain allowlisting.
• Systematically resolve our IP addresses. Perform DNS lookup for out.adyen.com. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.