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.

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.

Approve or reject a payment attempt

When a payment attempt comes in, we will send an HTTP POST with a relayed authorisation message to the endpoint you specified.

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

When you receive a relayed authorisation webhook, you have 1500 milliseconds to approve or deny the transaction.

To do this, you need to respond with an HTTP 200 status code, along with the following:

• status: Set this to Authorised or Refused.
• metadata: Object that contains key-value pairs that you can use in your reporting or other business process.

For example, to approve a transaction, 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}"
  }
}

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

Relayed authorisation fallback

When using relayed authorisation, you have 1500 milliseconds to respond.

If you don't respond within 1500 milliseconds, you can specify which fallback logic you want:

• Default approval
• Default refusal

You can set these rules within the Adyen Issuing dashboard.

Adyen domain and IP addresses

Depending on your network and security requirements, you might need to add our network to your firewall's whitelist 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 a whitelist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.