--- title: "Create recurring top-ups" description: "Learn how to configure recurring top-ups for your balance accounts." url: "https://docs.adyen.com/payouts/payout-service/top-up-balance-accounts/create-recurring-top-ups" source_url: "https://docs.adyen.com/payouts/payout-service/top-up-balance-accounts/create-recurring-top-ups.md" canonical: "https://docs.adyen.com/payouts/payout-service/top-up-balance-accounts/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](/payouts/payout-service/top-up-balance-accounts/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 [enterprise payouts](/payouts/payout-service) integration. | | **[API credential roles](/development-resources/api-credentials/roles/)** | To configure top-up schedules using the [API](#create-a-recurring-top-up), 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** | | **[Customer Area roles](/account/user-roles)** | To configure top-up schedules using the [Customer Area](#create-a-recurring-top-up), make sure that you have the following roles:- **Balance platform base role** - **Configure scheduled payouts** | | **[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** | Make sure that the account holder has 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 a capability](/issuing/manage-account-holders#request-capability). | | **Limitations** | * This feature does not support on-demand top-ups. * Top-ups are supported only in EUR and USD. | | **Setup steps** | - Make sure that your [top-up source](/payouts/payout-service/top-up-balance-accounts#top-up-source) has enough balance to fund the top-up. - If you are configuring top-ups using the API, you must first [accept the Terms of Service](/payouts/payout-service/top-up-balance-accounts/sign-terms-of-service). If you are using the [Customer Area](#create-a-recurring-top-up), this is handled during the setup wizard. | ## Create a recurring top-up You can create a recurring top-up using the API or your Customer Area. ### Tab: API 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" } ``` ** ### Optional - Dynamic transfer statement description When creating or updating a recurring top-up using the API, you can use placeholders to set dynamic descriptions. Setting a description in the `description` or `referenceForBeneficiary` fields overrides any default description settings. To dynamically change the top-up descriptions, include any number of placeholder values in the `description` and/or `referenceForBeneficiary` fields. The following placeholder values are available: | Placeholder | Description | Example value in the statement | | ------------------------------ | ---------------------------------------------------------------------- | ------------------------------ | | **$balanceAccountId** | The ID of the balance account. | BA32272223222B5FL6CTMBJPR | | **$balanceAccountReference** | Your reference for the balance account. | BA reference | | **$balanceAccountDescription** | Your description for the balance account. | BA description | | **$accountHolderId** | The ID of the account holder. | AH32272223222B5FL6CQTBJLD | | **$accountHolderReference** | Your reference of the account holder. | 23564762354654 | | **$accountHolderDescription** | Your description for the account holder. | Dean's Donuts | | **$transferReference** | The 30-character Adyen-generated reference for the resulting transfer. | SWPE12345678901234567890123456 | | **$shortTransferReference** | The 15-character Adyen-generated reference for the resulting transfer. | S12345678901234 | For example, setting the `description` to **$accountHolderId and $accountHolderDescription** when creating a recurring top-up generates a transfer request with the description **AH32272223222B5FL6CQTBJLD and Dean's Donuts**. **Use placeholders when creating a top-up** ```json { "counterparty": { "transferInstrumentId": "TI00000000000000000000001" }, "currency": "EUR", "description": "Top-up for $accountHolderDescription (Ref: $shortTransferReference)", "topUpAmount": { "fixedAmount": { "value": 5000, "currency": "EUR" } }, "trigger": { "threshold": { "value": 1000, "currency": "EUR" } }, "status": "active" } ``` ### Tab: Customer Area To configure a recurring top-up: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and switch to your company account. 2. Go to **Accounts & balances** > **Balance accounts** and select the relevant balance account. 3. Select **Move funds** > **Recurring top-up**. 4. In the **Recurring top-up** modal, select the balance account you want to top up, then select your counterparty bank account under **Transfer instruments**. 5. Customize your top-up configuration: * **When balance is less than or equal to**: Enter the threshold balance. When the available balance drops to or below this amount, a top-up is triggered. * **Action**: Select how to determine the top-up amount. Select **Pull an amount of** to add a fixed amount, or **Maintain a balance of** to top up to a target balance. * **Pull an amount of** or **Maintain a balance of**: Enter the fixed amount to add, or the target balance to reach, depending on the action you selected. * **When schedule matches**: Select how often to check the balance against the threshold. To trigger based on your balance events rather than a specific time, select **Continuous monitoring**. * **Status**: Select when the schedule takes effect, for example **Immediately after creation** or **Disabled after creation**. 6. Optional: Add a unique reference, description, or reference for the beneficiary for this top-up schedule. 7. Review your settings and open the terms of service to read the direct debit agreement. 8. Select the checkbox to accept the terms of service, and select **Submit**. ## Track your top-ups When a top-up is triggered, a transfer record is automatically created. You can track your top-ups in three places: * **Transfer overview**: Go to **Transactions** > **Transfers** to see the real-time status of the fund movement. To find top-up transfers, click the gear icon to add the **Type** and **Category** columns to your view, then filter for: * **Type**: Bank direct debit * **Category**: Top-up * **Balance account details**: Go to **Finance** > **Balance accounts**, select the relevant balance account, and see **Scheduled transfers**. Select a scheduled top-up to see its configuration details and execution history. * **Reports**: Top-up transactions are logged in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report). You can identify these transactions using the following field mappings: * **Tx Category**: `topUp` * **Tx Type**: `bankDirectDebit` ### Processing and cut-off times If you set a time-based schedule (such as weekly or monthly), the trigger timestamp defaults to 7:00 AM in the timezone of your account. Settle times depend on how this trigger time interacts with currency-specific cut-offs: * **USD (T+2 settlement)**: Because the automatic 7:00 AM trigger occurs after the 01:45 ET cut-off, funds settle on T+2 (after 08:30 ET). * **EUR (next business day settlement)**: Because the automatic 7:00 AM trigger occurs before the 14:00 CET cut-off, funds settle on the next business day. ## Error messages and failure reasons When you create top-up schedules using the API, if the request fails, the reason for the failure is provided in the API response. The following table shows how to identify and troubleshoot some of the most common errors that can occur during top-up creation. | Status | Error code `errorCode` | Error summary `title` | Reason `detail` | | ------ | ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `29_001` | The request is missing required fields or contains invalid data. | `trigger.threshold.currency`: missing or invalid currency code. | | 400 | `29_001` | The request is missing required fields or contains invalid data. | Currencies must match threshold currency.- `topUpAmount.fixed.currency` - `topUpAmount.target.currency` | | 400 | `29_001` | The request is missing required fields or contains invalid data. | `description`: invalid placeholders or invalid format. | | 404 | `1082_105` | Recurring top-up not found. | Top-up ID does not exist. (Applies to `GET`, `PATCH`, `DELETE` requests). | | 422 | `30_013` | Balance account not found. | Could not find balance account with ID `{id}`. | | 422 | `1082_101` | Account top-up currency mismatch. | Currency of the top-up does not match the balance account. | | 422 | `1082_102` | Invalid BAP configuration provided. | BAP property `DirectDebitTopUp` is not active for this balance account. | | 422 | `1082_103` | Invalid recurring top-up request. | Generic invalid request rejected by banksweep. | | 422 | `1082_104` | Account is missing required capabilities. | Missing `receiveFromTransferInstrument` on the account holder. | | 422 | `1082_107` | Failed to resolve payment instrument. | Payment instrument could not be resolved. | | 422 | `1082_108` | Failed to resolve transfer instrument. | Invalid transfer instrument with id `{id}`. | | 422 | `1082_112` | No valid routes found. | No routes are available for the provided configuration. | | 422 | `1082_113` | No PPA route assigned. | No PPA route found. | | 422 | `1082_114` | Terms of service not signed. | A terms of service needs to be signed before having a recurring top-up configured. | | 422 | `1082_115` | Direct debit amount threshold exceeded. | Top-up amount exceeds the configured maximum threshold for direct debit top-ups on balance account `{id}`. | | 422 | `1011_001` | An account has an invalid status. | BalanceAccountHolder `{id}` has invalid account status `inactive`. | | 422 | `1011_003` | Invalid counterparty provided. | Validation failed for one of the following reasons:- Cannot configure a sweep to itself. - Bank account id is invalid. - Merchant account not found. - Legal entity does not have access to transfer instrument. | | 422 | `1011_013` | A sweep with this configuration already exists. | A (`{direction}`) sweep with currency (`{cur}`), counterparty (`{cp}`) and schedule (`{sched}`) already exists: (`{id}`). | ## See also ###### [Manage recurring top-ups](/payouts/payout-service/top-up-balance-accounts/manage-recurring-top-ups) [Learn how to view, change, and delete recurring top-ups.](/payouts/payout-service/top-up-balance-accounts/manage-recurring-top-ups) ###### [Top-up webhooks](/payouts/payout-service/top-up-balance-accounts/top-up-webhooks) [Stay updated about changes to the recurring top-ups on your platform.](/payouts/payout-service/top-up-balance-accounts/top-up-webhooks)