--- title: "Top up on a schedule" description: "Set up a pull sweep to trigger a direct debit from a verified transfer instrument." url: "https://docs.adyen.com/marketplaces/top-up-balance-account/scheduled-top-ups" source_url: "https://docs.adyen.com/marketplaces/top-up-balance-account/scheduled-top-ups.md" canonical: "https://docs.adyen.com/marketplaces/top-up-balance-account/scheduled-top-ups" last_modified: "2026-05-07T17:20:51+02:00" language: "en" --- # Top up on a schedule Set up a pull sweep to trigger a direct debit from a verified transfer instrument. You can configure settings to automatically trigger top-ups to your users' balance accounts when certain conditions are met. These conditions include: * Timing. For example, a pre-defined, fixed schedule for top-ups. * The amount of funds available on the balance account. For example, a minimum amount that must always remain on the balance account. You can define the conditions relevant for your use cases by setting up [sweeps](#sweeps). When any of these conditions are met, Adyen automatically triggers an incoming transfer that tops up your user's balance account. ## Requirements | Requirement | Description | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Adyen for Platforms | | **[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). | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s): 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](/marketplaces/verification-overview/capabilities)** | Make sure that the user has the following capability:- **receiveFromTransferInstrument** | | **Limitations** | Scheduled top-ups are only supported for account holders with verified bank accounts in the EU, the UK, and the US. The top-ups are processed over corresponding standard debit rails of [Single Euro Payments Area (SEPA)](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en), [Bankers' Automated Clearing Services (BACS)](https://www.bacs.co.uk/pages/home.aspx), and [Automated Clearing House (ACH) Network](https://www.nacha.org/content/ach-network). | | **Setup steps** | Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable scheduled top-ups for your marketplace. | ## Sweeps A sweep is a configuration on your user's balance account that allows you to push or pull funds from your user's verified transfer instrument based on a pre-defined schedule and/or amount. This affects the balance in your user's balance account. When you configure a sweep for a balance account, you must determine the sweep type, the sweep conditions, and the sweep amount: * **Sweep type**: dictates the direction of the funds transfer in relation to your user's balance account. For scheduled top-ups, the direction is set to *pull*, in order to pull funds in to the balance account from a transfer instrument that you specify. * **Sweep conditions**: dictates the conditions that must be met for a sweep to be triggered. For example, you can trigger sweeps according to a fixed schedule, or you can configure a trigger amount based on the account's available balance. By configuring a trigger amount for a pull sweep, you can always maintain a certain minimum balance on your user's balance account * **Sweep amount**: the amount of the funds being transferred. When the conditions for a sweep are met, it triggers a top-up request from a transfer instrument for the specified sweep amount. Adyen sends webhooks to your server when an incoming transfer results from a sweep. ## How it works 1. You determine the conditions and amount for the pull sweep to your user's balance account. 2. You create a pull sweep for your user's balance account using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). 3. Adyen sends a [balancePlatform.balanceAccountSweep.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.created) webhook to your server to inform you of the status of the sweep you created. 4. When the conditions for the sweep are met, Adyen initiates an incoming transfer (top-up) to your balance account for the specified sweep amount. 5. Adyen sends transfer and transaction webhooks to your server to inform you about the status of the incoming transfer (top-up). ## Create a pull sweep 1. To create a sweep, make a POST [/balanceAccounts/{balanceAccountId}/sweeps](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps) request with the ID of the balance account in the path, and the following parameters in the request body. | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [counterparty.transferInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-counterparty-transferInstrumentId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments) ID of the source of the funds. The transfer instrument must be linked to the account holder's [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities). | | [counterparty.merchantAccount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-counterparty-merchantAccount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account ID that will be the source of funds. | | [currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-currency) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency of the sweep. This must match one of the currencies of the balances. | | [schedule.type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-schedule-CronSweepSchedule-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The schedule when the sweep is evaluated. Set this parameter to **balance**. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-schedule-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The direction of sweep. Set this parameter to **pull**. | | [triggerAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-triggerAmount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The threshold amount that triggers the sweep. | | [sweepAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-sweepAmount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The amount that must be pulled in. | | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-description) | | Your description for the resulting transfers. | Here's an example of creating a pull sweep to top up a balance account from a transfer instrument if the balance drops below EUR 5,000. **Create a pull sweep** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/sweeps \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "Top-up if balance drops below 5000", "counterparty": { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "transferInstrumentId" : "SE00000000000000000000001" }, "sweepAmount": { "value": 100000, "currency": "EUR" }, "triggerAmount": { "value": 500000, "currency": "EUR" }, "currency": "EUR", "schedule": { "type": "balance" }, "type": "pull" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule() .type(SweepSchedule.TypeEnum.BALANCE); SweepCounterparty sweepCounterparty2 = new SweepCounterparty() .merchantAccount("YOUR_MERCHANT_ACCOUNT") .transferInstrumentId("SE00000000000000000000001"); Amount amount2 = new Amount() .currency("EUR") .value(500000L); Amount amount3 = new Amount() .currency("EUR") .value(100000L); CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2() .schedule(sweepSchedule2) .description("Top-up if balance drops below 5000") .counterparty(sweepCounterparty2) .triggerAmount(amount2) .currency("EUR") .sweepAmount(amount3) .type(CreateSweepConfigurationV2.TypeEnum.PULL); // Send the request BalanceAccountsApi service = new BalanceAccountsApi(client); SweepConfigurationV2 response = service.createSweep("balanceAccountId", createSweepConfigurationV2, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $sweepSchedule2 = new SweepSchedule(); $sweepSchedule2 ->setType("balance"); $sweepCounterparty2 = new SweepCounterparty(); $sweepCounterparty2 ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setTransferInstrumentId("SE00000000000000000000001"); $amount2 = new Amount(); $amount2 ->setCurrency("EUR") ->setValue(500000); $amount3 = new Amount(); $amount3 ->setCurrency("EUR") ->setValue(100000); $createSweepConfigurationV2 = new CreateSweepConfigurationV2(); $createSweepConfigurationV2 ->setSchedule($sweepSchedule2) ->setDescription("Top-up if balance drops below 5000") ->setCounterparty($sweepCounterparty2) ->setTriggerAmount($amount2) ->setCurrency("EUR") ->setSweepAmount($amount3) ->setType("pull"); // Send the request $service = new BalanceAccountsApi($client); $response = $service->createSweep('balanceAccountId', $createSweepConfigurationV2); ``` #### C\# ```cs // Adyen .net API Library v27.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule { Type = SweepSchedule.TypeEnum.Balance }; SweepCounterparty sweepCounterparty2 = new SweepCounterparty { MerchantAccount = "YOUR_MERCHANT_ACCOUNT", TransferInstrumentId = "SE00000000000000000000001" }; Amount amount2 = new Amount { Currency = "EUR", Value = 500000 }; Amount amount3 = new Amount { Currency = "EUR", Value = 100000 }; CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2 { Schedule = sweepSchedule2, Description = "Top-up if balance drops below 5000", Counterparty = sweepCounterparty2, TriggerAmount = amount2, Currency = "EUR", SweepAmount = amount3, Type = CreateSweepConfigurationV2.TypeEnum.Pull }; // Send the request var service = new BalanceAccountsService(client); var response = service.CreateSweep("balanceAccountId", createSweepConfigurationV2); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const createSweepConfigurationV2 = { description: "Top-up if balance drops below 5000", counterparty: { merchantAccount: "YOUR_MERCHANT_ACCOUNT", transferInstrumentId: "SE00000000000000000000001" }, sweepAmount: { value: 100000, currency: "EUR" }, triggerAmount: { value: 500000, currency: "EUR" }, currency: "EUR", schedule: { type: "balance" }, type: "pull" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` #### Go ```go // Adyen Go API Library v16.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v16/src/common" "github.com/adyen/adyen-go-api-library/v16/src/adyen" "github.com/adyen/adyen-go-api-library/v16/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) sweepSchedule2 := balancePlatform.SweepSchedule{ Type: "balance", } sweepCounterparty2 := balancePlatform.SweepCounterparty{ MerchantAccount: common.PtrString("YOUR_MERCHANT_ACCOUNT"), TransferInstrumentId: common.PtrString("SE00000000000000000000001"), } amount2 := balancePlatform.Amount{ Currency: "EUR", Value: 500000, } amount3 := balancePlatform.Amount{ Currency: "EUR", Value: 100000, } createSweepConfigurationV2 := balancePlatform.CreateSweepConfigurationV2{ Schedule: sweepSchedule2, Description: common.PtrString("Top-up if balance drops below 5000"), Counterparty: sweepCounterparty2, TriggerAmount: &amount2, Currency: "EUR", SweepAmount: &amount3, Type: common.PtrString("pull"), } // Send the request service := client.BalancePlatform() req := service.BalanceAccountsApi.CreateSweepInput("balanceAccountId").CreateSweepConfigurationV2(createSweepConfigurationV2) res, httpRes, err := service.BalanceAccountsApi.CreateSweep(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "description": "Top-up if balance drops below 5000", "counterparty": { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "transferInstrumentId": "SE00000000000000000000001" }, "sweepAmount": { "value": 100000, "currency": "EUR" }, "triggerAmount": { "value": 500000, "currency": "EUR" }, "currency": "EUR", "schedule": { "type": "balance" }, "type": "pull" } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_sweep(request=json_request, balanceAccountId="balanceAccountId") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :description => 'Top-up if balance drops below 5000', :counterparty => { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :transferInstrumentId => 'SE00000000000000000000001' }, :sweepAmount => { :value => 100000, :currency => 'EUR' }, :triggerAmount => { :value => 500000, :currency => 'EUR' }, :currency => 'EUR', :schedule => { :type => 'balance' }, :type => 'pull' } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_sweep(request_body, 'balanceAccountId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const sweepSchedule2: Types.balancePlatform.SweepSchedule = { type: Types.balancePlatform.SweepSchedule.TypeEnum.Balance }; const sweepCounterparty2: Types.balancePlatform.SweepCounterparty = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", transferInstrumentId: "SE00000000000000000000001" }; const amount2: Types.balancePlatform.Amount = { currency: "EUR", value: 500000 }; const amount3: Types.balancePlatform.Amount = { currency: "EUR", value: 100000 }; const createSweepConfigurationV2: Types.balancePlatform.CreateSweepConfigurationV2 = { schedule: sweepSchedule2, description: "Top-up if balance drops below 5000", counterparty: sweepCounterparty2, triggerAmount: amount2, currency: "EUR", sweepAmount: amount3, type: Types.balancePlatform.CreateSweepConfigurationV2.TypeEnum.Pull }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` 2. In the response, note the sweep's unique identifier. By default, sweeps are created with an **active** status. You can change it by sending an updated status in a PATCH [/balanceAccounts/{balanceAccountId}/sweeps/{sweepId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balanceAccounts/\(balanceAccountId\)/sweeps/\(sweepId\)) request. **Response - sweep created** ```json { "id": "SWPC00000000000000000000000001", "description": "Top-up if balance drops below 5000", "counterparty": { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "transferInstrumentId" : "SE00000000000000000000001" }, "sweepAmount": { "value": 100000, "currency": "EUR" }, "triggerAmount": { "value": 500000, "currency": "EUR" }, "currency": "EUR", "schedule": { "type": "balance" }, "type": "pull", "status": "active" } ``` 3. Listen to the [balancePlatform.balanceAccountSweep.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.created) webhook, which Adyen sends to your server when you successfully create a sweep. ## Get updates when a sweep triggers a transfer request You can track incoming transfer requests that result from sweeps through [top-up webhooks](/marketplaces/top-up-balance-account/top-up-webhooks). These webhooks provide the status of the incoming transfer request, from the time when Adyen received the request and the transfer was authorised, up to when the funds were added to the balance account. The webhooks will also inform you if the transfer failed. You can also [view the resulting transfer in your Customer Area](/marketplaces/view-transfers-details). ## See also * [View transfer details in your Customer Area](/marketplaces/view-transfers-details) * [Top-up webhooks](/marketplaces/top-up-balance-account/top-up-webhooks)