Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
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 ID of the destination of the funds.
    currency -white_check_mark- The currency of the sweep.
    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 pay out the full available balance to another balance account every Wednesday at 0930.

    Create a sweep 
    curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps \
-H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "counterparty": {
      "balanceAccountId": "BA00100000000000000000001"
    },
    "currency": "EUR",
    "schedule": {
      "cronExpression": "30 9 * * 3",
      "type": "cron"
    },
    "type": "push"
}'

    The response returns the sweep with its unique identifier, along with the default values for the optional configuration. By default, sweeps are created with an active status. When you successfully create a sweep, Adyen also sends a corresponding balancePlatform.balanceAccountSweep.created webhook to your server.

    Response - sweep created 
    {
  "id": "SWPC4227C223222B5FTD2NT2JV4WN5",
  "schedule": {
    "type": "cron",
    "cronExpression": "30 9 * * 3"
  },
  "status": "active",
  "targetAmount": {
    "currency": "EUR",
    "value": 0
  },
  "triggerAmount": {
    "currency": "EUR",
    "value": 0
  },
  "type": "push",
  "counterparty": {
    "balanceAccountId": "BA00100000000000000000001"
  },
  "currency": "EUR",
  "description": "Internal funds transfer every Wednesday at 0930"
}

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 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 250 EUR and to keep a minimum balance of 200 EUR.

If the user has 620 EUR on their balance account, 420 EUR will be paid out to them. If they have 230 EUR on their balance account the week after, their funds will not be paid out.

Update sweep to maintain a minimum balance 
curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps/SWPC4227C224555B5FTD2NT2JV4WN5 \
-H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X PATCH \
-d '{
  "triggerAmount": {
    "value": 25000,
    "currency": "EUR"
  },
  "targetAmount": {
    "value": 20000,
    "currency": "EUR"
  }
}'

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.

Use placeholders when creating a sweep 
curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps \
-H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
  "counterparty": {
    "transferInstrumentId": "SE322KH223222D5FM372M6337"
  },
  "currency": "EUR",
  "description": "$accountHolderId and $accountHolderDescription",
  "schedule": {
    "cronExpression": "54 15 * * *",
    "type": "cron"
  },
  "status": "active",
  "type": "push"
}'

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.