{"title":"Manage recurring top-ups","category":"default","creationDate":1571779920,"content":"

After you create a recurring top-up, we automatically trigger top-ups to your balance account according to the settings you configured.<\/p>\n

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

Requirements<\/h2>\n\n\n\n\n\n\n\n\n\n\n
Requirement<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Integration type<\/strong><\/td>\n Adyen Issuing integration. <\/td>\n<\/tr>\n
API credential roles<\/a><\/strong><\/td>\nMake sure that you have the credentials for the Configuration API<\/a> with the following role:
  • BankAPI Advanced Webservice role<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
Webhooks<\/a><\/strong><\/td>\nSubscribe to the following webhooks:
Capabilities<\/a><\/strong><\/td>\nTo top up using a transfer instrument, you need the following capability:
Limitations<\/strong><\/td>\nThis feature does not support on-demand top-ups.<\/td>\n<\/tr>\n
Setup steps<\/strong><\/td>\nMake sure that your top-up source<\/a> has enough balance to fund the top-up.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

View recurring top-ups<\/h2>\n

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<\/code>), and where the list starts (cursor<\/code>). The list is always shown in chronological order of when you created the top-up.<\/p>\n

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.<\/p>\n

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

    To view all recurring top-ups configured for a balance account:<\/p>\n

    1. Make a GET request without the cursor parameter<\/h3>\n

    Make a initial GET \/balanceAccounts\/{balanceAccountId}\/recurringTopUps<\/code>. In your request, specify the following parameters:<\/p>\n\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    balanceAccountId<\/code><\/td>\nPath<\/td>\n\"Required\"<\/span><\/td>\nThe unique identifier of the balance account for which you want to retrieve recurring top-ups.<\/td>\n<\/tr>\n
    limit<\/code><\/td>\nQuery<\/td>\n<\/td>\nThe 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.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    \"This Required for all transactions.
    \"This Required for particular setups.
    \"This Recommended for all transactions, but not required.<\/p>\n

    \n \n
    \n
    \n <\/i>\n
    \n

    Example request - View recurring top-ups (first page)<\/h4>\n <\/div>\n <\/div>\n
    \n \n

    Here is an example request to retrieve a list of recurring top-ups for BA00000000000000000000001<\/strong>, and restrict this list to 2 results in the first page.<\/p>\n

    \n <\/code-sample>\n<\/div>\n\n <\/div>\n <\/div>\n<\/div>\n\n

    2. View the first page of results<\/h3>\n

    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<\/code> you defined. Each object in the array returns the following parameters:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    id<\/code><\/td>\nResponse body<\/td>\n\"Required\"<\/span><\/td>\nThe unique identifier of the recurring top-up.<\/td>\n<\/tr>\n
    counterparty.transferInstrumentId<\/code><\/td>\nResponse body<\/td>\n\"Required\"<\/span><\/td>\nUse case<\/strong>: Returned if the top-up source is a transfer instrument.

    The unique identifier of the transfer instrument that is funding the top-up.<\/td>\n<\/tr>\n
    description<\/code><\/td>\nResponse body<\/td>\n\"Required\"<\/span><\/td>\nYour description for the recurring top-up.<\/td>\n<\/tr>\n
    topUpAmount.fixed<\/code><\/td>\nResponse body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Returned if you use a fixed top-up amount.

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

    Format<\/strong>: In minor units<\/a>.<\/td>\n<\/tr>\n
    topUpAmount.target<\/code><\/td>\nResponse body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: 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<\/strong>: In minor units<\/a>.<\/td>\n<\/tr>\n
    trigger.schedule<\/code><\/td>\nResponse body<\/td>\n<\/td>\nThe frequency at which to check the available balance on the balance account. If not specified, the balance is continuously monitored.

    Possible values<\/strong>:
    • weekdays<\/strong>: from Monday to Friday at 07:00 AM<\/li>
    • weekly<\/strong>: on Mondays at 07:00 AM)<\/li>
    • monthly<\/strong>: on the 1st of each month at 07:00 AM<\/li>
    • null<\/strong> (default): continuous monitoring<\/li><\/ul><\/td>\n<\/tr>\n
    trigger.threshold<\/code><\/td>\nResponse body<\/td>\n\"Required\"<\/span><\/td>\nThe minimum balance you want to keep in the account. During the regular checks defined in trigger.schedule<\/code>, if the available balance is below the threshold amount, we trigger a top-up.<\/td>\n<\/tr>\n
    status<\/code><\/td>\nResponse body<\/td>\n\"Required\"<\/span><\/td>\nThe status of the recurring top-up.

    Possible values<\/strong>:
    • active<\/strong> (default)<\/li>
    • inactive<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
    referenceForBeneficiary<\/code><\/td>\nResponse body<\/td>\n<\/td>\nThe reference sent to the counterparty for the direct debit (the source of the funds).<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    \"This Required for all transactions.
    \"This Required for particular setups.
    \"This Recommended for all transactions, but not required.<\/p>\n

    The response also returns the following parameter to help you navigate through the list of results:<\/p>\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    link.next.href<\/code><\/td>\nResponse body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Returned if there is more than 1 page of results, based on the limit<\/code> you defined.

    The link leading to the next page of results. This link includes the cursor<\/code> which you can use as a query in your GET request to view the next page of results.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    \"This Required for all transactions.
    \"This Required for particular setups.
    \"This Recommended for all transactions, but not required.<\/p>\n

    \n \n
    \n
    \n <\/i>\n
    \n

    Example response - View recurring top-ups (first page)<\/h4>\n <\/div>\n <\/div>\n
    \n \n

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

    \n <\/code-sample>\n<\/div>\n\n <\/div>\n <\/div>\n<\/div>\n\n

    3. Make a GET request including the cursor parameter<\/h3>\n

    To view the next page of results, make a second GET \/balanceAccounts\/{balanceAccountId}\/recurringTopUps<\/code>. In your request, specify the following parameters:<\/p>\n\n\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    balanceAccountId<\/code><\/td>\nPath<\/td>\n\"Required\"<\/span><\/td>\nThe unique identifier of the balance account for which you want to retrieve recurring top-ups.<\/td>\n<\/tr>\n
    cursor<\/code><\/td>\nQuery<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: 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.<\/td>\n<\/tr>\n
    limit<\/code><\/td>\nQuery<\/td>\n<\/td>\nThe 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.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    \"This Required for all transactions.
    \"This Required for particular setups.
    \"This Recommended for all transactions, but not required.<\/p>\n

    \n \n
    \n
    \n <\/i>\n
    \n

    Example request - View recurring top-ups (next page)<\/h4>\n <\/div>\n <\/div>\n
    \n \n

    Here is an example request to retrieve the next page of results for BA00000000000000000000001<\/strong>. The results start from where the previous page ended, and includes 2 results per page.<\/p>\n

    \n <\/code-sample>\n<\/div>\n\n <\/div>\n <\/div>\n<\/div>\n\n

    4. View the next page of results<\/h3>\n

    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<\/code> and limit<\/code> you defined. In addition to the array, the response also returns the following parameters to help you navigate through the list of results:<\/p>\n\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    link.next.href<\/code><\/td>\nResponse body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Returned if there is more than 1 page of results, based on the limit<\/code> you defined.

    The link leading to the next page of results. This link includes the cursor<\/code> which you can use as a query in your GET request to view the next page of results.<\/td>\n<\/tr>\n
    link.prev.href<\/code><\/td>\nResponse body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Returned if there is more than 1 page of results, based on the cursor<\/code> and limit<\/code> you defined.

    The link leading to the previous page of results. This link includes the cursor<\/code> which you can use as a query in your GET request to view the previous page of results.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    \"This Required for all transactions.
    \"This Required for particular setups.
    \"This Recommended for all transactions, but not required.<\/p>\n

    \n \n
    \n
    \n <\/i>\n
    \n

    Example response - View recurring top-ups (next page)<\/h4>\n <\/div>\n <\/div>\n
    \n \n

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

    \n <\/code-sample>\n<\/div>\n\n <\/div>\n <\/div>\n<\/div>\n\n

    Update a recurring top-up<\/h2>\n

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

    \n

    If you do not specify a parameter, or explicitly set it to null<\/strong>, the value remains the same as what you specified in the POST request<\/a>.<\/p>\n<\/div>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    balanceAccountId<\/code><\/td>\nPath<\/td>\n\"Required\"<\/span><\/td>\nThe unique identifier of the balance account.<\/td>\n<\/tr>\n
    topUpId<\/code><\/td>\nPath<\/td>\n\"Required\"<\/span><\/td>\nThe unique identifier of the recurring top-up you want to update.<\/td>\n<\/tr>\n
    counterparty.transferInstrumentId<\/code><\/td>\nRequest body<\/td>\n\"Required\"<\/span><\/td>\nUse case<\/strong>: Required if you want to update to a new transfer instrument ID.<\/td>\n<\/tr>\n
    description<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Required if you want to change the description.

    Your description for the recurring top-up.

    Format<\/strong>: Maximum length is 140 characters. If you set a longer description, it will be cut off at 140 characters.<\/td>\n<\/tr>\n
    topUpAmount.fixed<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>:
    Required if:
    • You want to update to a new fixed top-up amount.<\/li>
    • You want to change from a target to a fixed amount.<\/li>
    • You want to change from a fixed to a target amount. In this case, set fixed<\/code> to null<\/strong>.<\/li><\/ul>
      The fixed amount with which you want to top up the balance account. Set to null<\/strong> if you want to change from a fixed to a target amount.<\/td>\n<\/tr>\n
    topUpAmount.target<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>:
    Required if:
    • You want to update to a new target top-up amount.<\/li>
    • You want to change from a fixed to a target amount.<\/li>
    • You want to change from a target to a fixed amount. In this case, set target<\/code> to null<\/strong>.<\/li><\/ul>
      The target balance for the balance account that the top-up must achieve. Set to null<\/strong> if you want to change from a target to a fixed amount.<\/td>\n<\/tr>\n
    trigger.schedule<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: 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<\/strong>:
    • weekdays<\/strong>: from Monday to Friday at 07:00 AM<\/li>
    • weekly<\/strong>: on Mondays at 07:00 AM<\/li>
    • monthly<\/strong>: on the 1st of each month at 07:00 AM<\/li>
    • null<\/strong>: continuous monitoring<\/li><\/ul><\/td>\n<\/tr>\n
    trigger.threshold<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: 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<\/code>, if the available balance is below the threshold amount, we trigger a top-up.<\/td>\n<\/tr>\n
    status<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: Required if you want to change the status.

    The status of the recurring top-up.

    Possible values:
    • active<\/strong> (default)<\/li>
    • inactive<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
    referenceForBeneficiary<\/code><\/td>\nRequest body<\/td>\n\"Conditionally<\/span><\/td>\nUse case<\/strong>: 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<\/strong>: