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 payouts

Set up scheduled automatic payouts to your user's verified bank account.

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.

Before you begin

Step 1. Create a push sweep

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

  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 transfer instrument ID of the destination of the funds. The transfer instrument must be linked to the account holder's legal entity.
    currency -white_check_mark- 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 country of the bank account and the priority.
    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 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 on every Wednesday at 9:30 AM.

    Create a sweep 
    curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/sweeps \
-H 'x-api-key: YOUR_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. 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 
    {
  "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"
}

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 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 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. Check the character limits based on the bank account country 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 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"
}'

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

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 
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 '{
    "priorities": [
        "fast",
        "regular"
    ],
    "category": "bank"
}'

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

Step 2. 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 will also inform you if the transfer failed.

You can also view the resulting transfer in you Balance Platform Customer Area.

Transfer statement description character limits

The following limits apply to the length and the characters that you can use when setting a transfer statement description based on the country of the counterparty and the priority.

Europe

Country of counterparty Currency Supported priority Transfer description limits
Single Euro Payments Area (SEPA) countries EUR regular, instant, wire Maximum 140 characters.
Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Czech Republic CZK regular Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Denmark DKK regular, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Hungary HUF regular Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Norway NOK regular, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Poland PLN regular, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Sweden SEK regular, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
Switzerland CHF regular, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
United Kingdom GBP regular, fast, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space

North America

Country of counterparty Currency Supported priority Transfer description limits
Canada CAD, USD regular Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space
United States USD regular, fast, wire Allowed characters:
Priority: regular and fast
[a-z][A-Z][0-9]& $ % # @ ~ = + - _ ' " ! ?
Priority:wire [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space

Asia Pacific

Country of counterparty Currency Supported priority Transfer description limits
Australia AUD regular, fast, wire Maximum 140 characters. Allowed characters: [a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space

See also