Automate internal fund transfers by configuring sweeps, in the same manner as setting up scheduled payouts. A sweep automatically pushes out or pulls in funds from a balance account based on a pre-defined schedule, amount, and source or destination. For more information, refer to How sweeps work.
Configure a push or pull sweep depending on the scenario. For example, to maintain balances, you can set up a pull sweep to pull funds from another balance account when the balance goes below a certain amount. If you want to automate sending bonuses from your liable balance account, you can push funds from the liable balance account to your user's balance account.
This page explains how to configure sweeps to schedule automatic transfers between balance accounts.
Before you begin
- Check the capabilities of the source and destination account holders. You can move funds between the balance accounts of the same account holder but if the balance accounts are not under the same account holder, the account holders must be allowed to use the corresponding capability.
- sendToBalanceAccount: The account holder that owns the source balance account must be allowed to use this capability.
- receiveFromBalanceAccount: The account holder that owns the destination balance account must be allowed to use this capability.
- Make sure that your server can receive and accept webhooks.
- Contact our Support Team:
- To enable transfers for the source balance account.
- If you want to configure a default transfer description for your platform.
Step 1. Create a sweep
Configure sweeps by making a POST /balanceAccounts/{balanceAccountId}/sweeps request or using your Customer Area. In this example, we will use a push sweep to push funds out of a balance account.
- 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 balance account ID of the destination of the funds. | |
currency | The currency of the sweep. This must match one of the currencies of the balances. | |
description | Your description for the sweep and the resulting transfer request. You can set placeholders to generate dynamic transfer descriptions. | |
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 | Default value is push. |
By default, the full available balance in the balance account is transferred 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 transfer the full available balance to another balance account 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 transferred 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 transfer, 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 transferred . -
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 transferred to the balance account . 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 transferred 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.
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.
Step 2. Get updates when a transfer results from a sweep
Track the transfer requests through webhooks that Adyen sends to your server. The webhooks provide the status of the request. The webhooks will also inform you if the transfer failed.
You can also view the resulting transfer in your Customer Area.
View sweep details
After you create a sweep, you can view the details of the resulting scheduled transfer in your Balance Platform Customer Area. These details include:
- Transfer amount
- Source and destination of the transfer
- Completed and upcoming scheduled transfers
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 transfer.
- Select View details.