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.
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 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 an authorized balance platform payment:
{
"data": {
"accountHolder": {
"description": "Example account holder John Doe",
"id": "AH32272223222B59MTF7458DP"
},
"amount": {
"currency": "EUR",
"value": -1000
},
"authCode": "809649",
"balanceAccount": {
"description": "My Balance Account",
"id": "BA3227C223222B5B9SCR82TMV"
},
"balancePlatform": "YOUR BALANCE PLATFORM",
"creationDate": "2020-05-06T16:26:24+02:00",
"id": "1W1UG35MQQD8WJZI",
"merchantData": {
"mcc": "7999",
"merchantId": "526567789012346",
"nameLocation": {
"city": "Amsterdam",
"country": "NLD",
"name": "Test Merchant ecom",
"rawData": "Test Merchant ecom Amsterdam NLD"
}
},
"paymentInstrument": {
"id": "PI1234C567890B5B9XWKW637Z"
},
"relayedAuthorisationData": {
"metadata": {
"key1": "value1",
"key2": "value2",
"key3": "value3"
}
},
"status": "Authorised",
"validationResult": [
{
"result": "valid",
"type": "MaxAuthAmount"
},
{
"result": "valid",
"type": "Validation"
},
{
"result": "valid",
"type": "PaymentInstrumentExpirationCheck"
},
{
"result": "valid",
"type": "Screening"
},
{
"result": "valid",
"type": "RelayedAuthorisation"
},
{
"result": "valid",
"type": "TransactionValidation"
},
{
"result": "valid",
"type": "CVC2"
}
]
},
"environment": "test",
"type": "balancePlatform.payment.created"
}