While the funds in users' balance accounts usually come from processing payments, you can also let them automatically top up their accounts. By configuring pull sweeps, you can automate pulling in funds from their verified bank account (transfer instrument) based on a pre-defined amount and source.
Topping up funds in balance accounts is useful when:
- Covering for possible negative balances, caused by refunds and chargebacks.
- Debiting costs from bank accounts when users' balance account has insufficient funds.
Topping up funds is supported for account holders with bank accounts in the EU, the UK, and the US. The direct debit transactions are processed over corresponding standard debit rails of Single Euro Payments Area (SEPA), Bankers' Automated Clearing Services (BACS), and Automated Clearing House (ACH) network.
How sweeps work
Sweeps are configured on a balance account. The configuration includes the type of the sweep and conditions, such as the schedule when the sweep is evaluated, or a trigger amount. The type dictates the direction of funds. For automated top-ups, the direction is set to pull to pull funds in to the balance account from a transfer instrument that you specify.
You can also set sweep conditions, such as:
- Maintain a certain amount on the balance account.
- Set an amount that triggers the sweep.
When the conditions for the pull sweep are met, it triggers a direct debit request from a transfer instrument. Adyen sends webhooks to your server when an incoming transfer results from a sweep.
Before you begin
- Contact our Support Team to enable automated top-ups for your platform.
- Ensure that the user is allowed to use the receiveFromTransferInstrument and receiveFromPlatformPayments capabilities.
- Ensure that your server can receive and accept webhooks.
Step 1. Create a pull sweep
To set up automated top-ups, create a pull sweep by making a POST /balanceAccounts/{balanceAccountId}/sweeps request.
-
To create a sweep, make a 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 
The transfer instrument ID of the source of the funds. The transfer instrument must be linked to the account holder's legal entity. counterparty.merchantAccount The merchant account ID that will be the source of funds. currency The currency of the sweep. This must match one of the currencies of the balances. schedule.type The schedule when the sweep is evaluated. Set this parameter to balance. type The direction of sweep. Set this parameter to pull. triggerAmount The threshold amount that triggers the sweep. sweepAmount The amount that must be pulled in. 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.
The response returns the sweep with its unique identifier. When you successfully create a sweep, Adyen also sends a corresponding balancePlatform.balanceAccountSweep.created webhook to your server.
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} request.
Step 2. Get updates when a sweep triggers a transfer request
You can track incoming transfer requests that result from sweeps through 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.