Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Pay out to your users

Make scheduled or one-off payouts to your users.

After your user starts receiving funds to their balance account, you can start paying out to their bank account. The bank account must be linked to their legal entity as a transfer instrument and must pass the verification checks.

To pay out funds to your users, you can:

  • Set up automatic scheduled payouts.
  • Make one-off payouts.

Before you begin

Make sure that your user has the sendToTransferInstrument capability.

Scheduled payouts

To set up scheduled payouts, you must configure a sweep on the balance account. A sweep pushes out or pulls in funds to a balance account based on a schedule that you define, amount, and a source or destination. To pay out to your user, you must create a push sweep.

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.transferInstrumentId -white_check_mark- The ID of the transfer instrument to which the payout must be sent. This resource must be linked to the account holder's legal entity.
currency -white_check_mark- The currency of the sweep. This must match one of the currencies of the balances.
description Your description for the transfer. See configure payout 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 paid out to the transfer instrument 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 on 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": {
      "transferInstrumentId": "SE32272223222D5DHXWBB9995"
    },
    "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": {
    "transferInstrumentId": "SE32272223222D5DHXWBB9995"
  },
  "currency": "EUR",
  "description": "Payout every Wednesday at 0930"
}

When a payout is triggered, Adyen informs your server of the status through webhooks.

Configure payout descriptions

You can configure what your users see on their bank statements when they receive payouts. This can help your users identify incoming transfers. To configure a description, either:

Note that if you set a default descriptor and also send a value for description, the value of the description is shown.

You can use placeholder values to dynamically change the description or transfer descriptor. The following values are supported:

  • $balanceAccountId (e.g. BA32272223222B5FL6CTMBJPR)
  • $balanceAccountReference (e.g. BA reference)
  • $balanceAccountDescription (e.g. BA description)
  • $accountHolderId (e.g. AH32272223222B5FL6CQTBJLD)
  • $accountHolderReference (e.g. 23564762354654)
  • $accountHolderDescription (e.g. Platform setup)
  • $transferReference (The reference for the OutgoingTransfer, e.g. 1ZXDSUSTTT5R4A8F)

In the example below, sending the description $accountHolderId and $accountHolderDescription generates a Transfer with the description AH32272223222B5FL6CQTBJLD and Platform setup.

Add description for payout
{
"counterparty": {
    "transferInstrumentId": "SE322KH223222D5FM372M6337"
},
"currency": "EUR",
"description": "$accountHolderId and $accountHolderDescription",
"id": "SWPC4227C223222C5GKQKLJ4P648VF",
"schedule": {
    "cronExpression": "54 15 * * *",
    "type": "cron"
},
"status": "active",
"type": "push"
}

Optional sweep configuration

By default, all the available balance in the balance account is paid out to the transfer instrument at the schedule that you specified. You can change this default behavior by providing additional objects in your 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 to the transfer instrument.

  • Maintain a minimum balance

    You may want keep a minimum balance in your user's balance account, which is useful, for example, in 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 payout amount by including a sweepAmount. The amount specified in the sweepAmount is paid out to the transfer instrument. The triggerAmount must be equal to or higher than the sweepAmount.

Below is an example request showing 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.

For example, 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.

One-off payouts

Some users may also require payouts outside of their automatic scheduled payouts. To trigger a one-off, unscheduled payout, you can use the Transfers API.

To send a payout request, make a POST /transfers request, specifying:

Parameter name Required Description
balanceAccountId -white_check_mark- The balance account from which funds are deducted.
category -white_check_mark- Set to bank.
counterparty.transferInstrumentId -white_check_mark- The ID of the transfer instrument to which the payout must be sent. This resource must be linked to the account holder's legal entity.
priority -white_check_mark- The priority of the bank transfer, which affects the transfer speed and the fees you have to pay. The possible values are regular (recommended), fast, or wire.
description Your description for the transfer.
reference Your reference for the transfer. This is only used within your platform and not sent to the recipient. If you don't provide this in the request, Adyen generates a unique reference.
referenceForBeneficiary Your reference for the transfer. Adyen sends this reference to the recipient.
Request for one-off payout
curl https://balanceplatform-api-test.adyen.com/btl/v3/transfers \
-H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
   "amount":{
      "value":60000,
      "currency":"EUR"
   },
   "balanceAccountId":"BA32272223222B5DFZNBZCX66",
   "category":"bank",
   "counterparty":{
      "transferInstrumentId":"SE32272223222D5DHXWBB9995"
   },
   "priority":"fast",
   "reference":"YOUR_INTERNAL_REFERENCE",
   "referenceForBeneficiary":"YOUR_REFERENCE_SENT_TO_BENEFICIARY",
   "description":"YOUR_DESCRIPTION_FOR_THE_TRANSFER"
}'

If the transfer request is successful, you receive an HTTP 200 OK response containing an id of the transfer request. Adyen informs your server of the status of the transfer through webhooks.

Next steps