Marketpay icon

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. 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:

Step 1. Create a sweep

Configure sweeps by making a POST /balanceAccounts/{balanceAccountId}/sweeps request or using your Balance Platform Customer Area. In this example, we will use a push sweep to push funds out of a balance account.

  1. 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 -white_check_mark- The balance account ID of the destination of the funds.
currency -white_check_mark- 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 -white_check_mark- The schedule when the sweep is evaluated. Set this parameter to cron.
schedule.cronExpression -white_check_mark- 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.

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 Balance Platform Customer Area.