Processing card payments

When a payment is attempted with an Adyen-issued card, you can control the approval through:

• Relayed authorization: Our platform sends you a webhook for each payment attempt. You have to approve or deny each payment attempt.
• Transaction rules: Create limitations based on conditions such as maximum amount, maximum number of transaction, 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 authorization. A payment that is 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. After the inital payment, you will need to manage the payment lifecycle.

Relayed authorization

Relayed authorization gives you full control over payment processing.

With each relayed authorization 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.

To start receiving webhooks, expose an endpoint. When a payment attempt comes in, we will send an HTTP POST with a relayed authorization message to the endpoint you specified.

Here is an example incoming request:

{
   "accountHolder" : {
      "balancePlatform" : "ExampleMarketplaceInstance1",
      "id" : "AH1234123412341234",
      "status" : "Active"
   },
   "merchantInformation" : {
      "mcc" : "7999",
      "merchantId" : "526567789012346",
      "city" : "Amsterdam",
      "country" : "NLD",
      "name" : "MC Test Merchant Ref m",
      "rawData" : "MC Test Merchant Ref m Amsterdam     NLD",
      "acquirerInstitutionIDCode" : "013445",
      "forwardingInstitutionIDCode" : "200353"
   },
   "amount" : {
      "currency" : "EUR",
      "value" : -1500
   },
   "authCode" : "747458",
   "balanceAccount" : {
      "accountHolderId" : "AH1234123412341234",
      "balancePlatformId" : "ExampleMarketplaceInstance1",
      "id" : "BA1234123412341234",
      "status" : "Active",
      "balances" : [
         {
            "currency":"EUR",
            "balanceAfter" : {
               "currency" : "EUR",
               "value" : 98500
            },
            "balanceBefore" : {
               "currency" : "EUR",
               "value" : 100000
            },
            "mutationAmount" : {
               "currency" : "EUR",
               "value" : -1500
            }
         }
      ]
   },
   "paymentInstrument" : {
      "balanceAccountId" : "BA1234123412341234",
      "issuingCountryCode" : "NL",
      "product" : "mastercard",
      "type" : "card",
      "card" : {
         "cardholderName" : "Simon Hopper",
         "formFactor" : "virtual",
         "bin" : "4111111",
         "expiration" : {
            "month" : "12",
            "year" : "2022"
         },
         "last4Digits" : "1111"
      },
      "id" : "PI1234123412341234",
      "status" : "activated"
   },
   "pspReference" : "9915717338410470",
   "validationResult":{
     "sanctionScreening":"valid",
     "cvc":"valid",
     "cardExpiration":"valid",
     "avsStreet":"valid",
     "avsPostalCode":"valid"
   }
}

When approving or denying a transaction, you need to respond with an HTTP 200 status code.

For example, to approve a transaction, respond with an HTTP 200 status code with a message containing result authorised.

{
  "result" : {
    "status" : "authorised",
    "details":"{hint:Human-readable field for your support agents and other staff}Payment looks good{/hint}"
  },
  "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}"
  }
}

You can also include metaData object in the response, containing key-value pairs that you can use in your reporting or other business process.

To reject a transaction, respond with an HTTP 200 status code with a message containing result refused.

{
  "result" : {
    "status" : "refused",
    "details":"{hint:Human-readable field for your support agents and other staff}Payment not allowed{/hint}"
  },
  "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 do not respond within 1500 milliseconds or if you return a different HTTP status code, we will use the fallback logic you specify.

Relayed authorization fallback

When using relayed authorization, 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

Set these rules within the Adyen Issuing dashboard.

Transaction Rules

A transactionRule is 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 authorization logic.

Payment lifecycle

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

Each payment has a payment lifecycle which includes multiple stages such as captured, refunded, and disputed. Each stage will have a corresponding resource and update the original payment's status.