Notification webhooks

The Balance Platform sends notification webhooks to communicate events that are triggered by your system (creating or updating resources) and those triggered by your users (payments and refunds).

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

Configure webhook endpoint

You will need to expose an endpoint that can:

• Receive a JSON object.
• Open a TCP port for https traffic on port 443, 8443, or 8843.
• 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 pertain to either a relayed authorization or to a resource creation or update.

Each notification includes an hmac-signature header. Validate this HMAC signature to ensure the notification came from the Adyen system.

You can determine the notification by the type, such as balancePlatform.payment.created or balancePlatform.refund.created. If the notification is about a resource being created or updated, the resource is included in the data field.

Here is an example notification of a an authorised balance platform payment:

{
  "platform":"test",
  "type":"balancePlatform.payment.created",
  "data":{
    "id":"BPP1234123412341234",
    "amount":{
      "currency":"EUR",
      "value":1500,
    },
    "status":"AUTHORISED",
    "pspReference" : "9915717338410470",
    "createdAt":"2019-11-17T09:00:00",
    "balanceAccount":{
      "id":"BA1234123412341234"
    },
    "paymentInstrument":{
      "id":"PI1234123412341234"
    },
    "authData":{
      "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"
      },
      "validationResult":{
        "sanctionScreening":"valid",
        "cvc":"valid",
        "cardExpiration":"valid",
        "avsStreet":"valid",
        "avsPostalCode":"valid"
      }
    },
    "reference":"myBalancePlatformPayment12345"
  }
}