--- title: "Configure custom payout schedules" description: "Set up scheduled automatic payouts to your user's verified bank account." url: "https://docs.adyen.com/platforms/custom-payouts/scheduled-payouts" source_url: "https://docs.adyen.com/platforms/custom-payouts/scheduled-payouts.md" canonical: "https://docs.adyen.com/platforms/custom-payouts/scheduled-payouts" last_modified: "2022-04-20T10:24:00+02:00" language: "en" --- # Configure custom payout schedules Set up scheduled automatic payouts to your user's verified bank account. [View source](/platforms/custom-payouts/scheduled-payouts.md) You can automate payouts from a balance account to your user's verified bank accounts by configuring a custom payout schedule. The schedule automatically initiates a payout from a balance account to your user's bank account based on a pre-defined frequency, trigger amount, and source or destination. When setting up a custom scheduled payout, consider the [cutoff times](/platforms/custom-payouts#transfer-cutoff) for each bank transfer method in each region. Cutoff times affect the expected time for your users to receive the funds in their bank account. ## Requirements Before you begin, take into account the following requirements: | Requirement | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Your API credential for the [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) must have the following [role](/platforms/manage-access/webservice-roles?tab=transfers_2):- **TransferService Webservice Initiate role** | | **[Customer Area roles](/account/user-roles)** | You must have the following roles:- **Balance platform base role** - **Configure scheduled payouts** | | **[Webhooks](/development-resources/webhooks)** | To track fund movements in your platform, you can subscribe to the following webhooks:- [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) - [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) | | **[Capabilities](/platforms/verification-overview/capabilities)** | Make sure that your user has the following capability:- **sendToTransferInstrument** | | **Setup steps** | Before you begin:- Make sure that the account holder and transfer instrument are linked to the same legal entity. - Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) if you want to configure a [default transfer description](/platforms/payout-descriptions) for your platform. - We recommend that you [calculate the available transfer routes](/platforms/custom-payouts/transfer-routes). This can enable you to design a configuration that optimally aligns with your use case and minimizes the risk of transfer failures by proactively identifying supported routes and highlighting any necessary parameters. | ## How it works You can configure custom payout schedules on [balance accounts](/platforms/account-structure-resources) in your platform. When you create a schedule, you can define the conditions that must be met for a payout to be initiated. You can set the following conditions: * Set a specific date and time. * Transfer the entire [available amount](/platforms/payout-amount) or a fixed amount. * Maintain an amount on the balance account. * Set an amount that triggers the payout. When all the conditions of the payout schedule are met, a transfer request is triggered automatically. Adyen sends webhooks to your server when a transfer request is triggered from a custom payout schedule. ## Create a custom payout schedule To set up automatic payouts, you must create a custom payouts schedule in your [Customer Area](https://ca-test.adyen.com/) or by making a [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) request. ### Tab: Customer Area To configure a custom payout schedule in your [Customer Area](https://ca-test.adyen.com/): 1. Go to **Accounts & balances** > **Account holders**, and search for the account holder. 2. Open the **Balance accounts** tab and select the relevant **Balance account ID**. 3. Under **Scheduled transfers**, select **Add a schedule**. 4. Choose **Pay out to another account** as the transfer type, and select **Continue**. 5. Enter and verify the required configuration details in their respective fields. | Field | Required | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Currency** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set the currency of the transfer. | | **What should the payout do?** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Choose how the funds are to be paid out. Possible values are:- **Transfer all available balance from this account** - **Maintain a specific balance in this account** - **Transfer a specific amount from this account** | | **Minimum balance for payout** | | Set a trigger amount. The trigger amount is the minimum balance needed to send a payout. If the balance is lower than this amount, the funds will not be paid out. If you always want payouts to be sent automatically, regardless of the balance, enter **0**. | | **Transfer balance to** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Select the **Transfer instrument**. | | **Transfer instrument** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Select the ID of the transfer instrument. | 6. Select **Next to schedule**. 7. If you are setting up a schedule to pay out all available funds from the balance account, select **Set a custom time to send a payout**. 8. Enter and verify the following configuration details in their respective fields. | Field | Required | Description | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How frequently should the payout arrive?** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set the payout frequency. If you set the frequency to **Monthly** or **Weekly**, you must also specify the day in the next step. | | **What time should the payout be sent?** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Specify the timing of the payout. | | **Description** | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | An identifier for the transfer. This value must be alphanumeric with no spaces and can be static, [dynamic](/platforms/payout-descriptions#scheduled-payouts), or a combination of both. | | **Reference for beneficiary** | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | The identifier, for example an invoice number, that appears on the recipient's bank statement. This value must be alphanumeric with no spaces and can be static, [dynamic](/platforms/custom-payouts/scheduled-payouts/?tab=API-1_2#optional-dynamic-transfer-statement-descriptions), or a combination of both. | | **Transfer priorities** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Specify how fast you want the funds to arrive to your user's bank account by setting a [priority for the payout](/platforms/custom-payouts#transfer-priority). A payout with a higher priority incurs higher fees. | 9. **Review** the information that you provided. 10. Select **Add**. The details of your scheduled payouts are shown under **Scheduled transfers**. The following example shows how to enter the configuration details with the following conditions: * Pay out all available funds at the beginning of each month. * The balance in their [balance account](/platforms/account-structure-resources) is higher than USD 250. | Field | Details | | -------------------------------------------- | ---------------------------------------------------- | | **Currency** | **USD** | | **What should the payout do?** | **Transfer all available balance from this account** | | **Minimum balance for payout** | **250** | | **Transfer balance to** | **Transfer instrument** | | **Transfer instrument** | **SE00000000000000000000001** | | **How frequently should the payout arrive?** | **Monthly** | | **Which day should the transfer arrive?** | **1st** | | **What time should the payout be sent?** | **07:00** | | **Description** | **monthlyPayout** | | **Reference for beneficiary** | **Payout001** | | **Transfer priorities** | **Regular** | ### Tab: API The following instructions describe how to pay out the full available balance in the balance account according to a specific schedule. To change the default behavior, you can include [additional objects](#optional-configuration) in your request. To create a custom schedule: 1. Make a POST [/balanceAccounts/{balanceAccountId}/sweeps](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps) request with the ID of the balance account in the path and the following parameters in the body: | Parameter name | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [counterparty](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-counterparty) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments) ID of the destination of the funds. The transfer instrument must be linked to the account holder's [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities). | | [currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-currency) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The currency of the payout. | | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-description) | | Your description for the resulting transfers, which is used by most recipient banks as the [transfer description](/platforms/payout-descriptions). You can set placeholders to generate [dynamic transfer descriptions](#dynamic-transfer-statement-description). Check the character limits based on the location of the bank account and the priority of the transfer. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-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](#dynamic-transfer-statement-description). | | [schedule.type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-schedule-CronSweepSchedule-type) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The schedule when the payout is evaluated. Set this parameter to **cron**. | | [schedule.cronExpression](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-schedule-CronSweepSchedule-cronExpression) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The [cron expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) for the schedule when the payout is evaluated, using the time zone of the balance account. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-schedule-type) | | The direction of the funds transfer. Set this parameter to **push**. | | [category](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-category) | | The type of transfer that results from the payout. Required when setting `priorities`. | | [priorities](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-priorities) | | The list of [priorities](/platforms/custom-payouts#transfer-priority) 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 [priorities](#priorities). | In the following example, we create a custom payout schedule to pay out the full available balance to a transfer instrument every Wednesday at 9:30 AM. **Create a payout schedule** #### curl ```bash 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": "USD", "schedule": { "cronExpression": "30 9 * * 3", "type": "cron" }, "type": "push" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule() .cronExpression("30 9 * * 3") .type(SweepSchedule.TypeEnum.CRON); SweepCounterparty sweepCounterparty2 = new SweepCounterparty() .transferInstrumentId("SE00000000000000000000001"); CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2() .schedule(sweepSchedule2) .counterparty(sweepCounterparty2) .currency("EUR") .type(CreateSweepConfigurationV2.TypeEnum.PUSH); // Send the request BalanceAccountsApi service = new BalanceAccountsApi(client); SweepConfigurationV2 response = service.createSweep("balanceAccountId", createSweepConfigurationV2, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $sweepSchedule2 = new SweepSchedule(); $sweepSchedule2 ->setCronExpression("30 9 * * 3") ->setType("cron"); $sweepCounterparty2 = new SweepCounterparty(); $sweepCounterparty2 ->setTransferInstrumentId("SE00000000000000000000001"); $createSweepConfigurationV2 = new CreateSweepConfigurationV2(); $createSweepConfigurationV2 ->setSchedule($sweepSchedule2) ->setCounterparty($sweepCounterparty2) ->setCurrency("EUR") ->setType("push"); // Send the request $service = new BalanceAccountsApi($client); $response = $service->createSweep('balanceAccountId', $createSweepConfigurationV2); ``` #### C\# ```cs // Adyen .net API Library v27.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule { CronExpression = "30 9 * * 3", Type = SweepSchedule.TypeEnum.Cron }; SweepCounterparty sweepCounterparty2 = new SweepCounterparty { TransferInstrumentId = "SE00000000000000000000001" }; CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2 { Schedule = sweepSchedule2, Counterparty = sweepCounterparty2, Currency = "EUR", Type = CreateSweepConfigurationV2.TypeEnum.Push }; // Send the request var service = new BalanceAccountsService(client); var response = service.CreateSweep("balanceAccountId", createSweepConfigurationV2); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const createSweepConfigurationV2 = { counterparty: { transferInstrumentId: "SE00000000000000000000001" }, currency: "EUR", schedule: { cronExpression: "30 9 * * 3", type: "cron" }, type: "push" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` #### Go ```go // Adyen Go API Library v16.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v16/src/common" "github.com/adyen/adyen-go-api-library/v16/src/adyen" "github.com/adyen/adyen-go-api-library/v16/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) sweepSchedule2 := balancePlatform.SweepSchedule{ CronExpression: common.PtrString("30 9 * * 3"), Type: "cron", } sweepCounterparty2 := balancePlatform.SweepCounterparty{ TransferInstrumentId: common.PtrString("SE00000000000000000000001"), } createSweepConfigurationV2 := balancePlatform.CreateSweepConfigurationV2{ Schedule: sweepSchedule2, Counterparty: sweepCounterparty2, Currency: "EUR", Type: common.PtrString("push"), } // Send the request service := client.BalancePlatform() req := service.BalanceAccountsApi.CreateSweepInput("balanceAccountId").CreateSweepConfigurationV2(createSweepConfigurationV2) res, httpRes, err := service.BalanceAccountsApi.CreateSweep(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "counterparty": { "transferInstrumentId": "SE00000000000000000000001" }, "currency": "EUR", "schedule": { "cronExpression": "30 9 * * 3", "type": "cron" }, "type": "push" } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_sweep(request=json_request, balanceAccountId="balanceAccountId") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :counterparty => { :transferInstrumentId => 'SE00000000000000000000001' }, :currency => 'EUR', :schedule => { :cronExpression => '30 9 * * 3', :type => 'cron' }, :type => 'push' } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_sweep(request_body, 'balanceAccountId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const sweepSchedule2: Types.balancePlatform.SweepSchedule = { cronExpression: "30 9 * * 3", type: Types.balancePlatform.SweepSchedule.TypeEnum.Cron }; const sweepCounterparty2: Types.balancePlatform.SweepCounterparty = { transferInstrumentId: "SE00000000000000000000001" }; const createSweepConfigurationV2: Types.balancePlatform.CreateSweepConfigurationV2 = { schedule: sweepSchedule2, counterparty: sweepCounterparty2, currency: "EUR", type: Types.balancePlatform.CreateSweepConfigurationV2.TypeEnum.Push }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` 2. In the response, note the following: * The unique identifier of the schedule. * The default values for the [optional configuration](#optional-configuration). * The `status` of the schedule, which is **active** by default. You can change it by sending an updated status in a PATCH [/balanceAccounts/{balanceAccountId}/sweeps/{sweepId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balanceAccounts/\(balanceAccountId\)/sweeps/\(sweepId\)) request. **Response - payout schedule created** ```json { "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" } ``` 3. Listen to the [balancePlatform.balanceAccountSweep.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.created) webhook to learn whether the schedule was created successfully. ### Optional configuration When creating a sweep, you can also configure the following: * [Set a trigger amount, minimum balance, or a fixed payout amount.](#sweep-configuration) * [Use placeholders to set dynamic descriptions.](#dynamic-transfer-statement-description) * [Specify a priority or a list of priorities](#priorities) to manage the speed at which the payout is sent and the fees that you have to pay. ** #### Sweep configuration By default, all the [available balance](/platforms/payout-amount) in the balance account is paid out according to the schedule that you specified. You can change this default behavior by providing additional objects in your API request. | Optional configuration | Additional object | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Set a trigger amount | [triggerAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-triggerAmount) | When the payout is evaluated at the schedule you specified, Adyen checks if the available balance is more than or equal to the `triggerAmount`. If this condition is met, all funds in the balance account are paid out. | | Maintain a minimum balance | [targetAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-targetAmount) | You can set a minimum balance for the balance account, for example, to maintain balances for day-to-day operational purposes. The amount in excess of the `targetAmount` is paid out to the transfer instrument. The [triggerAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-triggerAmount) must be higher than the `targetAmount`. | | Pay out a fixed amount | [sweepAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-sweepAmount) | You can pay out a specific amount, instead of the full available balance. The [triggerAmount](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-triggerAmount) must be equal to or higher than the `sweepAmount`. | The following example request shows how you can update the [previous sweep](#response-sweep-created) 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** ```bash 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](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.updated) webhook to your server. ** #### Dynamic transfer statement description When [creating a schedule using the API](#create-custom-schedule), 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 schedule** #### curl ```bash 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" }' ``` #### Java ```java // Adyen Java API Library v25.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balancePlatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule() .cronExpression("54 15 * * *") .type(SweepSchedule.TypeEnum.CRON); SweepCounterparty sweepCounterparty2 = new SweepCounterparty() .transferInstrumentId("SE322KH223222D5FM372M6337"); CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2() .schedule(sweepSchedule2) .counterparty(sweepCounterparty2) .description("$accountHolderId and $accountHolderDescription") .currency("EUR") .type(CreateSweepConfigurationV2.TypeEnum.PUSH) .status(CreateSweepConfigurationV2.StatusEnum.ACTIVE); // Make the API call BalanceAccountsApi service = new BalanceAccountsApi(client); SweepConfigurationV2 response = service.createSweep("balanceAccountId", createSweepConfigurationV2, null); ``` #### PHP ```php // Adyen PHP API Library v17.4.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\BalancePlatform\SweepSchedule; use Adyen\Model\BalancePlatform\SweepCounterparty; use Adyen\Model\BalancePlatform\CreateSweepConfigurationV2; use Adyen\Service\BalancePlatform\BalanceAccountsApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $sweepSchedule2 = new SweepSchedule(); $sweepSchedule2 ->setCronExpression("54 15 * * *") ->setType("cron"); $sweepCounterparty2 = new SweepCounterparty(); $sweepCounterparty2 ->setTransferInstrumentId("SE322KH223222D5FM372M6337"); $createSweepConfigurationV2 = new CreateSweepConfigurationV2(); $createSweepConfigurationV2 ->setSchedule($sweepSchedule2) ->setCounterparty($sweepCounterparty2) ->setDescription("\$accountHolderId and \$accountHolderDescription") ->setCurrency("EUR") ->setType("push") ->setStatus("active"); // Make the API call $service = new BalanceAccountsApi($client); $response = $service->createSweep('balanceAccountId', $createSweepConfigurationV2); ``` #### C\# ```cs // Adyen .net API Library v14.4.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) SweepSchedule sweepSchedule2 = new SweepSchedule { CronExpression = "54 15 * * *", Type = SweepSchedule.TypeEnum.Cron }; SweepCounterparty sweepCounterparty2 = new SweepCounterparty { TransferInstrumentId = "SE322KH223222D5FM372M6337" }; CreateSweepConfigurationV2 createSweepConfigurationV2 = new CreateSweepConfigurationV2 { Schedule = sweepSchedule2, Counterparty = sweepCounterparty2, Description = "$accountHolderId and $accountHolderDescription", Currency = "EUR", Type = CreateSweepConfigurationV2.TypeEnum.Push, Status = CreateSweepConfigurationV2.StatusEnum.Active }; // Make the API call var service = new BalanceAccountsService(client); var response = service.CreateSweep("balanceAccountId", createSweepConfigurationV2); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use const { Client, BalancePlatformAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const createSweepConfigurationV2 = { counterparty: { transferInstrumentId: "SE322KH223222D5FM372M6337" }, currency: "EUR", description: "$accountHolderId and $accountHolderDescription", schedule: { cronExpression: "54 15 * * *", type: "cron" }, status: "active", type: "push" } // Make the API call const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` #### Go ```go // Adyen Go API Library v9.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) sweepSchedule2 := balancePlatform.SweepSchedule{ CronExpression: common.PtrString("54 15 * * *"), Type: "cron", } sweepCounterparty2 := balancePlatform.SweepCounterparty{ TransferInstrumentId: common.PtrString("SE322KH223222D5FM372M6337"), } createSweepConfigurationV2 := balancePlatform.CreateSweepConfigurationV2{ Schedule: sweepSchedule2, Counterparty: sweepCounterparty2, Description: common.PtrString("$accountHolderId and $accountHolderDescription"), Currency: "EUR", Type: common.PtrString("push"), Status: common.PtrString("active"), } // Make the API call service := client.BalancePlatform() req := service.BalanceAccountsApi.CreateSweepInput("balanceAccountId").CreateSweepConfigurationV2(createSweepConfigurationV2) res, httpRes, err := service.BalanceAccountsApi.CreateSweep(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "counterparty": { "transferInstrumentId": "SE322KH223222D5FM372M6337" }, "currency": "EUR", "description": "$accountHolderId and $accountHolderDescription", "schedule": { "cronExpression": "54 15 * * *", "type": "cron" }, "status": "active", "type": "push" } # Make the API call result = adyen.balancePlatform.balance_accounts_api.create_sweep(request=json_request, balanceAccountId="balanceAccountId") ``` #### Ruby ```rb # Adyen Ruby API Library v9.3.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :counterparty => { :transferInstrumentId => 'SE322KH223222D5FM372M6337' }, :currency => 'EUR', :description => '$accountHolderId and $accountHolderDescription', :schedule => { :cronExpression => '54 15 * * *', :type => 'cron' }, :status => 'active', :type => 'push' } # Make the API call result = adyen.balancePlatform.balance_accounts_api.create_sweep(request_body, 'balanceAccountId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const sweepSchedule2: Types.balancePlatform.SweepSchedule = { cronExpression: "54 15 * * *", type: Types.balancePlatform.SweepSchedule.TypeEnum.Cron }; const sweepCounterparty2: Types.balancePlatform.SweepCounterparty = { transferInstrumentId: "SE322KH223222D5FM372M6337" }; const createSweepConfigurationV2: Types.balancePlatform.CreateSweepConfigurationV2 = { schedule: sweepSchedule2, counterparty: sweepCounterparty2, description: "$accountHolderId and $accountHolderDescription", currency: "EUR", type: Types.balancePlatform.CreateSweepConfigurationV2.TypeEnum.Push, status: Types.balancePlatform.CreateSweepConfigurationV2.StatusEnum.Active }; // Make the API call const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createSweep("balanceAccountId", createSweepConfigurationV2); ``` 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. ** #### Priorities When you create or update custom payout schedules, we recommend that you specify the [priority](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-priorities) of the funds transfer. The specified priority or a list of priorities affect the speed at which the funds are paid out 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, we use the default priority, 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 payout is executed using the first priority that leads to a valid route given the transfer 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 schedule to set up transfer priorities order** #### curl ```bash 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" }' ``` #### Java ```java // Adyen Java API Library v25.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balancePlatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) Amount amount2 = new Amount() .currency("EUR") .value(20000L); Amount amount3 = new Amount() .currency("EUR") .value(25000L); UpdateSweepConfigurationV2 updateSweepConfigurationV2 = new UpdateSweepConfigurationV2() .targetAmount(amount2) .triggerAmount(amount3); // Make the API call BalanceAccountsApi service = new BalanceAccountsApi(client); SweepConfigurationV2 response = service.updateSweep("balanceAccountId", "sweepId", updateSweepConfigurationV2, null); ``` #### PHP ```php // Adyen PHP API Library v17.4.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\BalancePlatform\Amount; use Adyen\Model\BalancePlatform\UpdateSweepConfigurationV2; use Adyen\Service\BalancePlatform\BalanceAccountsApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $amount2 = new Amount(); $amount2 ->setCurrency("EUR") ->setValue(20000); $amount3 = new Amount(); $amount3 ->setCurrency("EUR") ->setValue(25000); $updateSweepConfigurationV2 = new UpdateSweepConfigurationV2(); $updateSweepConfigurationV2 ->setTargetAmount($amount2) ->setTriggerAmount($amount3); // Make the API call $service = new BalanceAccountsApi($client); $response = $service->updateSweep('balanceAccountId', 'sweepId', $updateSweepConfigurationV2); ``` #### C\# ```cs // Adyen .net API Library v14.4.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) UpdateSweepConfigurationV2 updateSweepConfigurationV2 = new UpdateSweepConfigurationV2 { Priorities = { UpdateSweepConfigurationV2.PrioritiesEnum.Fast, UpdateSweepConfigurationV2.PrioritiesEnum.Regular }, Category = UpdateSweepConfigurationV2.CategoryEnum.Bank }; // Make the API call var service = new BalanceAccountsService(client); var response = service.UpdateSweep("balanceAccountId", "sweepId", updateSweepConfigurationV2); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use const { Client, BalancePlatformAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const updateSweepConfigurationV2 = { triggerAmount: { value: 25000, currency: "EUR" }, targetAmount: { value: 20000, currency: "EUR" } } // Make the API call const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.updateSweep("balanceAccountId", "sweepId", updateSweepConfigurationV2); ``` #### Go ```go // Adyen Go API Library v9.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) updateSweepConfigurationV2 := balancePlatform.UpdateSweepConfigurationV2{ Priorities: []string{ "fast", "regular", }, Category: common.PtrString("bank"), } // Make the API call service := client.BalancePlatform() req := service.BalanceAccountsApi.UpdateSweepInput("balanceAccountId","sweepId").UpdateSweepConfigurationV2(updateSweepConfigurationV2) res, httpRes, err := service.BalanceAccountsApi.UpdateSweep(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.2.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "triggerAmount": { "value": 25000, "currency": "EUR" }, "targetAmount": { "value": 20000, "currency": "EUR" } } # Make the API call result = adyen.balancePlatform.balance_accounts_api.update_sweep(request=json_request, balanceAccountId="balanceAccountId", sweepId="sweepId") ``` #### Ruby ```rb # Adyen Ruby API Library v9.3.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :triggerAmount => { :value => 25000, :currency => 'EUR' }, :targetAmount => { :value => 20000, :currency => 'EUR' } } # Make the API call result = adyen.balancePlatform.balance_accounts_api.update_sweep(request_body, 'balanceAccountId', 'sweepId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const amount2: Types.balancePlatform.Amount = { currency: "EUR", value: 20000 }; const amount3: Types.balancePlatform.Amount = { currency: "EUR", value: 25000 }; const updateSweepConfigurationV2: Types.balancePlatform.UpdateSweepConfigurationV2 = { targetAmount: amount2, triggerAmount: amount3 }; // Make the API call const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.updateSweep("balanceAccountId", "sweepId", updateSweepConfigurationV2); ``` The response returns the updated schedule details. Adyen also sends a corresponding [balancePlatform.balanceAccountSweep.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.updated) webhook to your server. When you successfully create a custom payout schedule, Adyen sends a [balancePlatform.balanceAccountSweep.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.created) webhook with its details. **Custom payout schedule created** ```json { "data": { "balanceAccountId": "BA00000000000000000000001", "sweep": { "id": "SW00000000000000000000001", "schedule": { "frequency": "monthly" }, "type": "push", "currency": "USD", "counterparty": { "transferInstrumentId": "SE00000000000000000000001" } } }, "type": "balancePlatform.balanceAccountSweep.created", "timestamp": "2026-05-01T10:15:30.000Z", "environment": "test" } ``` ## Track fund movements You can view the status of funds transfers initiated by a payout in your [Customer Area](https://ca-test.adyen.com/), or track them by listening to webhooks. To track the status of funds transfers initiated by a payout: 1. Listen to the following webhooks: * [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview): * [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook events notify you that funds will be deducted from a balance accounts. * [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook events notify of every status change of the funds transfer. * [`balanceAccountSweepExecution` ](/platforms/custom-payouts/scheduled-payouts/view-custom-payout-executions#execution-results-and-reasons)webhook events notify you of the success of failure of the payout executions. * [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview): Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook event to inform your server that funds have been deducted from a balance account. 2. Acknowledge the webhooks. 3. In the payload of the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook, note that: * The `event` array includes all previous transfer events. * The `sequenceNumber` defines the number of webhooks sent for the transfer, including the current one. For more details and examples, see [Payout executions](/platforms/custom-payouts/scheduled-payouts/view-custom-payout-executions#execution-results-and-reasons). ## View sweep details After you create a custom payout schedule, you can view the details of the resulting scheduled payout in your [Customer Area](https://ca-test.adyen.com/). 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](/platforms/internal-fund-transfers/scheduled-fund-transfers/) on the **Balance account details** page, under **Scheduled transfers**. To view the details of a scheduled payout: 1. Go to **Accounts & balances** > **Balance accounts**. 2. In the **Balance platform** dropdown, select the balance platform. You can view balance accounts from one balance platform at a time. 3. In the balance account table, select a balance account ID to open the **Balance account details** page. 4. Under **Scheduled transfers**, select a scheduled payout. 5. Open the **Details** tab to view information about the scheduled payout. ## See also * [View transfer details in your Customer Area](/platforms/view-transfers-details) * [Payout webhooks](/platforms/payout-webhooks)