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.
Step 1. Configure a webhook endpoint
To start receiving relayed authorisation webhooks, you will need to expose an endpoint that:
- Can receive a JSON object.
- Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
- Can handle basic authentication.
To learn more about setting up webhooks, see Set up webhooks.
Step 2. 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
If you decide to reject a transaction, your server must respond with an HTTP 200 status code with a message containing
If you don't 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, for example, 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.comif 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.