# Create a batch transfer

Airwallex Batch Transfers allows you to create multiple transfers in bulk to streamline your transaction processing and reconciliation, and leverage different funding sources such as the Wallet or Linked Bank Account. Easily manage multiple transfers to recipients in various countries/regions and in various currencies to multiple beneficiaries for payroll runs and supplier payments. As a platform, you can bring your customers onto Airwallex and enhance your product offering by creating Batch Transfers on their behalf. Learn how to programmatically create batch transfers with our [Batch Transfer API endpoints](/api/payouts/batch_transfers) in the following sections.

> **\[INFORMATIONAL]**
>
> **New feature:** Airwallex supports batch transfers created via API to be routed through the transfer approval workflow set up on the Airwallex account. Learn more in [Manage approvals for batch transfers](https://www.airwallex.com/docs/payouts/batch-transfers/manage-batch-transfers/manage-approvals-for-batch-transfers.md).

## Before you begin

- [Obtain your access token](/api/authentication/api_access_token) by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
- Check out [Payout Network](https://www.airwallex.com/docs/payouts/payout-network.md) for supported regions and currencies, and the country guides under it for more details on transfer methods, delivery times, and other country specific details.
- As a platform, you can call all Batch Transfers API endpoints on behalf of your connected accounts by specifying the connected account's open ID (in the format `acct_xxxxxx`) in the `x-on-behalf-of` header of your API request. To learn about how you can register as a platform and set up this solution, see [Global Treasury](https://www.airwallex.com/docs/global-treasury/overview.md) and [Global Finance](https://www.airwallex.com/docs/banking-as-a-service/overview.md).

## Step 1: Create a batch transfer

Call [Create a batch transfer](/api/payouts/batch_transfers/create) with the required funding source and batch information (name, remarks, request id, transfer date) to create a batch transfer. Please find below further considerations on some of the parameters:

- `funding_source`: funding source details should only be provided in this object if the batch transfer is to be funded via direct debit from Linked Account. Do not specify any parameters for Wallet as the funding source.
  - `id`: Unique ID of your Linked Account as returned in [Create a Linked Account](/api/core_resources/linked_accounts/create).
  - `deposit_type`: Should be either `DIRECT_DEBIT` or `FASTER_DIRECT_DEBIT`. Deposit type will default to `DIRECT_DEBIT` if not specified. See [direct debit flight times](https://www.airwallex.com/docs/global-treasury/receive-funds/add-funds-via-direct-debits-from-linked-accounts/understanding-direct-debit-flight-times-and-funding-limits.md) to understand difference between the two deposit types.

- `transfer_date`: current or future date (ISO 8601 format) for when the batch transfer should be processed. If left blank, the transfer date will default to the earliest possible date.

  > **\[WARNING]**
  >
  > To dispatch a batch transfer as soon as possible, omit `transfer_date`. Setting `transfer_date` (including today's date) routes the batch transfer through scheduled-transfer logic and is not equivalent to omitting the field.
  >
  >
  >
  >
  >
  > `transfer_date` is interpreted in your request account owning entity timezone. For related lifecycle behavior and timing details, see [Batch transfer statuses](https://www.airwallex.com/docs/payouts/batch-transfers/create-a-batch-transfer/batch-transfer-statuses.md), [Fund deduction](https://www.airwallex.com/docs/payouts/batch-transfers/create-a-batch-transfer#fund-deduction.md), and [Funding and Settlement Models](https://www.airwallex.com/docs/transactional-fx/funding-and-settlement-models.md).

Transfer items with the same source and transfer currency can support transfer dates up to 120 days into the future; whereas transfer items with currency conversions can support transfer dates up to 2 days into the future (varies by currency pairs). Longer tenors up to 180 days (varies by currency pair) are possible with our FX forwards product for Australian or Hong Kong customers, but additional regulatory restrictions and application/review process may apply. Please confirm the acceptable value dates by currency pair with your Account Manager. Since all transfer items within a batch are scheduled to a single transfer date, you may get validation errors for transfer items due to invalid transfer dates.

For [batch transfers with approval flows](https://www.airwallex.com/docs/payouts/batch-transfers/manage-batch-transfers/manage-approvals-for-batch-transfers.md), the `transfer_date` will be updated if it was approved after the original specified date; at which point the batch transfer status transitions to `SCHEDULED` and `transfer_date` is fixed.

In the response, you will see the batch transfer status is `DRAFTING`. Next, you can add transfer items (**Step 3**) to the batch you just created.

### Example request

```shell
curl -X POST https://api.sandbox.airwallex.com/api/v1/batch_transfers/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "funding_source": {
      "deposit_type": "DIRECT_DEBIT",
      "id": "8365ea88-2946-4877-abe1-e02a1015288d"
    },
    "metadata": {
      "order_id": "0123456789"
    },
    "name": "batch-name",
    "remarks": "Any information",
    "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911"
  }'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
  "funding": {
    "deposit_type": "DIRECT_DEBIT",
    "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",
    "status": "SCHEDULED"
  },
  "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "metadata": {
    "order_id": "0123456789"
  },
  "name": "batch-name",
  "remarks": "Any information",
  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911",
  "short_reference_id": "B231018-TMA1RTC",
  "status": "DRAFTING",
  "total_item_count": 0,
  "transfer_date": "2024-01-24",
  "updated_at": "2024-01-24T18:00:02+1100",
  "valid_item_count": 0
}

```

## Step 2: Prepare required beneficiary information

Before adding transfer items to a batch, you will need to prepare the required beneficiary information, which can vary depending on the payout country/currency, transfer method, local clearing system, beneficiary type.

Our [dynamic schema](/api/payouts/beneficiaries/create)  allows you to obtain precise field requirements specific to the intended payout scenario. Refer to the screenshot below on which fields you can specify to generate the schema.

![dynamic schema bene](https://www.airwallex.com/docs/assets/contentful/images.ctfassets.net/c3n7jozh84hr/5z35RtCGBtF7GVPKakmeuw/55d5c811642e4f7790c3ddeb8e15095c/image.png)

The dynamic schema comes in handy when you are checking for a handful of payout scenarios. To obtain our full schema for beneficiaries programmatically in a JSON payload, you can call [Get the API schema](/api/payouts/beneficiaries/generate_beneficiary_api_schemas) to retrieve the required fields and validation rules, and/or [Get the form schema](/api/payouts/beneficiaries/generate_beneficiary_form_schemas) to retrieve suggested specifications on the UI components to render the fields along with the corresponding validation rules. See [Using API and form schemas](https://www.airwallex.com/docs/payouts/beneficiaries/using-api-and-form-schemas.md) to learn more.

Furthermore, beneficiary information can be saved beforehand and used directly when adding transfer items to a batch by specifying the `beneficiary_id` instead (see **Step 3**).

## Step 3: Add items to a batch

After creating a batch transfer, you can call [Add items to a batch](/api/payouts/batch_transfers/add_items) to add transfer items to a batch. You may add a maximum of 100 transfer items at a time, up to a maximum total of 1,000 transfer items per batch.

Each batch transfer item requires the same information required to create a transfer. Please refer to **Step 2** in [Create a transfer](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer.md) for further details. Note that you do not need to specify `transfer_date` for each item as the `transfer_date` is set at the batch transfer level. If your funding source is a Linked Account, please make sure to specify the same `source_currency` for all items in the batch.

### Example request

```shell
curl -X POST https://api.sandbox.airwallex.com/api/v1/batch_transfers/d9af1614-a6a1-4d45-aae7-6858fc6d9ede/add_items \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "items": [
      {
        "beneficiary": {
          "additional_info": {
            "personal_email": "john.walker@gmail.com"
          },
          "address": {
            "city": "Melbourne",
            "country_code": "AU",
            "postcode": "3000",
            "state": "VIC",
            "street_address": "18 William Street"
          },
          "bank_details": {
            "account_currency": "AUD",
            "account_name": "John Walker",
            "account_number": "716978952",
            "account_routing_type1": "bsb",
            "account_routing_value1": "082401",
            "bank_country_code": "AU",
            "local_clearing_system": "BANK_TRANSFER"
          },
          "company_name": "Complete Concrete Pty Ltd",
          "entity_type": "COMPANY"
        },
        "metadata": {
          "order_id": "0123456789"
        },
        "transfer_amount": "100.00",
        "transfer_currency": "AUD",
        "transfer_method": "LOCAL",
        "reason": "travel",
        "reference": "INV-123456",
        "remarks": "",
        "request_id": "722fc382-3025-4da4-b6b4-801b2295eeb0",
        "source_currency": "AUD"
      },
      {
        "beneficiary": {
          "additional_info": {
            "personal_email": "john.walker@gmail.com"
          },
          "address": {
            "city": "Seattle",
            "country_code": "US",
            "postcode": "98104",
            "state": "US-VT",
            "street_address": "412 5th Avenue"
          },
          "bank_details": {
            "account_currency": "USD",
            "account_name": "John Walker",
            "account_number": "50001121",
            "account_routing_type1": "aba",
            "account_routing_value1": "021000021",
            "bank_country_code": "US",
            "local_clearing_system": "ACH"
          },
          "company_name": "Complete Concrete Pty Ltd",
          "entity_type": "COMPANY"
        },
        "metadata": {
          "order_id": "0123456789"
        },
        "transfer_amount": "100.00",
        "transfer_currency": "USD",
        "transfer_method": "LOCAL",
        "reason": "travel",
        "reference": "INV-123456",
        "remarks": "",
        "request_id": "b0212b43-4e77-4d16-ba00-ee7f398506e5",
        "source_currency": "AUD"
      },
      {
        "beneficiary": {
          "additional_info": {
            "personal_email": "john.walker@gmail.com"
          },
          "address": {
            "city": "Seattle",
            "country_code": "US",
            "postcode": "98104",
            "state": "US-VT",
            "street_address": "412 5th Avenue"
          },
          "bank_details": {
            "account_currency": "USD",
            "account_name": "John Walker",
            "account_number": "50001121",
            "account_routing_type1": "aba",
            "account_routing_value1": "021000021",
            "bank_country_code": "US",
            "local_clearing_system": "ACH"
          },
          "company_name": "Complete Concrete Pty Ltd",
          "entity_type": "COMPANY"
        },
        "metadata": {
          "order_id": "0123456789"
        },
        "transfer_amount": "100.00",
        "transfer_currency": "USD",
        "transfer_method": "LOCAL",
        "reason": "travel",
        "reference": "INV-123456",
        "remarks": "",
        "request_id": "40d90756-c0f1-45f7-a02e-0023b648fcf0",
        "source_currency": "AUD"
      },
      {
        "beneficiary": {
          "additional_info": {
            "personal_email": "john.walker@gmail.com"
          },
          "address": {
            "city": "Seattle",
            "country_code": "US",
            "postcode": "98104",
            "state": "xxxxx",
            "street_address": "412 5th Avenue"
          },
          "bank_details": {
            "account_currency": "USD",
            "account_name": "John Walker",
            "account_number": "50001121",
            "account_routing_type1": "aba",
            "account_routing_value1": "021000021",
            "bank_country_code": "US",
            "local_clearing_system": "ACH"
          },
          "company_name": "Complete Concrete Pty Ltd",
          "entity_type": "COMPANY"
        },
        "metadata": {
          "order_id": "0123456789"
        },
        "transfer_amount": "100.00",
        "transfer_currency": "USD",
        "transfer_method": "LOCAL",
        "reason": "travel",
        "reference": "INV-123456",
        "remarks": "",
        "request_id": "20883ea8-ce1c-4058-a4f7-daa42d305bae",
        "source_currency": "AUD"
      }
    ]
  }'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
  "funding": {
    "deposit_type": "DIRECT_DEBIT",
    "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",
    "status": "SCHEDULED"
  },
  "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "metadata": {
    "order_id": "0123456789"
  },
  "name": "batch-name",
  "remarks": "Any information",
  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911",
  "short_reference_id": "B231018-TMA1RTC",
  "status": "DRAFTING",
  "total_item_count": 4,
  "transfer_date": "2024-01-24",
  "updated_at": "2024-01-24T18:00:02+1100",
  "valid_item_count": 3
}
```

### Total and valid item count

Within the response, there are two item counts to confirm the number of transfer items added to the batch:

- `total_item_count`: the total number of items in the batch.
- `valid_item_count`: the number of items that passed our validation schema in the batch.

If the two item counts equal each other, then all transfer items are valid and you can either get a quote for this batch (**Step 4**) or submit the batch (**Step 7**) directly.

If `valid_item_count` is less than `total_item_count`, you can still quote and submit valid items in the batch; alternatively, you can preview all items within the batch (**Step 5**) to identify the invalid items and delete items (**Step 6**) before submitting the batch (**Step 7**).

## Step 4: Quote a batch transfer (optional)

After adding valid transfer items to the batch, you can call [Quote a batch transfer](/api/payouts/batch_transfers/quote) to get quotes to lock the conversion rates for valid items in the batch. Please note that this is not a required step.

- If you have quoted before submitting the batch. You must always ensure to submit before the quotes expire; otherwise, you will receive a `quote_expired` error. In that case, you can call quote a batch transfer to obtain a new quote and submit the batch again;
- If you have not quoted before submitting the batch, all transfer items will be quoted automatically upon submission and you can see the quote details in the response.

In the request, you can specify a customised quote `validity`. The value will default to MIN\_1 if not specified.

In the response, you will see a `quote_summary` with the following useful parameters:

- `expires_at`: The expiration time of the quotes
- `last_quoted_at`: The time this batch transfer last quoted
- `quotes`: Details of each quote based on currency pairs
- `validity`: Quote validity period in the request

For [batch transfers with approval flows](https://www.airwallex.com/docs/payouts/batch-transfers/manage-batch-transfers/manage-approvals-for-batch-transfers.md), quotes will be updated if the batch transfer is approved after the quote expires; at which point the batch transfer status transitions to `SCHEDULED`, and quotes are fixed.

### Example request

```shell
curl -X POST https://api.sandbox.airwallex.com/api/v1/batch_transfers/d9af1614-a6a1-4d45-aae7-6858fc6d9ede/quote \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "validity": "MIN_15"
  }'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
  "funding": {
    "deposit_type": "DIRECT_DEBIT",
    "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",
    "status": "SCHEDULED"
  },
  "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "metadata": {
    "order_id": "0123456789"
  },
  "name": "batch-name",
 "quote_summary": {
  "expires_at": "2024-01-24T18:00:02+0000",
  "last_quoted_at": "2024-01-24T18:03:02+0000",
  "quotes": [
    {
      "amount_beneficiary_receives": 100.0,
      "amount_payer_pays": 100.0,
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "AUD",
      "source_currency": "AUD"
    },
    {
      "amount_beneficiary_receives": 200.0,
      "amount_payer_pays": 308.44,
      "client_rate": 0.648414,
      "currency_pair": "AUDUSD",
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "USD",
      "source_currency": "AUD"
     }
  ],
    "validity": "MIN_15"
 },
  "remarks": "Any information",
  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911",
  "short_reference_id": "B231018-TMA1RTC",
  "status": "DRAFTING",
  "total_item_count": 4,
  "transfer_date": "2024-01-24",
  "updated_at": "2024-01-24T18:00:02+1100",
  "valid_item_count": 3
}
```

## Step 5: List all items within a batch (optional)

Call [List all items within a batch](/api/payouts/batch_transfers/items) to preview all items added to the batch transfer. You can call this endpoint at any time, before or after submitting the batch. Please note that this is not a required step.

### Example request

```shell
curl -G https://api.sandbox.airwallex.com/api/v1/batch_transfers/d9af1614-a6a1-4d45-aae7-6858fc6d9ede/itemspage_size=1000&page=YWZ0ZXI9ZjY0MjZkYzctYzcxMi00YjllLThlYzQtZTVmM2YzOTQwZTBk \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
    "items": [
        {
            "id": "461c6d8a-ff3b-4e86-9a4b-3a46494ccd48",
            "request_id": "40d90756-c0f1-45f7-a02e-0023b648fcf0",
            "status": "VALIDATED",
            "transfer_draft": {
                "amount_beneficiary_receives": 100.0,
                "amount_payer_pays": 154.22,
                "beneficiary": {
                    "additional_info": {
                        "personal_email": "john.walker@gmail.com"
                    },
                    "address": {
                        "city": "Seattle",
                        "country_code": "US",
                        "postcode": "98104",
                        "state": "US-VT",
                        "street_address": "412 5th Avenue"
                    },
                    "bank_details": {
                        "account_currency": "USD",
                        "account_name": "John Walker",
                        "account_number": "50001121",
                        "account_routing_type1": "aba",
                        "account_routing_value1": "021000021",
                        "bank_country_code": "US",
                        "bank_name": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
                        "local_clearing_system": "ACH"
                    },
                    "company_name": "Complete Concrete Pty Ltd",
                    "entity_type": "COMPANY"
                },
                "fee_amount": 0,
                "fee_currency": "AUD",
                "fee_paid_by": "PAYER",
                "metadata": {
                    "order_id": "0123456789"
                },
                "payer": {
                    "additional_info": {
                        "business_incorporation_date": "1986-04-22",
                        "business_registration_number": "CN - 730-58-1527",
                        "business_registration_type": "COMPANY"
                    },
                    "address": {
                        "city": "Shanghai",
                        "country_code": "AU",
                        "postcode": "SH-09090",
                        "state": "SH",
                        "street_address": "Shanghai St, Shanghai St"
                    },
                    "company_name": "Stokes, Gerhold and Mayer",
                    "entity_type": "COMPANY"
                },
                "transfer_amount": 100.0,
                "transfer_currency": "USD",
                "transfer_method": "LOCAL",
                "reason": "travel",
                "reference": "INV-123456",
                "request_id": "40d90756-c0f1-45f7-a02e-0023b648fcf0",
                "short_reference_id": "P240320-MEX719O",
                "source_amount": 154.22,
                "source_currency": "AUD"
            },
            "updated_at": "2024-01-24T18:00:02+0000"
        },
        {
            "id": "247fb034-533e-48f0-b434-72fa3c2619ac",
            "request_id": "b0212b43-4e77-4d16-ba00-ee7f398506e5",
            "status": "VALIDATED",
            "transfer_draft": {
                "amount_beneficiary_receives": 100.0,
                "amount_payer_pays": 154.22,
                "beneficiary": {
                    "additional_info": {
                        "personal_email": "john.walker@gmail.com"
                    },
                    "address": {
                        "city": "Seattle",
                        "country_code": "US",
                        "postcode": "98104",
                        "state": "US-VT",
                        "street_address": "412 5th Avenue"
                    },
                    "bank_details": {
                        "account_currency": "USD",
                        "account_name": "John Walker",
                        "account_number": "50001121",
                        "account_routing_type1": "aba",
                        "account_routing_value1": "021000021",
                        "bank_country_code": "US",
                        "bank_name": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
                        "local_clearing_system": "ACH"
                    },
                    "company_name": "Complete Concrete Pty Ltd",
                    "entity_type": "COMPANY"
                },
                "fee_amount": 0,
                "fee_currency": "AUD",
                "fee_paid_by": "PAYER",
                "metadata": {
                    "order_id": "0123456789"
                },
                "payer": {
                    "additional_info": {
                        "business_incorporation_date": "1986-04-22",
                        "business_registration_number": "CN - 730-58-1527",
                        "business_registration_type": "COMPANY"
                    },
                    "address": {
                        "city": "Shanghai",
                        "country_code": "AU",
                        "postcode": "SH-09090",
                        "state": "SH",
                        "street_address": "Shanghai St, Shanghai St"
                    },
                    "company_name": "Stokes, Gerhold and Mayer",
                    "entity_type": "COMPANY"
                },
                "transfer_amount": 100.0,
                "transfer_currency": "USD",
                "transfer_method": "LOCAL",
                "reason": "travel",
                "reference": "INV-123456",
                "request_id": "b0212b43-4e77-4d16-ba00-ee7f398506e5",
                "short_reference_id": "P240320-BTAUJ0F",
                "source_amount": 154.22,
                "source_currency": "AUD"
            },
            "updated_at": "2024-01-24T18:00:02+0000"
        },
        {
            "id": "3372184b-1d00-4a9f-9231-d04d22da439d",
            "request_id": "722fc382-3025-4da4-b6b4-801b2295eeb0",
            "status": "VALIDATED",
            "transfer_draft": {
                "amount_beneficiary_receives": 100.0,
                "amount_payer_pays": 100.0,
                "beneficiary": {
                    "additional_info": {
                        "personal_email": "john.walker@gmail.com"
                    },
                    "address": {
                        "city": "Melbourne",
                        "country_code": "AU",
                        "postcode": "3000",
                        "state": "VIC",
                        "street_address": "18 William Street"
                    },
                    "bank_details": {
                        "account_currency": "AUD",
                        "account_name": "John Walker",
                        "account_number": "716978952",
                        "account_routing_type1": "bsb",
                        "account_routing_value1": "082401",
                        "bank_country_code": "AU",
                        "bank_name": "National Australia Bank Limited",
                        "local_clearing_system": "BANK_TRANSFER"
                    },
                    "company_name": "Complete Concrete Pty Ltd",
                    "entity_type": "COMPANY"
                },
                "fee_amount": 0,
                "fee_currency": "AUD",
                "fee_paid_by": "PAYER",
                "metadata": {
                    "order_id": "0123456789"
                },
                "payer": {
                    "additional_info": {
                        "business_incorporation_date": "1986-04-22",
                        "business_registration_number": "CN - 730-58-1527",
                        "business_registration_type": "COMPANY"
                    },
                    "address": {
                        "city": "Shanghai",
                        "country_code": "AU",
                        "postcode": "SH-09090",
                        "state": "SH",
                        "street_address": "Shanghai St, Shanghai St"
                    },
                    "company_name": "Stokes, Gerhold and Mayer",
                    "entity_type": "COMPANY"
                },
                "transfer_amount": 100.0,
                "transfer_currency": "AUD",
                "transfer_method": "LOCAL",
                "reason": "travel",
                "reference": "INV-123456",
                "request_id": "722fc382-3025-4da4-b6b4-801b2295eeb0",
                "short_reference_id": "P240320-IVLGVL2",
                "source_amount": 100.0,
                "source_currency": "AUD"
            },
            "updated_at": "2024-01-24T18:00:02+0000"
        }
    ],
    "page_before": "YmVmb3JlPTg0ZjVmZTUzLWFkZTYtNGRiMS05Y2M1LWI4OTFiZjhkYmU1Mw=="
}
```

Details of each transfer item in the batch are returned in the response. Please find below further considerations on some parameters within the `items` array:

- `id`: System generated ID for each item in the batch, which can be used to delete items (**Step 6**).
- `Errors`: If the batch item status is `VALIDATION_FAILED` or `BOOKING_FAILED`. See [Batch transfer item errors](https://www.airwallex.com/docs/payouts/errors/batch-transfer-error-codes#batch-transfer-item-errors.md) for detailed descriptions of each error code.
- `status`: The status for each batch item, which can be one of `VALIDATION_FAILED`, `VALIDATED`, `BOOKING`, `BOOKED`, `BOOKING_FAILED`. See [Batch transfer item statuses](https://www.airwallex.com/docs/payouts/batch-transfers/create-a-batch-transfer/batch-transfer-statuses#batch-transfer-item-statuses.md) for detailed descriptions of each status.
- `transfer_draft`: After obtaining a quote, you can preview the draft details of each transfer item before the batch transfer is `BOOKED`; after which this parameter is no longer available and you should call [Get transfer by ID](/api/payouts/transfers/retrieve) with `transfer_id` to retrieve transfer details.
- `transfer_id`: System generated ID for each `BOOKED` item in the batch, which can be used to retrieve transfer details by calling [Get transfer by ID](/api/payouts/transfers/retrieve).

## Step 6: Delete items within a batch (optional)

Before submitting a batch transfer, i.e. the batch transfer status is `DRAFTING`, you can call [Delete items within a batch](/api/payouts/batch_transfers/delete_items) with `item_ids` to delete invalid or wrong items in the batch. Please note that this is not a required step.

### Example request

```shell
curl -X POST https://api.sandbox.airwallex.com/api/v1/batch_transfers/d9af1614-a6a1-4d45-aae7-6858fc6d9ede/delete_items \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "item_ids": [
      "84f5fe53-ade6-4db1-9cc5-b891bf8dbe53"
    ]
  }'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
  "funding": {
    "deposit_type": "DIRECT_DEBIT",
    "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",
    "status": "SCHEDULED"
  },
  "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "metadata": {
    "order_id": "0123456789"
  },
  "name": "batch-name",
 "quote_summary": {
  "expires_at": "2024-01-24T18:00:02+0000",
  "last_quoted_at": "2024-01-24T18:03:02+0000",
  "quotes": [
    {
      "amount_beneficiary_receives": 100.0,
      "amount_payer_pays": 100.0,
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "AUD",
      "source_currency": "AUD"
    },
    {
      "amount_beneficiary_receives": 200.0,
      "amount_payer_pays": 308.44,
      "client_rate": 0.648414,
      "currency_pair": "AUDUSD",
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "USD",
      "source_currency": "AUD"
     }
  ],
    "validity": "MIN_15"
 },
  "remarks": "Any information",
  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911",
  "short_reference_id": "B231018-TMA1RTC",
  "status": "DRAFTING",
  "total_item_count": 3,
  "transfer_date": "2024-01-24",
  "updated_at": "2024-01-24T18:00:02+1100",
  "valid_item_count": 3
}
```

## Step 7: Submit a batch transfer

Once you have added valid items to the batch transfer, you can call [Submit a batch transfer](/api/payouts/batch_transfers/submit) to submit the batch.

- If no approval is required, this batch will transition to `SCHEDULED` status and will be processed by Airwallex accordingly.
- If approval is required, this batch will transition to `IN_APPROVAL` status.

In the response, you will see a `funding` object contains the following funding information:

- `deposit_type`: If specified when creating the batch, the value can be `DIRECT_DEBIT` or `FASTER_DIRECT_DEBIT`.
- `failure_reason`: If there is an error with the funding source, a failure reason will be returned. See [Batch transfer direct debit deposit errors (asynchronous)](https://www.airwallex.com/docs/payouts/errors/batch-transfer-error-codes#direct-debit-deposit-errors-asynchronous.md) for details.
- `funding_source_id`: The unique ID of your Linked Account if funded by `DIRECT_DEBIT` or `FASTER_DIRECT_DEBIT`.
- `status`: The funding status of this batch transfer. Please see details in [Funding Statuses](https://www.airwallex.com/docs/payouts/batch-transfers/create-a-batch-transfer/batch-transfer-statuses#funding-statuses.md).

After submitting the batch transfer, please ensure sufficient balance is available in your Wallet or Linked Account to cover the batch transfer amount (including fees). Once the batch is successfully funded, the system will start to book single transfers, which can be retrieved by calling [Get transfer by ID](/api/payouts/transfers/retrieve). See [Transfer statuses](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer/transfer-statuses.md) for further details of each transfer item.

### Example request

```shell
curl -X POST https://api.sandbox.airwallex.com/api/v1/batch_transfers/d9af1614-a6a1-4d45-aae7-6858fc6d9ede/submit \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
```

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the `x-on-behalf-of` header.

### Example response

```json
{
  "funding": {
    "deposit_type": "DIRECT_DEBIT",
    "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",
    "status": "PROCESSING"
  },
  "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "metadata": {
    "order_id": "0123456789"
  },
  "name": "batch-name",
 "quote_summary": {
  "expires_at": "2024-01-24T18:00:02+0000",
  "last_quoted_at": "2024-01-24T18:03:02+0000",
  "quotes": [
    {
      "amount_beneficiary_receives": 100.0,
      "amount_payer_pays": 100.0,
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "AUD",
      "source_currency": "AUD"
    },
    {
      "amount_beneficiary_receives": 200.0,
      "amount_payer_pays": 308.44,
      "client_rate": 0.648414,
      "currency_pair": "AUDUSD",
      "fee_amount": 0,
      "fee_currency": "AUD",
      "transfer_currency": "USD",
      "source_currency": "AUD"
     }
  ],
    "validity": "MIN_15"
 },
  "remarks": "Any information",
  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d911",
  "short_reference_id": "B231018-TMA1RTC",
  "status": "SCHEDULED",
  "total_item_count": 3,
  "transfer_date": "2024-01-24",
  "updated_at": "2024-01-24T18:00:02+1100",
  "valid_item_count": 3
}
```

### Fund deduction

*Note: Applicable to batch transfers using Wallet as the funding source only.*

Generally under the **pre-funding workflow**, funds will be immediately deducted from the Wallet when batch transfers are submitted (including future dated batch transfers). If a batch transfer was initially [created and submitted for approval](https://www.airwallex.com/docs/payouts/batch-transfers/manage-batch-transfers/manage-approvals-for-batch-transfers.md), funds will be deducted from the Wallet when the status of the batch transfer transitions to `SCHEDULED`. Please ensure that you have sufficient balance in your Wallet when creating batch transfers.

Alternatively under the **post-funding workflow**, certain customers without sufficient balance are permitted to create batch transfers in advance. Funds will be deducted from the Wallet on transfer date from 9 AM, on a first-in first-out basis based on the earliest `transfer_date`, and the earliest `created_at` time. Funding will be retried every 30 minutes if wallet balance is insufficient.

To learn more about fund deduction models, please see [Funding and Settlement Models](https://www.airwallex.com/docs/transactional-fx/funding-and-settlement-models.md).

### Batch transfer fee

The fee component of a batch transfer item (similar to a transfer) is calculated by Airwallex and communicated back via `fee_currency` and `fee_amount` in the API response, while `amount_payer_pays` and `amount_beneficiary_receives` represent the actual amounts that you will pay and the recipient will receive respectively (with fees applied). If a batch transfer was initially [created and submitted for approval](https://www.airwallex.com/docs/payouts/transfers/manage-transfers/manage-approvals-for-transfers.md), `fee_amount`, `amount_payer_pays` and `amount_beneficiary_receives` for each batch item are tentative based on the exchange rate at the time of creation until the batch transfer status changes to `SCHEDULED`, at which point the exchange rate is confirmed.

The batch transfer fee is set to be paid by the payer by default, while you can pass on the fees to the beneficiary instead by specifying `BENEFICIARY` for the `fee_paid_by` parameter in your request. See more details in required request information for a batch transfer item.

### Errors

Airwallex uses conventional [HTTP response codes](/api/errors) to indicate the success or failure of an API request.

A HTTP 400 status code indicates an error that has been triggered due to the information provided in the request. See [Batch transfer error codes](https://www.airwallex.com/docs/payouts/errors/batch-transfer-error-codes.md) to learn about all possible errors associated with the HTTP 400 status when creating a batch transfer.