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 options. Transaction rules are applied first, serving as a filtering mechanism for payment attempts before sending you the relayed authorisation webhook. A payment already rejected by transaction rules will not be sent to your system.

Once a payment has been approved or rejected, it creates a balance platform payment resource. After the initial payment, the payment will go through different stages.

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.

Transaction rules

A transactionRule sets a a specific limitation in how a paymentInstrument can be used. You can limit a transaction based on the amount, number of transactions, countries, MCCs, and more.

You can also combine transactions rules to represent more complex authorisation logic. For more information, refer to Transaction rules.

Payment stages

Once a payment has been attempted on a payment instrument, a balance platform payment resource is created. This resource includes information about whether the payment was approved or refused. You will receive a notification webhook of the payment creation.

Each payment goes through multiple payment stages which includes stages such as captured and refunded.