---
title: "Schedule internal funds transfers"
description: "Create a schedule to automatically transfer funds between balance accounts within your marketplace."
url: "https://docs.adyen.com/marketplaces/internal-fund-transfers/scheduled-fund-transfers"
source_url: "https://docs.adyen.com/marketplaces/internal-fund-transfers/scheduled-fund-transfers.md"
canonical: "https://docs.adyen.com/marketplaces/internal-fund-transfers/scheduled-fund-transfers"
last_modified: "2020-09-11T17:20:00+02:00"
language: "en"
---

# Schedule internal funds transfers

Create a schedule to automatically transfer funds between balance accounts within your marketplace.

Automate internal funds transfers by configuring *sweeps*, in the same manner as setting up scheduled payouts. A sweep automatically pushes out or pulls in funds from a balance account based on a pre-defined schedule, amount, and source or destination. For more information, refer to [How sweeps work](/marketplaces/payout-to-users/scheduled-payouts#how-sweeps-work).

Configure a *push* or *pull* sweep depending on the scenario. For example, to maintain balances, you can set up a pull sweep to pull funds from another balance account when the balance goes below a certain amount. If you want to automate sending bonuses from your liable balance account, you can set up a push sweep to push funds from the liable balance account to your user's balance account.

This page explains how to configure sweeps to schedule automatic transfers between balance accounts.

## Requirements

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

| Requirement                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                           | You need an [Adyen for Platforms](/adyen-for-platforms-model) integration.                                                                                                                                                                                                                                                                                                                                                                                                             |
| **[API credentials](/marketplaces/manage-access/api-credentials-web-service)** | Your API credential for the [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) must have the following [role](/marketplaces/manage-access/webservice-roles?tab=transfers_2): - **TransferService Webservice Initiate role**                                                                                                                                                                                                                                |
| **[Customer Area roles](/account/user-roles)**                                 | You need the following roles: - **Initiate internal transfers**

- **Balance platform base role**                                                                                                                                                                                                                                                                                                                                                                                      |
| **[Webhooks](/development-resources/webhooks/configure-and-manage)**           | 1. Make sure that your server receives and accepts webhooks.

2. In your Customer Area, subscribe to [Transfer webhooks](/marketplaces/webhook-types#transfer-webhooks).                                                                                                                                                                                                                                                                                                               |
| **[Capabilities](/marketplaces/verification-overview/capabilities)**           | If the balance accounts involved in the transfer *do not belong to the same account holder*, check the [capabilities](/marketplaces/verification-overview/capabilities#capabilities) of the account holders:- The account holder of the balance account that sends the the transfer request must have the **sendToBalanceAccount** capability.

- The account holder of the balance account that receives the transfer request must have the **receiveFromBalanceAccount** capability. |
| **Setup steps**                                                                | Before you begin your integration, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable transfers for the source balance account.                                                                                                                                                                                                                                                                                                  |

## Step 1. Create a sweep

Configure sweeps by using your [Customer Area](https://ca-test.adyen.com/), or making a POST [/balanceAccounts/{balanceAccountId}/sweeps](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps) request. In this example, we will use a *push* sweep to push funds out of a balance account.

### Tab: Customer Area

To configure sweeps in your [Customer Area](https://ca-test.adyen.com/), your account must have the **Manage sweep configurations** [role](/account/user-roles#platforms).

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 **Add a schedule**.

5. Select **Payout schedule**.

6. Select **Next**.

7. Enter and verify the configuration details in their respective fields.

   | Field                     | Description                                                                                                                                                                                                                               |   |
   | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
   | **When balance on**       | Automatically set to the balance account ID.                                                                                                                                                                                              |   |
   | **Is more or equal to**   | Set a trigger amount. Before paying out the funds, Adyen checks if the [available balance](/marketplaces/payout-to-users/scheduled-payouts#how-adyen-calculates-the-available-payout-amount) is more than or equal to the trigger amount. |   |
   | **Action**                | Select **Push an amount** or **Maintain a balance**.                                                                                                                                                                                      |   |
   | **Push this amount**      | Select **Entire available balance** or **Custom**. Read more on [how Adyen calculates the available balance](/marketplaces/payout-to-users/scheduled-payouts#how-adyen-calculates-the-available-payout-amount).                           |   |
   | **Push balance to**       | Select **Balance account**.                                                                                                                                                                                                               |   |
   | **Balance account Id**    | Select the ID of the balance account.                                                                                                                                                                                                     |   |
   | **When schedule matches** | Select one of the predefined schedules or **Custom** to define your own schedule.                                                                                                                                                         |   |
   | **Schedule**              | If you select a **Custom** schedule, specify the schedule or a cron expression. Select **Submit**.                                                                                                                                        |   |
   | **Activate**              | **Immediately after creation**                                                                                                                                                                                                            |   |
   | **Description**           | (Optional) Enter a description for the schedule.                                                                                                                                                                                          |   |

8. Select **Next**.

9. Review the information that you provided.

10. Select **Save**.

The details of your scheduled transfer are shown in **Scheduled transfers**.

The following example shows how to enter the configuration details.

**

### Example — Maintain a balance by transferring funds

Your user has two balance accounts, **balance account 1** and **balance account 2**, which they use for different purposes. On **balance account 1**, they want to maintain a balance of EUR 200. To do this, they want to check on every Wednesday at 9:30 AM if the funds in **balance account 1** have exceeded EUR 250 and push this excess to **balance account 2**.

The following table shows the details you must enter for this case.

| Field                     | Details                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **When balance on**       | **BA00000000000000000000001**                                                                               |
| **Is more or equal to**   | **EUR 250**                                                                                                 |
| **Action**                | **Maintain a balance**                                                                                      |
| **Maintain a balance of** | **EUR 200**                                                                                                 |
| **Push balance to**       | **Balance account**                                                                                         |
| **Balance account**       | **BA00000000000000000000002**                                                                               |
| **When schedule matches** | **Custom**                                                                                                  |
| **Schedule**              | [**Cron Expression** ](http://www.nncron.ru/help/EN/working/cron-format.htm)> **30 9 \* \* 3** > **Submit** |
| **Activate**              | **Immediately after creation**                                                                              |

### Tab: API

The following instructions describe how to transfer 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 sweep:

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 [balance account](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts) ID of the destination of the funds.                                                                                                                                                               |
   | [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 sweep. This must match one of the currencies of the balances.                                                                                                                                                                                                                        |
   | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-description)                                           |                                                                                                               | The description for the resulting transfers, which is used by most recipient banks as the [transfer description](/marketplaces/payout-to-users#transfer-statement-description). You can set placeholders to generate [dynamic transfer descriptions](#optional-dynamic-transfer-statement-descriptions). |
   | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(balanceAccountId\)/sweeps#request-referenceForBeneficiary)                   |                                                                                                               | The second description field, which is available in most locations. You can set placeholders to generate [dynamic transfer descriptions](#optional-dynamic-transfer-statement-descriptions).                                                                                                             |
   | [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 sweep 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 sweep 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)                                                |                                                                                                               | Default value is **push**.                                                                                                                                                                                                                                                                               |

   In the following example, we create a sweep to transfer the full available balance to another balance account every Wednesday at 9:30 AM.

   **Create a sweep**

   #### 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": {
         "balanceAccountId": "BA00100000000000000000001"
       },
       "currency": "EUR",
       "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()
     .balanceAccountId("BA00100000000000000000001");

   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
   <?php
   // Adyen PHP API Library v24.0.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_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
     ->setBalanceAccountId("BA00100000000000000000001");

   $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
   {
     BalanceAccountId = "BA00100000000000000000001"
   };

   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: {
       balanceAccountId: "BA00100000000000000000001"
     },
     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{
     BalanceAccountId: common.PtrString("BA00100000000000000000001"),
   }

   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": {
       "balanceAccountId": "BA00100000000000000000001"
     },
     "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 => {
       :balanceAccountId => 'BA00100000000000000000001'
     },
     :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 = {
     balanceAccountId: "BA00100000000000000000001"
   };

   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 sweep.
   * The default values for the [optional configuration](#optional-configuration).
   * The `status` of the sweep, 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 - sweep created**

   ```json
   {
       "id": "SWPC4227C223222B5FTD2NT2JV4WN5",
       "schedule": {
           "type": "cron",
           "cronExpression": "30 9 * * 3"
       },
       "status": "active",
       "targetAmount": {
           "currency": "EUR",
           "value": 0
       },
       "triggerAmount": {
           "currency": "EUR",
           "value": 0
       },
       "type": "push",
       "counterparty": {
           "balanceAccountId": "BA00100000000000000000001"
       },
       "currency": "EUR",
       "description": "Internal funds transfer 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 sweep was created successfully.

**

#### Optional sweep configuration

By default, all the [available balance](/marketplaces/payout-to-users/scheduled-payouts#how-adyen-calculates-the-available-payout-amount) in the balance account is transferred at 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 sweep is evaluated at the schedule you specified, Adyen checks if the [available balance](/marketplaces/payout-to-users/scheduled-payouts#how-adyen-calculates-the-available-payout-amount) is more than or equal to the `triggerAmount`. If this condition is met, all funds in the balance account are transferred.                                                                                              |
| 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 transferred to the counterparty balance account. 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 transfer 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.

**

#### Optional dynamic transfer statement descriptions

When [creating a sweep using the API](#create-sweep), you can use placeholders to set dynamic descriptions.

Setting a description overrides [default descriptions](#before-you-begin) 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 sweep**

#### 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.

## Step 2. Get updates when a transfer results from a sweep

For every internal transfer request that results from a sweep, Adyen sends multiple [webhooks](/marketplaces/internal-fund-transfers/internal-transfer-webhooks) to your server: a series of webhooks for the balance account where the transfer is an outgoing request, and a series of webhooks for the balance account where the transfer is an incoming request.

Using these webhooks, you can track the status of the transfer: **received**, then **authorised**, and finally **booked**. The webhooks also inform you if the transfer failed.

You can also [view the transfer details in your Customer Area](/marketplaces/view-transfers-details). Each transfer of funds between balance accounts appears in the Customer Area as two transfer entries: one for the balance account that is credited, and one for the balance account that is debited.

## Troubleshooting

If an internal fund transfer fails, verify if there are enough funds in the source balance account:

1. Make a GET [/balanceAccounts/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)) request, specifying the source balance account's ID in the path.

2. Check the [available](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)#responses-200-balances-available) balance.

3. If the amount is lower than the transfer amount, you can:

   * Ask your user to [top up](/marketplaces/top-up-balance-account) their balance account.
   * Make an internal transfer from your liable balance account to your user's balance account.

If there are enough funds in the balance account, but the transfer still fails, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

## View sweep details

After you create a sweep, you can view the details of the resulting scheduled transfer in your [Customer Area](https://ca-test.adyen.com/). These details include:

* Transfer amount
* Source and destination of the transfer
* Completed and upcoming scheduled transfers

You can view the details of all [payout schedules](/marketplaces/payout-to-users/scheduled-payouts) and internal transfer schedules in the **Balance account details** page, under **Scheduled transfers**. To do this, your account must have the **Balance platform base** [role](/account/user-roles/).

To view the details of a scheduled transfer:

1. Select **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 transfer.

5. Open the **Details** tab to view information about the scheduled transfer.

6. Open the **Events** tab to track the event history of the scheduled transfer. You can:

   * View the date of the next scheduled transfer.
   * View a history of past transfer events, including their execution dates and statuses.

### Transfer statuses

The table below explains the statuses you may see in the **Events** tab for each scheduled transfer, along with their possible reasons:

| Status      | Description                                                                                                                  | Possible reasons                                   |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Success** | The transfer was created. The details include the transfer amount, the transfer ID, and a link to the transfer details page. | Not applicable.                                    |
| **Failed**  | The transfer failed.                                                                                                         | **Unauthorized**: The transfer was not authorized. |
| **Success** | The transfer was created. The details include the transfer amount, the transfer ID, and a link to the transfer details page. | Not applicable.                                    |