--- title: "Create recurring top-ups" description: "Learn how to configure recurring top-ups for your balance accounts." url: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/create-recurring-top-ups" source_url: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/create-recurring-top-ups.md" canonical: "https://docs.adyen.com/issuing/add-manage-funds/top-ups/create-recurring-top-ups" last_modified: "2020-09-11T17:20:00+02:00" language: "en" --- # Create recurring top-ups Learn how to configure recurring top-ups for your balance accounts. [View source](/issuing/add-manage-funds/top-ups/create-recurring-top-ups.md) 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](/development-resources/api-credentials/roles/)** | Make sure that you have the credentials for the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) with the following role:- **BankAPI Advanced Webservice role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhooks:- [Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview) - [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) - [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) | | **[Capabilities](/issuing/verification-overview/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](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus). Note, if you need to enable this capability see request [additional capabilities](/issuing/manage-account-holders#request-capability). | | **Limitations** | This feature does not support on-demand top-ups. | | **Setup steps** | Make sure that your [top-up source](/issuing/add-manage-funds/top-ups#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 | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the balance account. | | `counterparty` | Request body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object containing details about the counterparty that is funding the top-up. For more information, see [Counterparty](#counterparty). | | `description` | Request body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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 | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](#top-up-amount). | | `trigger` | Request body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](#trigger). | | `status` | Request body | | The status of the recurring top-up. **Possible values**:- **active** (default) - **inactive** | | `referenceForBeneficiary` | Request body | | The reference sent to the counterparty (the source of the funds) for the direct debit request. **Format**:- Only alphanumeric characters. - Maximum length is 80 characters. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ### Counterparty In the `counterparty` object, specify the following parameter. | Parameter | Type | Required | Description | | ---------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `transferInstrumentId` | Request body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | **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. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) 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 | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](/development-resources/currency-codes/#minor-units). | | `target` | Request body | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | **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](/development-resources/currency-codes/#minor-units). | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) 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**:- **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 | | `threshold` | Request body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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: **Create recurring top-up** ```bash curl https://balanceplatform-api-beta.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/recurringTopUps \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "counterparty": { "transferInstrumentId": "TI00000000000000000000001" }, "description": "Your description for the recurring top-up", "topUpAmount": { "target": { "value": 100000, "currency": "USD" } }, "trigger": { "schedule": { "type": "weekly" }, "threshold": { "value": 25000, "currency": "USD" } } }' ``` You receive the following response: **Response - create recurring top-up** ```json { "id": "TU0000000000001", "counterparty": { "transferInstrumentId": "TI00000000000000000000001" }, "description": "Your description for the recurring top-up", "topUpAmount": { "target": { "value": 100000, "currency": "USD" } }, "trigger": { "schedule": { "type": "weekly" }, "threshold": { "value": 25000, "currency": "USD" } }, "status": "active" } ``` ## 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. | ## See also ###### [Manage recurring top-ups](/issuing/add-manage-funds/top-ups/manage-recurring-top-ups) [Learn how to view, change, and delete recurring top-ups.](/issuing/add-manage-funds/top-ups/manage-recurring-top-ups) ###### [Top-up webhooks](/issuing/add-manage-funds/top-ups/top-up-webhooks) [Stay updated about changes to the recurring top-ups on your platform.](/issuing/add-manage-funds/top-ups/top-up-webhooks)