Processing card payments

When a cardholder attempts to make a payment with an Adyen-issued card, you can control the approval through:

• Relayed authorisation: Approve or deny each payment attempt. Adyen sends you a webhook for each attempt, and you have up to 1500 milliseconds to respond. If we don't receive a response within this timeframe, we will apply your default fallback.
• Transaction rules: Automatically approve or deny payment attempts based on transaction rules. You can create rules based on conditions such as maximum amount, maximum number of transactions, or the types of payments allowed for a payment instrument. The rules are automatically applied to each payment attempt. Rules can be combined to facilitate different use cases.

You can choose to use both. When you use both, the transaction rules are applied first, because these serve as a filter for payment attempts before sending you the relayed authorisation webhook. A payment already rejected by transaction rules will not be sent to your system.

Relayed authorisation

Relayed authorisation gives you full control over payment processing.

With each relayed authorisation webhook we send you, 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.

Default fallback

When using relayed authorisation, you have 1500 milliseconds to respond. If you don't respond within 1500 milliseconds, Adyen applies your default fallback logic.

Reach out to your Adyen contact to specify which fallback logic you want:

• Default approval
• Default refusal

Step 1. Configure a relayed authorisation 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.

Once you have an endpoint ready, reach out to your Adyen contact to configure the endpoint within the Adyen platform.

Step 2. Respond to the webhook

When a transaction attempt comes in, we will send an HTTP POST with a relayed authorisation message to the webhook endpoint you specified. Your server must respond within 1500 milliseconds, with 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 field set to Authorised if you are allowing the transaction or Refused.
  • 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 don't receive a response within 1500 milliseconds or if we receive an HTTP 4xx or 5xx error code, we will apply your default fallback logic.

Here is an example incoming request:

{
  "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"
    }
  ]
}

For example, you processed the webhook and decided to approve the transaction. Your server must respond with an HTTP 200 status code with a message containing status Authorised.

{
  "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, respond with an HTTP 200 status code with a message containing status Refused.

{
  "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}"
  }
}

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.