Scheduled internal fund transfers

Automatically transfer funds between balance accounts.

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.

This page explains how to configure sweeps to schedule automatic transfers between balance accounts.

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.

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.

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.

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 the triggerAmount. 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 the targetAmount is transferred to the balance account . The triggerAmount must be higher than the targetAmount.
Pay out a fixed amount
Set a fixed amount by including a sweepAmount. The amount specified in the sweepAmount is transferred to the destination. The triggerAmount must be equal to or higher than the sweepAmount.

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.

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.

To configure sweeps in your Customer Area, your account must have the Manage sweep configurations role.

In the navigation menu, select the merchant account linked to your balance platform.
In Platforms > Accounts & balances > Balance accounts, select a Balance account ID.
In Sweep configuration section, select Add sweep configuration.
Select Payout schedule.
Enter a Description for the schedule. (Optional)
Select Next.

Enter the configuration details in the corresponding fields.

Field	Description
When balance on	Automatically set to the balance account ID.
Is more or equal to	Set a trigger amount. Before paying out the funds, Adyen checks if the available balance is more than or equal to the trigger amount.
Action	Select Push an amount or Maintain a balance.
Push this amount	Select Entire available balance or Custom. Read more on how Adyen calculates the available balance.
Push balance to	Select Balance account.
Balance account Id	Select the ID of the balance account.
When schedule matches	Select the predefined schedules or Custom.
Schedule	If you select a Custom schedule, specify the schedule or a cron expression. Select Submit.
Activate	Immediately after creation

Select Next.
Select Save.

Now, the details of your scheduled transfer are shown in Sweep configuration.

The following example shows how to enter the configuration details.

Your user has two balance accounts, balance account 1 and balance account 2, which they use for different purposes. On balance account 1, they want to maintain a balance of EUR 200. To do this, they want to check on every Wednesday at 9:30 AM if the funds in balance account 1 have exceeded EUR 250 and push this excess to balance account 2.

The following table shows the details you must enter for this case.

Field	Details
When balance on	BA00000000000000000000001
Is more or equal to	EUR 250
Action	Maintain a balance
Maintain a balance of	EUR 200
Push balance to	Balance account
Balance account	BA00000000000000000000002
When schedule matches	Custom
Schedule	Cron Expression > *30 9 * 3 > Submit**
Activate	Immediately after creation

Step 2. Get updates when a transfer results from a sweep

Track the transfer requests that result from sweeps 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.

Scheduled internal fund transfers

How sweeps work

Before you begin

Step 1. Create a sweep

Optional sweep configuration

Optional dynamic transfer statement descriptions

Example — Maintain a balance by transferring funds

Step 2. Get updates when a transfer results from a sweep