When a top-up is triggered in your marketplace, Adyen sends two kinds of webhooks:
- Standard webhooks, which inform your server of incoming funds to your merchant account. When a top-up request triggers a direct debit or a payment authorization, Adyen sends an AUTHORISATION webhook to your server.
- Transfer webhooks, which inform your server of incoming transfers or payments to balance accounts in your marketplace.
To keep track of events related to top-ups in your marketplace, make sure that:
- Your server can receive and accept webhooks.
- You subscribed to the Transfer webhooks in your Balance Platform Customer Area.
Scheduled top-ups
Transfer webhooks triggered by scheduled top-ups have the following values:
| Parameter | Description | Value |
|---|---|---|
| category | Specifies the category of the transfer. | platformPayment |
| direction | The direction of the transfer based on the balance account. | incoming |
| type | Specifies the type of the transfer. | capture |
In the example below, you configure a pull sweep to top-up your user's first balance account.
- The triggerAmount is EUR 5000.00. The transfer is initiated when the balance in the balance account drops below EUR 5000.00.
- The sweepAmount is EUR 1000.00. This is the amount that is credited to the balance account.
When the balance drops below EUR 5000.00 and the top-up is triggered, your server receives webhooks for the balance account involved in the transfer (your user's first balance account). Adyen sends webhooks for each stage of the transfer.
Scheduled top-up initiated
When an incoming transfer request is received to credit funds to your user's balance account, Adyen sends a balancePlatform.transfer.created webhook with status received and direction incoming. The webhook provides information about the transfer, such as the amount and which user and balance account is credited with the funds.
{ "data": { "accountHolder": { "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 100000 } ], "category": "platformPayment", "categoryData": { "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "creationDate": "2023-02-28T13:30:05+02:00", "direction": "incoming", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" } ], "id": "JN4227222422265", "reason": "approved", "sequenceNumber": 1, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "received", "type": "capture" }, "environment": "test", "type": "balancePlatform.transfer.created" }
Scheduled top-up authorized
When the incoming transfer request is authorised, Adyen sends a balancePlatform.transfer.updated webhook with status authorised.
Scheduled top-up captured
When the funds are credited to your user's balance account, Adyen sends a balancePlatform.transfer.updated webhook with status captured and the transactionId.
{ "data": { "accountHolder": { "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "platformPayment", "categoryData": { "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "creationDate": "2023-02-28T13:30:05+02:00", "direction": "incoming", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": -100000, "reserved": 100000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:20+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": -100000 } ], "status": "captured", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T00:00:00+02:00" } ], "id": "JN4227222422265", "reason": "approved", "sequenceNumber": 3, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "captured", "type": "capture" }, "environment": "test", "type": "balancePlatform.transfer.updated" }
When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook which includes information about the top-up.
{ "data": { "id": "EVJN42272224222B5JB8BRC84N686ZEUR", "amount": { "value": 100000, "currency": "EUR" }, "status": "booked", "transfer": { "id": "JN4227222422265", "reference": "Your reference for the top-up", }, "valueDate": "2023-03-01T00:00:00+02:00", "bookingDate": "2023-02-28T13:30:20+02:00", "creationDate": "2023-02-28T13:30:05+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder", "reference": "Your reference for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" }
On-demand top-ups
On-demand top-ups are initiated using payment requests. Just like other payments processed by your marketplace, they incur transaction fees. Adyen sends separate webhooks for the top-up amount, and for the transaction fees incurred by the top-up.
In the example below, your user makes a payment to top up their balance account.
- EUR 1000.00 is booked to your user's first balance account as the top-up amount.
- EUR 3.44 is deducted from your user's second balance account as the transaction fees incurred by the top-up.
Your server receives webhooks for each balance account involved and each split of the total top-up amount specified in the splits array of your POST /payments request.
Transfer webhooks triggered by on-demand top-ups have the following values:
| Parameter | Description | Value |
|---|---|---|
| category | Specifies the category of the transfer. | topUp |
| direction | The direction of the transfer based on the balance account. | incoming |
| type | Specifies the type of the transfer. | capture |
| platformPaymentType | Specifies the nature of each transfer on the balance platform. This parameter helps categorize transfers so you can reconcile transactions at a later time using the Balance Platform Accounting Report. | TopUp |
Adyen sends webhooks for each stage of the transfer.
On-demand top-up initiated
When a payment request is received to credit funds to your user's balance account, Adyen sends a balancePlatform.transfer.created webhook with status received and direction incoming. The webhook provides information about the transfer, such as the payment and split references and which user and balance account is credited with the funds.
{ "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 100000 } ], "category": "topUp", "categoryData": { "modificationMerchantReference": "Your reference for the capture.", "modificationPspReference": "WNS7WQ756L2GWR82", "paymentMerchantReference": "YOUR_ORDER_NUMBER", "platformPaymentType": "TopUp", "pspPaymentReference": "M5N7TQ4TG5PFWR50", "type": "platformPayment" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your description for the top-up", "direction": "incoming", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "SKRL00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" } ], "id": "JN4227222422265", "reason": "approved", "reference": "Your reference for the top-up", "sequenceNumber": 1, "status": "received", "type": "capture" }, "environment": "test", "timestamp": "2024-12-20T13:51:24.928Z", "type": "balancePlatform.transfer.created" }
On-demand top-up authorized
When the transfer request is authorized, Adyen sends a balancePlatform.transfer.updated webhook with status authorised.
On-demand top-up captured
When the funds are credited to your user's balance account, Adyen sends a balancePlatform.transfer.updated webhook with status captured and the transactionId.
{ "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 100000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "topUp", "categoryData": { "modificationMerchantReference": "Your reference for the capture.", "modificationPspReference": "WNS7WQ756L2GWR82", "paymentMerchantReference": "YOUR_ORDER_NUMBER", "platformPaymentType": "TopUp", "pspPaymentReference": "M5N7TQ4TG5PFWR50", "type": "platformPayment" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your description for the transfer", "direction": "incoming", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "SKRL00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": 100000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "SKRL00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": -100000, "reserved": 100000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:20+02:00", "id": "SKRL00000000000000000000000003", "mutations": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": -100000 } ], "status": "captured", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T00:00:00+02:00" } ], "id": "JN4227222422265", "reason": "approved", "reference": "Your reference for the top-up", "sequenceNumber": 3, "status": "captured", "type": "capture" }, "environment": "test", "timestamp": "2024-12-20T13:51:24.928Z", "type": "balancePlatform.transfer.updated" }
When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook which includes information about the top-up.
{ "data": { "id": "EVJN42272224222B5JB8BRC84N686ZEUR", "amount": { "value": 100000, "currency": "EUR" }, "status": "booked", "transfer": { "id": "JN4227222422265", "reference": "Your reference for the top-up" }, "valueDate": "2023-03-01T00:00:00+02:00", "bookingDate": "2023-02-28T13:30:20+02:00", "creationDate": "2023-02-28T13:30:05+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder", "reference": "Your reference for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" }