When a top-up is triggered in your platform, 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 platform.
To keep track of events related to top-ups in your platform, 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.
Webhook example
Scheduled top-up authorized
When the incoming transfer request is authorised, Adyen sends a balancePlatform.transfer.updated webhook with status authorised.
Webhook example
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.
Webhook example
When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook which includes information about the top-up.
On-demand top-ups
On-demand top-ups are initiated using payment requests. Just like other payments processed by your platform, 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.
Webhook example
On-demand top-up authorized
When the transfer request is authorized, Adyen sends a balancePlatform.transfer.updated webhook with status authorised.
Webhook example
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.
Webhook example
When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook which includes information about the top-up.