Pay out on a schedule

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.

How Adyen calculates the available payout amount

Before paying out funds to your users, Adyen verifies their available balance. The available balance refers to the amount of money on the balance account that the user can spend. Verifying the available balance protects you as a platform from any potential obligations that may arise due to users holding a negative balance.

To determine the available balance, Adyen considers an existing balance and all debits and credits that are expected to occur in the future, also called future balance changes.

• Existing balance – The initial balance as of the day of calculation, including all amounts with a value date until the day of calculation.

• Future balance changes – The total of all future debits and credits amounts that have a value date in the future and a booking date until the day of calculation.

The expected future debits and credits are only taken into account if their total results in a negative amount. In such a case, Adyen calculates the available balance as the existing balance minus future balance changes.

If the future balance changes result in a zero or positive amount, Adyen ignores this amount when calculating the available balance.

Below are some examples of how Adyen calculates the available balance of the balance account.

Requirements

• Make sure that your server can receive and accept webhooks.
• Contact Support Team if you want to configure a default transfer description for your platform.
• Make sure that the user is allowed to use the sendToTransferInstrument capability. From LEM API v3, this capability is verified at the level of the transfer instrument, such as a bank account. This means that transfers are possible to a verified transfer instrument independently of the verification status of other transfer instruments that the legal entity has.

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

Create a push sweep

To set up scheduled payouts, create push sweeps in your Customer Area by using your Customer Area, or by making a POST /balanceAccounts/{balanceAccountId}/sweeps request.

Customer AreaAPICustomer AreaAPI

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

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 location of the bank account and the priority of the transfer.
referenceForBeneficiary		Second description field, which is available in most locations. Check the character limits based on the location of the bank account and the priority of the transfer. 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		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. Set category 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 every Wednesday at 9:30 AM.

Create a sweep

curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

Expand view

Copy link to code block

Copy code

Copy code

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/sweeps \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "counterparty": {
      "transferInstrumentId": "SE00000000000000000000001"
    },
    "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. 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.

Response - sweep created

Expand view

Copy link to code block

Copy code

Copy code

{
    "id": "SWPC00000000000000000000000001",
    "schedule": {
        "type": "cron",
        "cronExpression": "30 9 * * 3"
    },
    "status": "active",
    "targetAmount": {
        "currency": "EUR",
        "value": 0
    },
    "triggerAmount": {
        "currency": "EUR",
        "value": 0
    },
    "type": "push",
    "counterparty": {
        "transferInstrumentId": "SE00000000000000000000001"
    },
    "currency": "EUR",
    "description": "Payout every Wednesday at 0930"
}

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 available balance is more than or equal to the triggerAmount. 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 the targetAmount is paid out to the transfer instrument . 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 paid out 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.

Update sweep to maintain a minimum balance

Expand view

Copy link to code block

Copy code

Copy code

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps/SWPC4227C224555B5FTD2NT2JV4WN5 \
-H 'x-api-key: ADYEN_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.

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/region 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 and/or remittanceForBeneficiary fields:

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 30-character Adyen-generated reference for the resulting transfer.	SWPE12345678901234567890123456
$shortTransferReference	The 15-character Adyen-generated reference for the resulting transfer.	S12345678901234

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

curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

Expand view

Copy link to code block

Copy code

Copy code

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps \
-H 'x-api-key: ADYEN_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"
}'

To automate the reconciliation of payouts, we recommend that you use the $shortTransferReference. This appears in:

• Customer Area Transfer Details page under Description
• Transfer Confirmation Letter under Description
• Balance Platform Payout Report under Description
• Beneficiary bank statements as remittance information. This is provided by all banks, but the location in the bank statement can differ.

Optional priorities setup

When you create or update sweeps for scheduled payouts, you are advised to 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 is not possible, it moves on to the next option in the order of provided priorities.

If the priority is not specified, the default priority will be used, which differs per region. We recommend to set the priority or list of priorities of your choice.

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.

Update sweep to set up transfer priorities order

curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)curlJavaPHPC#NodeJS (JavaScript)GoPythonRubyNodeJS (TypeScript)

Expand view

Copy link to code block

Copy code

Copy code

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA3227C223222B5B9SCR82TMV/sweeps/SWPC4227C224555B5FTD2NT2JV4WN5 \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X PATCH \
-d '{
    "priorities": [
        "fast",
        "regular"
    ],
    "category": "bank"
}'

The response returns the updated sweep resource. Adyen also sends a corresponding balancePlatform.balanceAccountSweep.updated webhook to your server.

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 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 payout in your Customer Area. These details include:

• Payout amount
• Source and destination of the payout
• Completed and upcoming scheduled payouts

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:

1. In Accounts & balances > Balance accounts, select a Balance account ID.
2. In Balance account details, under Scheduled transfers, select a scheduled payout.
3. Select View details.

Transfer statement description character limits

A statement description is the text that your users see on their bank statements when they receive payouts, helping them identify the transaction. The limit for the statement description depends on the clearing system regulations.

Adyen offers two dedicated fields that are sent to the beneficiary: description and referenceForBeneficiary. Depending on the location, currency, and priority combination, different character limits apply to these two fields. See the table below to understand the description behavior in each location. The data in the table is based on extensive testing, but some beneficiary banks may choose not to show the full description to their customers.

To configure a default description for all payouts, contact our Support Team. You can still override the default description when you initiate a scheduled or on-demand payout in the Customer Area or API.

¹ In these regions, the description and referenceForBeneficiary characters are combined and shown in a single field on the bank application or statement. The description appears first. If the character limit is reached, the referenceForBeneficiary is not included.

See also