Issuin icon

Manage recurring top-ups

Learn how to view, change, and delete recurring top-ups.

After you create a recurring top-up, we automatically trigger top-ups to your balance account according to the settings you configured.

If you need to view or change these settings, or delete a recurring top-up, you can do so using the Configuration API.

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:
  • BankAPI Advanced Webservice role
Webhooks Subscribe to the following webhooks:
Capabilities To top up using a transfer instrument, you need the following capability:
  • receiveFromTransferInstrument

Before attempting a transfer, verify that this capability is active and has a valid verificationStatus. You can check this via the verificationStatus.

Note: 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.

View recurring top-ups

After creating recurring top-ups for your balance account, you can make requests to get an overview of them. You can use query parameters to determine how many results to show (limit), and where the list starts (cursor). The list is always shown in chronological order of when you created the top-up.

When your list of results consists of more than one page, you can navigate through the pages using the API. The following list provides a high-level overview of the steps required to complete this process. We will then dive into the details for each step.

  1. Make an initial GET request without the cursor parameter.
  2. Take note of the cursor value in the response, which shows the first page of results.
  3. Make a second GET request including the cursor parameter.
  4. Take note of the cursor values in the response, which shows the second page of results. You can use these values to navigate to the next or previous page of results.

To view all recurring top-ups configured for a balance account:

1. Make a GET request without the cursor parameter

Make a initial GET /balanceAccounts/{balanceAccountId}/recurringTopUps. In your request, specify the following parameters:

Parameter Type Required Description
balanceAccountId Path Required The unique identifier of the balance account for which you want to retrieve recurring top-ups.
limit Query The number of results (recurring top-ups) to show in the first page of the response. By default, the response shows 10 results. The response also includes links to the next page of the results.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

Here is an example request to retrieve a list of recurring top-ups for BA00000000000000000000001, and restrict this list to 2 results in the first page.

2. View the first page of results

Take note of the array in the response that returns a list of recurring top-ups configured for your balance account, according to the limit you defined. Each object in the array returns the following parameters:

Parameter Type Required Description
id Response body Required The unique identifier of the recurring top-up.
counterparty.transferInstrumentId Response body Required Use case: Returned if the top-up source is a transfer instrument.

The unique identifier of the transfer instrument that is funding the top-up.
description Response body Required Your description for the recurring top-up.
topUpAmount.fixed Response body Conditionally required Use case: Returned if you use a fixed top-up amount.

The fixed amount with which you want to top up the balance account.

Format: In minor units.
topUpAmount.target Response body Conditionally required Use case: Returned if you want to top up to a target amount.

The target balance for the balance account that the top-up must achieve.

Format: In minor units.
trigger.schedule Response body The frequency at which to check the available balance on the balance account. If not specified, the balance is continuously monitored.

Possible values:
  • weekdays: from Monday to Friday at 07:00 AM
  • weekly: on Mondays at 07:00 AM)
  • monthly: on the 1st of each month at 07:00 AM
  • null (default): continuous monitoring
trigger.threshold Response body Required 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.
status Response body Required The status of the recurring top-up.

Possible values:
  • active (default)
  • inactive
referenceForBeneficiary Response body The reference sent to the counterparty for the direct debit (the source of the funds).

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

The response also returns the following parameter to help you navigate through the list of results:

Parameter Type Required Description
link.next.href Response body Conditionally required Use case: Returned if there is more than 1 page of results, based on the limit you defined.

The link leading to the next page of results. This link includes the cursor which you can use as a query in your GET request to view the next page of results.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

Here is an example response showing a list of recurring top-ups configured for balance account BA00000000000000000000001, where the list is restricted to 2 results per page.

3. Make a GET request including the cursor parameter

To view the next page of results, make a second GET /balanceAccounts/{balanceAccountId}/recurringTopUps. In your request, specify the following parameters:

Parameter Type Required Description
balanceAccountId Path Required The unique identifier of the balance account for which you want to retrieve recurring top-ups.
cursor Query Conditionally required Use case: Required if you want to see the next or previous page of results. Use only if this is not your first GET request.

The encrypted identifier of the recurring top-up from which you want your list of results to start. You can find the cursor in the response of your previous GET request. By default, the list of results starts from the first top-up created for that balance account.
limit Query The number of results (recurring top-ups) to show in the first page of the response. By default, the response shows 10 results. The response also includes links to the next and previous page of the results.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

Here is an example request to retrieve the next page of results for BA00000000000000000000001. The results start from where the previous page ended, and includes 2 results per page.

4. View the next page of results

Take note of the array in the response that returns a list of recurring top-ups configured for your balance account, according to the cursor and limit you defined. In addition to the array, the response also returns the following parameters to help you navigate through the list of results:

Parameter Type Required Description
link.next.href Response body Conditionally required Use case: Returned if there is more than 1 page of results, based on the limit you defined.

The link leading to the next page of results. This link includes the cursor which you can use as a query in your GET request to view the next page of results.
link.prev.href Response body Conditionally required Use case: Returned if there is more than 1 page of results, based on the cursor and limit you defined.

The link leading to the previous page of results. This link includes the cursor which you can use as a query in your GET request to view the previous page of results.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

Here is an example response showing the next page of a list of recurring top-ups configured for balance account BA00000000000000000000001, where the list is restricted to 2 results per page.

Update a recurring top-up

To update a recurring top-up, make a PATCH /balanceAccounts/{balanceAccountId}/recurringTopUps/{topUpId} request. In your request, specify the parameters you want to update:

If you do not specify a parameter, or explicitly set it to null, the value remains the same as what you specified in the POST request.

Parameter Type Required Description
balanceAccountId Path Required The unique identifier of the balance account.
topUpId Path Required The unique identifier of the recurring top-up you want to update.
counterparty.transferInstrumentId Request body Required Use case: Required if you want to update to a new transfer instrument ID.
description Request body Conditionally required Use case: Required if you want to change the description.

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.fixed Request body Conditionally required Use case:
Required if:
  • You want to update to a new fixed top-up amount.
  • You want to change from a target to a fixed amount.
  • You want to change from a fixed to a target amount. In this case, set fixed to null.

The fixed amount with which you want to top up the balance account. Set to null if you want to change from a fixed to a target amount.
topUpAmount.target Request body Conditionally required Use case:
Required if:
  • You want to update to a new target top-up amount.
  • You want to change from a fixed to a target amount.
  • You want to change from a target to a fixed amount. In this case, set target to null.

The target balance for the balance account that the top-up must achieve. Set to null if you want to change from a target to a fixed amount.
trigger.schedule Request body Conditionally required Use case: Required if you want to change the schedule.

The frequency at which to check the available balance on the balance account. If not specified, the balance is continuously monitored.

Possible values:
  • weekdays: from Monday to Friday at 07:00 AM
  • weekly: on Mondays at 07:00 AM
  • monthly: on the 1st of each month at 07:00 AM
  • null: continuous monitoring
trigger.threshold Request body Conditionally required Use case: Required if you want to change the threshold.

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.
status Request body Conditionally required Use case: Required if you want to change the status.

The status of the recurring top-up.

Possible values:
  • active (default)
  • inactive
referenceForBeneficiary Request body Conditionally required Use case: Required if you want to change the reference for the beneficiary.

The reference sent to the counterparty for the direct debit (the source of the funds).

Format:
  • Only alphanumeric characters.
  • Maximum length is 80 characters.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

You created a recurring top-up (TU0000000000001) for balance account BA00000000000000000000001 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.

You now want to update the following details:

  • Change the source of the funds transfer instrument with ID TI00000000000000000000002.
  • Change the top-up amount to a fixed amount of USD 750.
  • Deactivate the top-up.

Here is an example request to update this recurring top-up:

You receive the following response:

Delete a recurring top-up

To delete a recurring top-up, make a DELETE /balanceAccounts/{balanceAccountId}/recurringTopUps/{topUpId} request. In your request, specify the following parameters.

Parameter Type Required Description
balanceAccountId Path Required The unique identifier of the balance account.
topUpId Path Required The unique identifier of the recurring top-up you want to delete.

This is the required icon. Required for all transactions.
This is the conditionally required icon. Required for particular setups.
This is the recommended icon. Recommended for all transactions, but not required.

Here is an example request to delete a recurring top-up with ID TU0000000000001:

If the request is successful, you receive a 204 - No Content response.

See also