Managing recurring top-ups using the Top-up API is an asynchronous process. A successful API response does not necessarily indicate that a recurring top-up is successfully created, updated, or deleted.
To stay up to date about changes to the recurring top-ups in your platform, we recommend that you subscribe to Configuration webhooks.
To stay up to date about the direct debit triggered by the recurring top-up, we recommend that you subscribe to Transfer webhooks and Transaction webhooks.
Requirements
| Requirement | Description |
|---|---|
| Integration type | Adyen Issuing integration. |
| Webhooks | Subscribe to the following webhook(s):
|
| Setup steps | Before you begin:
|
Configuration webhooks
To stay updated about changes to recurring top-ups in your balance platform, you can listen to the following webhooks:
balancePlatform.balanceAccount.recurringTopUp.created: sent when a new recurring top-up is successfully created.balancePlatform.balanceAccount.recurringTopUp.updated: sent when an existing recurring top-up is successfully updated.balancePlatform.balanceAccount.recurringTopUp.deleted: sent when an existing recurring top-up is successfully deleted.
In these webhooks, pay attention to the following fields:
| Parameter | Description |
|---|---|
accountId |
The unique identifier of the balance account on which the recurring top-up is configured. |
webhookTopUpConfiguration |
An object that contains the details of the recurring top-up. |
type |
The type of webhook, indicating whether a recurring top-up is created, updated, or deleted. |
Examples
Recurring top-up created
Recurring top-up updated
Recurring top-up deleted
Transfer webhooks
When a top-up is triggered on your balance platform, Adyen sends the following transfer webhooks:
- balancePlatform.transfer.created: which informs your server that an outgoing direct debit request is initiated from a balance account in your balance platform.
- balancePlatform.transfer.updated: which informs your server of the transfer status changes.
Identify top-up related transfer webhooks
You can identify transfer webhooks triggered by payout-related events by looking at the following values:
| Parameter | Description | Value |
|---|---|---|
category |
The category of the transfer. | bank |
type |
Specifies the type of the transfer. | bankDirectDebit |
Examples
Top-up initiated
Top-up authorized
Top-up booked
Transfer failure examples
A transfer can fail during processing even if the initial API request is accepted. When a transfer cannot be completed, the status of the transfer is updated, and a balancePlatform.transfer.updated notification is sent. Use the following examples to identify the reasons for these failures.
In the following example, a transfer is rejected if it fails internal validation or transaction rules before it can be finalized.
In the following example, a transfer is marked as returned when the funds reach the destination bank but are sent back, usually due to a closed account or incorrect beneficiary details.
Transaction webhooks
The transaction webhook balancePlatform.transaction.created informs your server that Adyen has credited funds to your balance account.
Transaction webhooks can be used in combination with Transfer webhooks to stay fully up to date about the status of your transfers. While a transfer webhook is sent for every status change, transaction webhooks are only sent when the funds from the transfer are credited to the balance account.
Here is an example of a transaction webhook you receive when a top-up is credited to your balance account: