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