Automate payouts to your user's verified bank accounts by configuring sweeps. A sweep automatically pushes out or pulls in funds from a balance account based on a pre-defined schedule, amount, and source or destination.
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 the funds: push to push funds out of the balance account to a destination that you specify, or pull to pull funds in to the balance account from a source that you specify.
You can also set sweep conditions such as:
- Transfer the entire available amount or a fixed amount.
- Maintain an amount on the balance account.
- Set an amount that triggers the sweep.
When the conditions for the sweep are met, it triggers a transfer request. Adyen sends webhooks to your server when a transfer request results from a sweep.
For scheduled payouts, you will configure a push sweep to send funds from your user's balance account to their transfer instrument.
How Adyen calculates the available payout amount
Before paying out funds to your users, Adyen verifies their available balance. The available balance refers to the amount of money on the balance account that the user can spend. Verifying the available balance protects you as a marketplace from any potential obligations that may arise due to users holding a negative balance.
To determine the available balance, Adyen considers an existing balance and all debits and credits that are expected to occur in the future, also called future balance changes.
-
Existing balance – The initial balance as of the day of calculation, including all amounts with a value date until the day of calculation.
-
Future balance changes – The total of all future debits and credits amounts that have a value date in the future and a booking date until the day of calculation.
The expected future debits and credits are only taken into account if their total results in a negative amount. In such a case, Adyen calculates the available balance as the existing balance minus future balance changes.
If the future balance changes result in a zero or positive amount, Adyen ignores this amount when calculating the available balance.
Below are some examples of how Adyen calculates the available balance of the balance account.
Example 1: Balance account has negative future balance changes
- At the current time T, the existing balance of the balance account is USD 100.
- The total of the debits and credits scheduled for T+1 (USD -50) and T+2 (USD +30) is USD -20.
- Since the future balance changes result in a negative amount, Adyen considers this amount for calculating the available balance.
- The available balance for the balance sweep at T is the existing balance minus future balance changes, or USD 80.
Example 2: Balance account has zero future balance changes
- At the current time T, the existing balance of the balance account is USD 100.
- The total of the debits and credits scheduled for T+1 (USD -15) and T+2 (USD +15) is USD 0.
- Since the future balance changes result in a zero amount, Adyen ignores this amount when calculating the available balance.
- The available balance for the balance sweep at T is the existing balance of USD 100.
Example 3: Balance account has positive future balance changes
- At the current time T, the existing balance of the balance account is 100 USD.
- The total of the debits and credits scheduled for T+1 (USD -50) and T+2 (USD +80) is USD 30.
- Since the future balance changes result in a positive amount, Adyen ignores this amount when calculating the available balance.
- The available balance for the balance sweep at T is the existing balance of USD 100.
Before you begin
- Ensure that the user is allowed to use the sendToTransferInstrument capability. From LEM API v3, this capability is verified at the level of the transfer instrument, such as a bank account. This means that transfers are possible to a verified transfer instrument independently of the verification status of other transfer instruments that the legal entity has.
- Ensure that your server can receive and accept webhooks.
- Contact Support Team if you want to configure a default transfer description for your platform.
Get transfer routes
Prior to creating a push sweep, we recommend that you calculate the available transfer routes. This will enable you to design a configuration that optimally aligns with your use case. Furthermore, it minimizes the risk of transfer failures by proactively identifying supported routes and highlighting any necessary parameters.
Step 1. Create a push sweep
To set up scheduled payouts, create push sweeps by making a POST /balanceAccounts/{balanceAccountId}/sweeps request or use your Customer Area.
- 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 |  |
The transfer instrument ID of the destination of the funds. The transfer instrument must be linked to the account holder's legal entity. |
| currency | |
The currency of the sweep. |
| description | Your description for the resulting transfers, which is used by most recipient banks as the transfer description. You can set placeholders to generate dynamic transfer descriptions. Check the character limits based on the country of the bank account and the priority. | |
| schedule.type | |
The schedule when the sweep is evaluated. Set this parameter to cron. |
| schedule.cronExpression | |
The cron expression for the schedule when the sweep is evaluated, using the time zone of the balance account. |
| type | The direction of the sweep. Set this parameter to push. | |
| category | The type of transfer that results from the sweep. Required when setting priorities. |
|
| priorities | The list of priorities for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Set category to bank. For details, see optional priorities setup. |
By default, the full available balance in the balance account is paid out to the destination according to the schedule that you specified. To change the default behavior, you can include an optional configuration.
Here's an example of creating a sweep to pay out the full available balance to a transfer instrument every Wednesday at 9:30 AM.
The response returns the sweep with its unique identifier, along with the default values for the optional configuration. 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.
Optional sweep configuration
By default, all the available balance in the balance account is paid out at the schedule that you specified. You can change this default behavior by providing additional objects in your API request.
-
Set a trigger amount
To set a threshold amount that triggers the payout , include a triggerAmount. When the sweep is evaluated at the schedule you specified, Adyen also checks if the available balance is more than or equal to thetriggerAmount. Only then will all the funds be paid out . -
Maintain a minimum balance
You may want keep a minimum balance in the user's balance account, for example, to maintain balances for day-to-day operational purposes. To set a minimum balance, include a targetAmount. The amount in excess of thetargetAmountis paid out to the transfer instrument . The triggerAmount must be higher than thetargetAmount. -
Pay out a fixed amount
Set a fixed amount by including a sweepAmount. The amount specified in thesweepAmountis paid out to the destination. The triggerAmount must be equal to or higher than thesweepAmount.
The following example request shows how you can update the previous sweep to only trigger a payout when the amount in the balance account exceeds EUR 250 and to keep a minimum balance of EUR 200.
If the user has EUR 620 on their balance account, EUR 420 will be paid out to them. If they have EUR 230 on their balance account the week after, their funds will not be paid out.
The response returns the updated sweep resource. Adyen also sends a corresponding balancePlatform.balanceAccountSweep.updated webhook to your server.
Optional dynamic transfer statement descriptions
When creating a sweep using the API, you can use placeholders to set dynamic descriptions. Check the character limits based on the bank account country and priority.
Setting a description overrides default descriptions for your platform.
To dynamically change the transfer descriptions, set any of the following placeholders in the description field:
| 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 Adyen-generated reference for the resulting transfer. | 1ZXDSUSTTT5R4A8F |
For example, setting the description to $accountHolderId and $accountHolderDescription when creating a sweep generates a transfer request with the description AH32272223222B5FL6CQTBJLD and Dean's Donuts.
Optional priorities setup
When you create or update sweeps for scheduled payouts, you are advised to specify the priority of the transfer. For example, if you want to try faster transfer options first. The specified priority or a list of priorities affect the speed at which the payout is sent and the fees that you have to pay. When providing multiple priorities, Adyen tries to pay out using the priority listed first, and if that is not possible, it moves on to the next option in the order of provided priorities.
If the priority is not specified, the wire priority will be used in most cases, so we recommend to set the priority if you'd like to send a regular, fast or instant transfer.
Some transfer routes have an amount limit. The sweep will be executed using the first priority that leads to a valid route given the sweep amount. All supplied priorities must lead to a valid route at the time of configuration.
When setting priorities, you must also specify the category bank.
The response returns the updated sweep resource. Adyen also sends a corresponding balancePlatform.balanceAccountSweep.updated webhook to your server.
Step 2. Get updates when a sweep triggers a transfer request
Track the transfer requests that result from sweeps through webhooks that Adyen sends to your server. The webhooks provide the status of the request, from the time when Adyen received the request and the transfer was authorised, up to when the transfer was booked and deducted from the balance account. The webhooks will also inform you if the transfer failed.
You can also view the resulting transfer in your Balance Platform Customer Area.
View sweep details
After you create a sweep, you can view the details of the resulting scheduled payout in your Balance Platform Customer Area. These details include:
- Payout amount
- Source and destination of the payout
- Completed and upcoming scheduled payouts
You can view the details of all payout schedules and internal transfer schedules in the Balance account details page, under Scheduled transfers. To do this your account must have one of the following roles:
- Balance platform base role
- Balance platform admin role
To view details:
- In Accounts & balances > Balance accounts, select a Balance account ID.
- In Balance account details, under Scheduled transfers, select a scheduled payout.
- Select View details.
Transfer statement description character limits
The following limits apply to the length and the characters that you can use when setting a transfer statement description based on the country of the counterparty and the priority.
Europe
| Country of counterparty | Currency | Supported priority | Transfer description limits | |
|---|---|---|---|---|
| Single Euro Payments Area (SEPA) countries | EUR | regular, instant, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Czech Republic | CZK | regular | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Denmark | DKK | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Hungary | HUF | regular | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Norway | NOK | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Poland | PLN | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Sweden | SEK | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Switzerland | CHF | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| United Kingdom | GBP | regular, fast, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
North America
| Country of counterparty | Currency | Supported priority | Transfer description limits | |
|---|---|---|---|---|
| Canada | CAD, USD | regular | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| United States | USD | regular, fast, wire | Allowed characters: Priority: regular and fast [a-z][A-Z][0-9]& $ % # @ ~ = + - _ ' " ! ? Priority:wire [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
Asia Pacific
| Country of counterparty | Currency | Supported priority | Transfer description limits | |
|---|---|---|---|---|
| Australia | AUD | regular, fast, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Hong Kong | HKD, USD | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| New Zealand | NZD | regular, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |
|
| Singapore | SGD | regular, fast, wire | Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space |