You can create recurring top-ups to automatically pull funds into your balance accounts when needed. This ensures that your balance accounts are adequately funded and have sufficient balance for day-to-day activities.
A recurring top-up triggers outgoing direct debit requests to a bank account, based on the settings you configure. These settings determine the amount, frequency, and source of funds for the direct debit requests. Adyen then books the funds from the top-up to your balance account.
Requirements
| Requirement | Description |
|---|---|
| Integration type | Adyen Issuing integration. |
| API credential roles | Make sure that you have the credentials for the Configuration API with the following role:
|
| Webhooks | Subscribe to the following webhooks: |
| Capabilities | To top up using a transfer instrument, you need the following capability:
Before attempting a transfer, verify that this capability is active and has a valid verificationStatus. You can check this via the verificationStatus.Note, if you need to enable this capability see request additional capabilities. |
| Limitations | This feature does not support on-demand top-ups. |
| Setup steps | Make sure that your top-up source has enough balance to fund the top-up. |
Create a recurring top-up
To create a recurring top-up, make a POST /balanceAccounts/{balanceAccountId}/recurringTopUps request. In your request, specify the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
balanceAccountId |
Path |  |
The unique identifier of the balance account. |
counterparty |
Request body | |
An object containing details about the counterparty that is funding the top-up. For more information, see Counterparty. |
description |
Request body | |
Your description for the recurring top-up. Format: Maximum length is 140 characters. If you set a longer description, it will be cut off at 140 characters. |
topUpAmount |
Request body | |
An object containing the currency and value of the top-up amount, in minor units. Use this to specify the amount you want to top up the balance account. For more information, see Top-up amount. |
trigger |
Request body | |
An object containing details about when to trigger the top-up. This includes the minimum balance value and currency that serves as the threshold. For more information, see Trigger. |
status |
Request body | The status of the recurring top-up. Possible values:
|
|
referenceForBeneficiary |
Request body | The reference sent to the counterparty (the source of the funds) for the direct debit request. Format:
|
Required for all transactions. 
Required for particular setups. 
Recommended for all transactions, but not required.
Counterparty
In the counterparty object, specify the following parameter.
| Parameter | Type | Required | Description |
|---|---|---|---|
transferInstrumentId |
Request body | |
Use case: Required if the top-up source is a transfer instrument. The unique identifier of the transfer instrument that is funding the top-up. |
Required for all transactions. Required for particular setups. Recommended for all transactions, but not required.
Top-up amount
In the topUpAmount object, specify one of the following parameters. If you specify both parameters, the request fails.
| Parameter | Type | Required | Description |
|---|---|---|---|
fixed |
Request body |  |
Use case: Required if you use a fixed top-up amount. The fixed amount with which you want to top up the balance account. Format: Use minor units. |
target |
Request body | |
Use case: Required if you want to top up to a target amount. The target balance for the balance account that the top-up must achieve. Format: Use minor units. |
Required for all transactions. Required for particular setups. Recommended for all transactions, but not required.
Trigger
In the trigger object, specify the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schedule |
Request body | The frequency at which to check the available balance on the balance account. If not specified, the balance is continuously monitored. Possible values:
|
|
threshold |
Request body | |
The minimum balance you want to keep in the account. During the regular checks defined in trigger.schedule, if the available balance is below the threshold amount, we trigger a top-up. |
Example - Create recurring top-up
You have a balance account with the following details:
- Balance account ID: BA00000000000000000000001
- Available balance: USD 500.00
You want to create a recurring top-up for this balance account with the following settings:
- Source of funds: transfer instrument with ID TI00000000000000000000001.
- Top-up amount: a target amount of USD 1000 for the balance account.
- Schedule: check the available balance weekly, every Monday at 7:00 AM.
- Threshold: top up the balance account only if the available balance drops below USD 250.
Here is an example request to create this recurring top-up:
You receive the following response:
Error messages and failure reasons
Use the following table to identify and troubleshoot errors returned in the API response during a top-up.
| Error message | Description |
|---|---|
| Unauthorised. | The request failed due to invalid credentials. |
Could not find balance account with id. |
The user does not have access to the balance account. |
| No routes could be found using the provided sweep. | No route is configured. |
| Account top up currency mismatch. | There is a currency mismatch between the balance account and the request. |
Invalid transfer instrument with id transferInstrumentId. |
The provided transferInstrumentId is invalid. |
| Legal entity not having access to transfer instrument. | The legal entity does not have access to the transfer instrument provided. |
balanceAccountHolder has invalid account status inactive. |
The balance account holder has an inactive account status. |
Missing Capabilities receiveFromTransferInstrument for balanceAccountHolder. |
The balance account holder is missing the receiveFromTransferInstrument capability. |