> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create payment batch

> Create, validate, and send payment batches of up to 10,000 payments using a single CSV file, or up to 3,000 payments using a single JSON request, thro

# Create payment batches

Create, validate, and send payment batches of up to 10,000 payments using a single CSV file, or up to 3,000 payments using a single JSON request, through the Payment Batch API.

## How it works

To create a payment batch, use the `/v2/payment-batches` endpoint, which allows optional customisation such as name, visibility, and payment details. You can specify payment details while creating the payment batch, or in a separate request, upload payments to the created batch using the `/v2/payment-batches/{paymentBatchId}/payments` endpoint, then confirm using the `/v2/payment-batches/{paymentBatchId}/confirm` enpoint. Payments can be added by uploading a CSV file or by sending the data in JSON format. A blank template can also be downloaded to provide a structured format.

If you specify payment details inline when creating the payment batch, the batch will be locked and you won’t be able to update or upload additional payment details afterwards. After the batch is created, you can confirm it using `/v2/payment-batches/{paymentBatchId}/confirm` to initiate the payment process.

Payments in the batch will use the specified `fundingBudgetId`, if provided. If a `fundingBudgetId` is not specified, the `defaultFundingBudgetId` will be used instead. Orders within the batch are grouped by currency and funding budget. This structure ensures efficient processing and management of payments.

To manage and monitor the lifecycle of a payment batch, a series of webhooks are triggered at key stages, from initial validation and approval to processing, completion, or cancellation. Individual payments within the batch also emit events such as creation, dispatch, or return. These webhooks provide real-time visibility and allow you to automate actions or handle errors efficiently.

For more information about the type of details to provide depending on the country that you're sending money to, see [about preferred recipient details](/pages/payments/about-preferred-recipient-details).

<Warning>
  Validation errors such as insufficient funds or limits, may require recreating the batch, as failed payments won’t be saved.
</Warning>

## Download blank template csv

<Note>
  **GET** `/v2/payment-batch-template`
</Note>

Use this endpoint to download a blank CSV template, which provides a structured format for payment batch details. The template ensures your data aligns with API requirements, simplifying the upload process.

### Request

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/payment-batch-template' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Accept: text/csv' 
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/payment-batch-template' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Accept: text/csv' \
  ```
</CodeGroup>

### Response

If your request is successful, you will receive a `200 OK` response with a text or CSV file for payment details.

## Create a payment batch

<Note>
  **POST** `/v2/payment-batches`
</Note>

### Request

Use this endpoint to create a new payment batch with optional customisation, including name, visibility, and payment details. In sandbox, compliance checks are bypassed, allowing all transactions to pass automatically for faster testing. In production, compliance checks are enforced and may affect payment success.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "John Frank",
      "visible": true,
      "payments": {
        "defaultFundingBudgetId": "771967a7-f0f7-4137-a6bf-494452ba6549",
        "rows": [
          {
            "amount": "10",
            "currencyCode": "USD",
            "fundingBudgetId": "6ee672f6-226f-4a72-8592-0f8dc5284ab1",
            "purposeCode": "BKF",
            "purpose": "Funding my own account",
            "reference": "Paying my savings account",
            "recipient": {
              "id": "8lqccfgmo",
              "defaultReference": "Paying my savings account",
              "type": "individual",
              "name": "John Frank",
              "displayName": "Electrician",
              "subscribedEmails": [
                {
                  "name": "John",
                  "email": "user@example.com"
                }
              ],
              "accountIdentifier": "GB95SPPV23188424911122",
              "bankIdentifier": "SPPVGB2LXXX",
              "intermediaryBankIdentifier": "QBLCCCCV",
              "paymentNetwork": "SWIFT",
              "address": {
                "addressType": "ADDR",
                "streetName": "High St",
                "buildingNumber": "10",
                "buildingName": "Abram",
                "postcode": "SW1A 1AA",
                "city": "London",
                "region": "South West",
                "countryCode": "GB"
              },
              "bankAddress": {
                "countryCode": "GB"
              }
            }
          }
        ]
      }
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "string",
      "visible": boolean,
      "payments": {
        "defaultFundingBudgetId": "string",
        "rows": [
          {
            "amount": "string",
            "currencyCode": "string",
            "fundingBudgetId": "string",
            "purposeCode": "string",
            "purpose": "string",
            "reference": "string",
            "recipient": {
              "id": "string",
              "defaultReference": "string",
              "type": "string",
              "name": "string",
              "displayName": "string",
              "subscribedEmails": [
                {
                  "name": "string",
                  "email": "string"
                }
              ],
              "accountIdentifier": "string",
              "bankIdentifier": "string",
              "intermediaryBankIdentifier": "string",
              "paymentNetwork": "string",
              "address": {
                "addressType": "string",
                "streetName": "string",
                "buildingNumber": "string",
                "buildingName": "string",
                "postcode": "string",
                "city": "string",
                "region": "string",
                "countryCode": "string"
              },
              "bankAddress": {
                "countryCode": "string"
              }
            }
          }
        ]
      }
    }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account to work with.

  Allowable values: An existing `accountId`
</ParamField>

#### Request body schema

<ParamField body="payments" type="object" required>
  Payment details for the batch, including default funding budget and individual payments.
</ParamField>

<ParamField body="payments.defaultFundingBudgetId" type="string" required>
  Default budget to fund payments if not specified for each payment. Example: `771967a7-f0f7-4137-a6bf-494452ba6549`
</ParamField>

<ParamField body="payments.rows" type="array" required>
  Array of all the payments with optional fundingBudgetId. Each payment includes amount, currency, recipient, and purpose details.
</ParamField>

<ParamField body="payments.rows[].amount" type="string" required>
  Payment amount. Example: `100.00`
</ParamField>

<ParamField body="payments.rows[].currencyCode" type="string" required>
  Payment currency (ISO 4217 format). Example: `USD`
</ParamField>

<ParamField body="payments.rows[].recipient" type="object" required>
  Existing recipient (object) or New recipient (object).
</ParamField>

<ParamField body="payments.rows[].recipient.type" type="string" required>
  Type of recipient.

  Allowable values: `individual`, `business`
</ParamField>

<ParamField body="payments.rows[].recipient.name" type="string" required>
  Name of the recipient. Example: `John Doe`
</ParamField>

<ParamField body="payments.rows[].recipient.accountIdentifier" type="string" required>
  This represents the identifier of the recipient's account, such as an Account Number or IBAN. Example: `55555555`
</ParamField>

<ParamField body="payments.rows[].recipient.subscribedEmails.name" type="string" required>
  Name associated with the email subscription. Example: `John Doe`
</ParamField>

<ParamField body="payments.rows[].recipient.subscribedEmails.email" type="string" required>
  Email address for notifications. Example: `johndoe@example.com`
</ParamField>

<ParamField body="payments.rows[].recipient.address" type="object" required>
  Address details of the recipient.
</ParamField>

<ParamField body="payments.rows[].recipient.address.countryCode" type="string" required>
  Country code in ISO 3166-1 alpha-2 format. Example: `US`
</ParamField>

<ParamField body="payments.rows[].recipient.bankAddress" type="object" required>
  Bank account details of the recipient.
</ParamField>

<ParamField body="payments.rows[].recipient.bankAddress.bankCountryCode" type="string" required>
  Country code of the recipient’s bank in ISO 3166-1 alpha-2 format. Example: `GB`
</ParamField>

### Response

If your request is made without payments being specified inline, you'll receive a `201 Created`. This indicates that the batch has been created but still needs payments uploaded to it before confirmation can be done.

Alternatively, you receive a `202 Accepted` response when you specify the payments inline. This means the batch has been sent for validation.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "accountId": "string",
    "name": "string",
    "createdBy": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "person"
    },
    "product": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string"
    },
    "status": "draft",
    "visible": true,
    "visibleAt": "2019-08-24T14:15:22Z",
    "confirmedBy": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "person"
    },
    "confirmedAt": "2019-08-24T14:15:22Z",
    "passedMfaCheckAt": "2019-08-24T14:15:22Z",
    "riskCheckedAt": "2019-08-24T14:15:22Z",
    "ordersSentAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "alerts": [
      {
        "timestamp": "2019-08-24T14:15:22Z",
        "type": "Error",
        "code": "string",
        "message": "string"
      }
    ],
    "ordersSummary": {
      "numberOfOrders": 0,
      "uniqueCurrencyCodes": [
        "USD"
      ]
    },
    "input": {
      "format": "csv",
      "status": "accepted",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "accountId": "string",
    "name": "string",
    "createdBy": {
      "id": "string",
      "type": "string"
    },
    "product": {
      "id": "string",
      "name": "string"
    },
    "status": "string",
    "visible": boolean,
    "visibleAt": "string",
    "confirmedBy": {
      "id": "string",
      "type": "string"
    },
    "confirmedAt": "string",
    "passedMfaCheckAt": "string",
    "riskCheckedAt": "string",
    "ordersSentAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "alerts": [
      {
        "timestamp": "string",
        "type": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "ordersSummary": {
      "numberOfOrders": number,
      "uniqueCurrencyCodes": [
        "string"
      ]
    },
    "input": {
      "format": "string",
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, see API reference.

## Upload payments to a payment batch

<Note>
  **POST** `/v2/payment-batches/{paymentBatchId}/payments`
</Note>

### Request

Use this endpoint to upload payments to a payment batch. Payments can be added by uploading a file (CSV or text) or by sending the data in JSON format.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/payments?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "defaultFundingBudgetId": "771967a7-f0f7-4137-a6bf-494452ba6549",
      "rows": [
        {
          "amount": "10",
          "currencyCode": "USD",
          "fundingBudgetId": "6ee672f6-226f-4a72-8592-0f8dc5284ab1",
          "purposeCode": "BKF",
          "purpose": "Funding my own account",
          "reference": "Paying my savings account",
          "recipient": {
            "id": "8lqccfgmo",
            "defaultReference": "Paying my savings account",
            "type": "individual",
            "name": "John Frank",
            "displayName": "Electrician",
            "subscribedEmails": [
              {
                "name": "John",
                "email": "user@example.com"
              }
            ],
            "accountIdentifier": "GB95SPPV23188424911122",
            "bankIdentifier": "SPPVGB2LXXX",
            "intermediaryBankIdentifier": "QBLCCCCV",
            "paymentNetwork": "SWIFT",
            "address": {
              "addressType": "ADDR",
              "streetName": "High Street",
              "buildingNumber": "10",
              "buildingName": "Abram",
              "postcode": "E16 2YD",
              "city": "London",
              "region": "South East",
              "countryCode": "GB"
            },
            "bankAddress": {
              "countryCode": "GB"
            }
          }
        }
      ]
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/payments?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "defaultFundingBudgetId": "string",
      "rows": [
        {
          "amount": "string",
          "currencyCode": "string",
          "fundingBudgetId": "string",
          "purposeCode": "string",
          "purpose": "string",
          "reference": "string",
          "recipient": {
            "id": "string",
            "defaultReference": "string",
            "type": "individual",
            "name": "string",
            "displayName": "string",
            "subscribedEmails": [
              {
                "name": "string",
                "email": "string"
              }
            ],
            "accountIdentifier": "string",
            "bankIdentifier": "string",
            "intermediaryBankIdentifier": "string",
            "paymentNetwork": "string",
            "address": {
              "addressType": "string",
              "streetName": "string",
              "buildingNumber": "string",
              "buildingName": "string",
              "postcode": "string",
              "city": "string",
              "region": "string",
              "countryCode": "string"
            },
            "bankAddress": {
              "countryCode": "string"
            }
          }
        }
      ]
    }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you're creating a recipient for.

  Allowable values: An existing `accountId`
</ParamField>

#### Path parameters

<ParamField body="paymentBatchId" type="string" required>
  The unique ID of the Payment Batch.

  Allowable values: An existing `paymentBatchId`
</ParamField>

#### Request body schema

<ParamField body="defaultFundingBudgetId" type="string" required>
  The ID of the budget that will fund each payment if one isn't specified per payment.

  Allowable values: An existing `BudgetId`
</ParamField>

<ParamField body="rows" type="array" required>
  Array of all the payments with optional fundingBudgetId. Each payment includes amount, currency, recipient, and purpose details.
</ParamField>

<ParamField body="rows[].amount" type="string" required>
  Payment amount. Example: `100.00`
</ParamField>

<ParamField body="rows[].currencyCode" type="string" required>
  Payment currency (ISO 4217 format). Example: `USD`
</ParamField>

<ParamField body="rows[].recipient" type="object" required>
  Existing recipient (object) or New recipient (object).
</ParamField>

<ParamField body="rows[].recipient.type" type="string" required>
  Type of recipient.

  Allowable values: `individual`, `business`
</ParamField>

<ParamField body="rows[].recipient.name" type="string" required>
  Name of the recipient. Example: `John Doe`
</ParamField>

<ParamField body="rows[].recipient.accountIdentifier" type="string" required>
  This represents the identifier of the recipient's account, such as an Account Number or IBAN. Example: `55555555`
</ParamField>

<ParamField body="rows[].recipient.subscribedEmails.name" type="string" required>
  Name associated with the email subscription. Example: `John Doe`
</ParamField>

<ParamField body="rows[].recipient.subscribedEmails.email" type="string" required>
  Email address for notifications. Example: `johndoe@example.com`
</ParamField>

<ParamField body="rows[].recipient.address" type="object" required>
  Address details of the recipient.
</ParamField>

<ParamField body="rows[].recipient.address.countryCode" type="string" required>
  Country code in ISO 3166-1 alpha-2 format. Example: `US`
</ParamField>

<ParamField body="rows[].recipient.bankAddress" type="object" required>
  Bank account details of the recipient.
</ParamField>

<ParamField body="rows[].recipient.bankAddress.bankCountryCode" type="string" required>
  Country code of the recipient’s bank in ISO 3166-1 alpha-2 format. Example: `GB`
</ParamField>

### Response

If your request is successful, you will receive a `202 Accepted` response with the following structure:

<CodeGroup>
  ```json Sample response theme={null}
  {
    "format": "csv",
    "status": "accepted",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
  ```

  ```json Response structure theme={null}
  {
    "format": "string",
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, see API reference.

## Validate a payment batch

<Note>
  **GET** `/v2/payment-batches/{paymentBatchId}/validate`
</Note>

### Request

Use this endpoint optionally to validate if a payment batch is in a state which it can be confirmed.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you're creating a recipient for.

  Allowable values: An existing `accountId`
</ParamField>

#### Path parameters

<ParamField body="paymentBatchId" type="string" required>
  The unique ID of the Payment Batch.
</ParamField>

### Response

If your request is successful, you will receive a 200 OK response with the following structure:

<CodeGroup>
  ```json Sample response theme={null}
  {
    "isValid": true,
    "paymentBatchStatus": {
      "isValid": true,
      "issues": [
        {
          "code": "150041",
          "message": "string",
          "data": {
            "status": "draft"
          }
        }
      ]
    },
    "ordersBalances": {
      "isValid": true,
      "issues": [
        {
          "code": "150031",
          "message": "string",
          "data": {
            "orderId": "string",
            "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
            "currencyCode": "USD",
            "availableBalance": "string"
          }
        }
      ]
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "isValid": boolean,
    "paymentBatchStatus": {
      "isValid": boolean,
      "issues": [
        {
          "code": "string",
          "message": "string",
          "data": {
            "status": "string"
          }
        }
      ]
    },
    "ordersBalances": {
      "isValid": boolean,
      "issues": [
        {
          "code": "string",
          "message": "string",
          "data": {
            "orderId": "string",
            "budgetId": "string",
            "currencyCode": "string",
            "availableBalance": "string"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, see API reference.

## Testing validation outcomes

Use the following predefined values to simulate various validation scenarios in the sandbox.

### Validation by Bic and Iban

| Test Scenario                                        | Identifier                                       |
| ---------------------------------------------------- | ------------------------------------------------ |
| Successful Validation - SEPA not available           | IBAN: GB68SPPV00000010000001 or BIC: SPPVGB3L001 |
| Caution Validation                                   | IBAN: GB41SPPV00000010000002 or BIC: SPPVGB3L002 |
| Failure Validation                                   | IBAN: GB14SPPV00000010000003 or BIC: SPPVGB3L003 |
| Unsupported CHAPS Network Call - CHAPS not supported | Sort Code: 000000, Account: 00000002             |

### Country Services

| Test Scenario                    | countryCode |
| -------------------------------- | ----------- |
| Successful country services call | GB          |
| Failure country services call    | Non-GB      |

## Confirm a payment batch

<Note>
  **POST** `/v2/payment-batches/{paymentBatchId}/confirm`
</Note>

### Request

Use this endpoint to confirm a payment batch, lock the total sum of payments, and trigger the payment processing workflow. Once a batch is confirmed, it can no longer be edited.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/confirm?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -H 'requestid: string' \
    -d '{
      "mfa": {
        "provider": "fx-mfa-service",
        "sessionId": "string",
        "token": "string"
      }
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/confirm?accountId=F50091' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -H 'requestid: string' \
    -d '{
      "mfa": {
        "provider": "fx-mfa-service",
        "sessionId": "string",
        "token": "string"
      }
    }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you're creating a recipient for.

  Allowable values: An existing `accountId`
</ParamField>

#### Path parameters

<ParamField body="paymentBatchId" type="string" required>
  The unique ID of the Payment Batch.
</ParamField>

#### Request body schema

<ParamField body="mfa.provider" type="string" required>
  Name of the MFA provider.

  Allowable values: An existing `mfa.provider`
</ParamField>

<ParamField body="mfa.sessionId" type="string" required>
  ID of the successful MFA session.

  Allowable values: An existing `mfa.sessionId`
</ParamField>

<ParamField body="mfa.token" type="string" required>
  MFA secret sent to the user's device.

  Allowable values: An existing `mfa.token`
</ParamField>

### Response

If your request is successful, you will receive a 200 OK response with the following structure:

<CodeGroup>
  ```json Sample response theme={null}
  {
    "status": "confirmed"
  }
  ```

  ```json Response structure theme={null}
  {
    "status": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, see API reference.