Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Notification webhooks

Learn how to configure and use notification webhooks from the Balance Platform.

The Balance Platform sends notification webhooks to communicate events such as payments and fund transfers.

Since many of the events on the Balance Platform are asynchronous, handling notifications is required for a successful integration.

The Balance Platform notification webhooks return a different JSON object from the core Adyen platform. If you want to reuse an existing endpoint, make sure the endpoint is able to handle the new notification structure.

Configure notification webhook endpoint

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. We will provide a shared secret that you will use to validate HMAC signatures.

Handling a notification

All notifications in the Balance Platform are about payments or fund transfers.

You can determine the notification by the type, such as balancePlatform.payment.created.

Here is an example notification for an authorised payment:

Payment notification
{
   "data" : {
      "accountHolder" : {
         "description" : "S.Hopper - Staff 123",
         "id" : "AHA1B2C3D4E5F6G7H8I9J0"
      },
      "{hint:Amount converted to the default currency code}amount{/hint}" : {
         "currency" : "EUR",
         "value" : -88
      },
      "authCode" : "245773",
      "balanceAccount" : {
         "description" : "S.Hopper - Main balance account",
         "id" : "BAB8B2C3D4E5F6G7H8D9J6GD4"
      },
      "balancePlatform" : "YOUR_BALANCE_PLATFORM_ACCOUNT",
      "creationDate" : "2020-08-16T21:10:32+02:00",
      "{hint:The payment ID}id{/hint}" : "3UHFB75NIZPDCWN0",
      "merchantData" : {
         "mcc" : "7999",
         "merchantId" : "526567789010068",
         "nameLocation" : {
            "city" : "Amsterdam",
            "country" : "NLD",
            "name" : "NB Bookstore",
            "rawData" : "NB Bookstore Amsterdam NLD"
         }
      },
      "{hint:Original value and currency of the payment}originalAmount{/hint}" : {
         "currency" : "USD",
         "value" : -100
      },
      "paymentInstrument" : {
         "id" : "PI322FN2235HGP5BNR47LCX2D"
      },
      "relayedAuthorisationData" : {
         "metadata" : {
            "key1" : "value1",
            "key2" : "value2"
         },
         "reference" : "1594926632477"
      },
      "{hint:The result of the payment}status{/hint}" : "Authorised",
      "validationResult" : [
         {
            "result" : "valid",
            "type" : "PaymentInstrumentExpirationCheck"
         },
         {
            "result" : "valid",
            "type" : "RelayedAuthorisation"
         },
         {
            "result" : "valid",
            "type" : "CVC2"
         },
         {
            "result" : "valid",
            "type" : "TransactionRules"
         },
         {
            "result" : "valid",
            "type" : "ExchangeAmount"
         },
         {
            "result" : "valid",
            "type" : "Validation"
         },
         {
            "result" : "valid",
            "type" : "TransactionValidation"
         },
         {
            "result" : "valid",
            "type" : "Screening"
         },
         {
            "result" : "valid",
            "type" : "MaxAuthAmount"
         }
      ]
   },
   "environment" : "test",
   "type" : "balancePlatform.payment.created"
}