Schedule top-ups to your users' balance accounts by configuring pull sweeps. A pull sweep pulls in funds from your user's registered transfer instrument (verified bank account) to their balance account based on a pre-defined amount and schedule.
Scheduled top-ups are 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), 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 scheduled 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 top-up 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 scheduled 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.
Create a pull sweep
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.
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.