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

Before you can pay out to your user, you must:

  • Reach out to your Adyen contact to:
    • Add an additional role for your API credential. You'll need this for the Transfers API.
    • Enable transfers for the source balance account.
  • Make sure that the account holder has a 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 defined schedule, 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.
schedule.type -white_check_mark- The schedule when the sweep is evaluated.

Possible values:
- daily: Daily at 07:00 AM CET.
- weekly: Every Monday at 07:00 AM CET.
- monthly: Every first of the month at 07:00 AM CET.
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 a weekly basis.

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": {
    "type": "weekly"
  },
  "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": "SWPC4227C224555B5FTD2NT2JV4WN5",
  "schedule": {
    "type": "weekly"
  },
  "status": "active",
  "targetAmount": {
    "currency": "EUR",
    "value": 0
  },
  "triggerAmount": {
    "currency": "EUR",
    "value": 0
  },
  "type": "push",
  "counterparty": {
    "transferInstrumentId": "SE32272223222D5DHXWBB9995"
  },
  "currency": "EUR"
}

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

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.
category -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, 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