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. 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 | Make sure that you have the credentials for the Configuration API. |
| Webhooks | Subscribe to the following webhook(s): Subscribe to the following webhooks: |
| Capabilities | Make sure that the user has the following capability:
|
| 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), Bankers' Automated Clearing Services (BACS), and Automated Clearing House (ACH) Network. |
| Setup steps | Contact our Support Team 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
- You determine the conditions and amount for the pull sweep to your user's balance account.
- You create a pull sweep for your user's balance account using the Configuration API.
- Adyen sends a balancePlatform.balanceAccountSweep.created webhook to your server to inform you of the status of the sweep you created.
- When the conditions for the sweep are met, Adyen initiates an incoming transfer (top-up) to your balance account for the specified sweep amount.
- 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
-
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.
-
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} request.
-
Listen to the 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. 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.