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.
Before you begin
- Ensure that the user is allowed to use the sendToTransferInstrument capability.
- 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 Balance Platform 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.
Setcategory
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 on every Wednesday at 9:30 AM.
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.
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 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 thetargetAmount
is 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 thesweepAmount
is 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 can 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's not possible, it moves on to the next option in the order of provided priorities.
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 you Balance Platform Customer Area.
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 |