Use managed payouts

Set up automatic and optimized payouts using preconfigured managed payout schedules on your balance platform.

View source

After you have configured managed payouts with you Adyen contact, you can manage them in your Customer Area or using the Configuration API. You can view and modify the following details of your managed payouts:

View a list of all your payout schedules and the details of each payout schedule on your balance platform.
Apply a payout schedule to a balance account.
View a list of all your managed payout schedules and the details of each payout schedule on a balance account.
Update a payout schedule applied to a balance account.
Deactivate or delete a payout schedule applied to a balance account.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations:

Requirement	Description
API credentials	Your API credential for the Configuration API must have the following role: Bank Scheduled Payouts Merchant Role
Customer Area roles	Make sure that your users have the following roles: Balance platform base role Configure scheduled payouts
Webhooks	Subscribe to the following webhook: Configuration webhooks Scheduled payout webhooks
Capabilities	Your user must have the following capability: sendToTransferInstrument
Limitations	You can only apply one payout schedule per currency on each balance account. Each payout schedule only supports one location and currency. You cannot automatically apply managed payout schedules to balance accounts associated with existing legal entities. Managed payouts don't affect the settlement of payments on pass-through or sales day payouts of T+7 or more. The settlements of these payments happens according to the indicated delay and will be paid out once settled.

View managed payout schedules for your balance platform

To view payout schedules configured on your balance platform:

From your server, make a GET /balancePlatforms/{balancePlatformId}/payoutSchedules request specifying the following parameters:

Parameter name	Parameter type	Description
`balancePlatformId`	Path	The unique identifier of your balance platform.
`countryCode`	Query	The ISO 3166-1 alpha-2 code of the country to which the payout schedule applies.
`currency`	Query	The ISO code of the currency for which the payout schedule applies.

The following code example shows a GET /balancePlatforms/{balancePlatformId}/payoutSchedules request for a list that includes all managed payout schedules in your balance platform.

In the response, the balancePlatformPayoutSchedules array contains all the payout schedules in your balance platform that match the query parameters.
Take note of the id of the payout schedules, as you will need them to apply the schedule to a balance account.

To get the details of a specific payout schedule, make a GET /balancePlatforms/{balancePlatformId}/payoutSchedules/{id} request.

Apply a payout schedule to a balance account

To pay out using your managed payout schedules, you must apply the schedules to your users' balance accounts.

You can only apply one payout schedule per currency on each balance account.

You can apply payout schedules to your balance accounts using one of the following methods:

Enable automatic application.
Make a POST /balanceAccounts/{balanceAccountId}/payoutSchedules request.
Use your Customer Area.

The following tabs explain each method.

If the the application of the managed payout schedule to the balance account is successful, Adyen sends a balancePlatform.balanceAccountPayoutSchedule.created webhook to notify you of the payout schedule creation.

View the payout schedule on a balance account

You can view the payout schedules on your balance account in your Customer Area, or by making a Configuration API request.

Update a payout schedule on a balance account

Deactivate a payout schedule on a balance account

You can temporarily deactivate a managed payout schedule on your balance account in your Customer Area, or by making a Configuration API request.

To deactivate a managed payout schedule applied to your balance platform, you must reach out to your Adyen contact.

Delete a payout schedule on a balance account

You can delete a managed payout schedule on your balance account in your Customer Area, or by making a Configuration API request.

To delete a managed payout schedule from your balance platform, reach out to your Adyen contact.

Testing

Before going live with managed payout schedules, we recommend that you test the scenarios described in the following table.

Test scenario Relevant schedules Scenario description Expected outcome

Successfully apply a managed payout schedule

All

Apply a managed payout schedule to a balance account using automatic application or the Configuration API.

If using automatic application, you must receive:

A balancePlatform.balanceAccountPayoutSchedule.created webhook

If using the Configuration API, you must receive:

An HTTP 200—OK response
A balancePlatform.balanceAccountPayoutSchedule.created webhook

Updating balance account details is not allowed

All

While a managed payout schedule is active, attempt a PATCH /balanceAccounts/{id} request to change the timeZone.

The request must fail. You must delete the schedule before changing the timeZone of a balance account.

You must receive an HTTP 422—Unprocessable Entity response. The response must include:

Error 30_021—Invalid Balance Account information provided

Application fails because of countryCode mismatch

All

Using automatic application or the Configuration API, attempt to apply a managed payout schedule with the US countryCode to a balance account with a transfer instrument that has the CA countryCode.

The application must fail because of countryCode mismatch.