Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em inglês
Issuin icon

Use relayed authorisation

Approve or decline payments by responding to relayed authorisation webhooks.

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 1500 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 notification 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 1500 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:

Relayed authorisation message
{
  "accountHolder": {
    "description": "S.Hopper - Staff 123",
    "id": "AHA1B2C3D4E5F6G7H8I9J0"
  },
  "amount": {
    "currency": "EUR",
    "value": -66
  },
  "authCode": "136649",
  "authorisationDecision": {
    "reasonCode": "APPROVED",
    "status": "Authorised",
    "statusCode": "APPROVED"
  },
  "balanceAccount": {
    "description": "S.Hopper - Main balance account",
    "id": "BAB8B2C3D4E5F6G7H8D9J6GD4"
  },
  "balanceMutations": [
    {
      "balanceAfter": {
        "currency": "EUR",
        "value": 231
      },
      "balanceBefore": {
        "currency": "EUR",
        "value": 297
      },
      "currency": "EUR",
      "mutationAmount": {
        "currency": "EUR",
        "value": -66
      },
      "type": "AuthorisedOutgoing"
    }
  ],
  "balancePlatform": "YOUR_BALANCE_PLATFORM",
  "id": "1W3ZLV5O48VTA1E6",
  "merchantData": {
    "mcc": "7999",
    "merchantId": "526567789012346",
    "nameLocation": {
      "city": "Amsterdam",
      "country": "NLD",
      "name": "MerchantName",
      "rawData": "MerchantName Amsterdam NLD"
    }
  },
  "originalAmount": {
    "currency": "EUR",
    "value": -66
  },
  "paymentInstrument": {
    "balanceAccountId": "BA1234123412341234",
    "description": "S.Hopper - Main card",
    "issuingCountryCode": "NL",
    "status": "active",
    "type": "card",
    "card": {
      "brand": "mc",
      "brandVariant": "mcdebit",
      "cardholderName": "Sam Hopper",
      "formFactor": "virtual",
      "bin": "555544",
      "expiration": {
        "month": "06",
        "year": "2023"
      },
      "lastFour": "2168"
    },
    "id": "PI3227C223222B5BPCMFXD2XG"
  },
  "reference": "MCS652790426",
  "transactionRulesResult": {
    "allRulesPassed": "true"
  },
  "validationResult": [
    {
      "result": "valid",
      "type": "MaxAuthAmount"
    },
    {
      "result": "valid",
      "type": "TransactionRules"
    },
    {
      "result": "valid",
      "type": "Screening"
    },
    {
      "result": "valid",
      "type": "PaymentInstrumentExpirationCheck"
    },
    {
      "result": "valid",
      "type": "Validation"
    },
    {
      "result": "valid",
      "type": "TransactionValidation"
    },
    {
      "result": "valid",
      "type": "ExchangeAmount"
    },
    {
      "result": "valid",
      "type": "CVC2"
    }
  ]
}

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

Approve a payment
{
  "authorisationDecision" : {
    "status" : "Authorised"
  },
  "reference":"{hint:This is your unique identifier for this resource}myBalancePlatformPayment_12345{/hint}",
  "metadata":{
    "customId":"{hint:This is your unique identifier for this resource}your-own-custom-field-12345{/hint}"
  }
}

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

Decline a payment
{
  "authorisationDecision" : {
    "status" : "Refused"
  },
  "reference":"{hint:This is your unique identifier for this resource}myBalancePlatformPayment_12345{/hint}",
  "metadata":{
    "customId":"{hint:This is your unique identifier for this resource}your-own-custom-field-12345{/hint}"
  }
}

Fallback

If you don't respond within 1500 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 notification 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.

Próximas etapas