/ Guides / Payments / Send batch payments / Create payment batches

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.

warning

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

Download blank template csv

Get/v2/payment-batch-template

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

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/payment-batch-template' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Accept: text/csv'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/payment-batch-template' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Accept: text/csv' \

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

Post/v2/payment-batches

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.

Sample requestRequest structure
Copy
Copied
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"
            }
          }
        }
      ]
    }
  }'
Copy
Copied
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"
            }
          }
        }
      ]
    }
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account to work with.

Allowable values:
An existing accountId

Request body schema

Parameter Description
name
string
optional		 Name of the payment batch. Defaults to a generated name if not provided.
visible
boolean
optional		 Determines the payment batch will be returned in the GET and LIST API for other users.
payments
object
required		 Payment details for the batch, including default funding budget and individual payments.
payments.defaultFundingBudgetId
string
required		 Default budget to fund payments if not specified for each payment.

Example: 771967a7-f0f7-4137-a6bf-494452ba6549
payments.rows
array
required		 Array of all the payments with optional fundingBudgetId. Each payment includes amount, currency, recipient, and purpose details.
payments.rows[].amount
string
required		 Payment amount.

Example: 100.00
payments.rows[].fundingBudgetId
string
optional		 Budget ID for the specific payment. If not included, it will default to defaultFundingBudgetId.

Example: 6ee672f6-226f-4a72-8592-0f8dc5284ab1
payments.rows[].purposeCode
string
optional		 Purpose code for the payment. See more details on payment purpose codes guide

Example: BKF
payments.rows[].purpose
string
optional		 Purpose description for the payment.

Example: Invoice Payment
payments.rows[].reference
string
optional		 Reference for the payment.

Example: Payment for Services
payments.rows[].currencyCode
string
required		 Payment currency (ISO 4217 format).

Example: USD
payments.rows[].recipient
object
required		 Existing recipient (object) or New recipient (object).
payments.rows[].recipient.id
string
required if existing recipient		 ID of an existing recipient (if applicable).

Example: 8lqccfgmo
payments.rows[].recipient.defaultReference
string
optional		 Default reference for the recipient.

Example: EXT123
payments.rows[].recipient.type
string
required if new recipient		 Type of recipient.

Allowable values:
individual, business
payments.rows[].recipient.name
string
required if new recipient		 Name of the recipient.

Example: John Doe
payments.rows[].recipient.displayName
string
optional		 Display name for the recipient.

Example: JD Services
payments.rows[].recipient.paymentNetwork
string
optional		 Payment network to use.

Allowable values:
SEPA.INSTANT, SEPA.CREDITTRANSFER, SWIFT, UKFPS, CHAPS, ACH, WIRETRANSFER
payments.rows[].recipient.accountIdentifier
string
required if new recipient		 This represents the identifier of the recipient's account, such as an Account Number or IBAN.

Example: 55555555
payments.rows[].recipient.bankIdentifier
string
optional		 This represents the identifier of the recipient's bank, such as Sort Code, BIC or Routing Number. This field is required if the accountIdentifier provided is not an IBAN.

Example: 123456
payments.rows[].recipient.intermediaryBankIdentifier
string
optional		 Identifier for intermediary bank.

Example: QBLCCCCV
payments.rows[].recipient.subscribedEmails
array
optional		 List of email notifications for payments to this recipient.
payments.rows[].recipient.subscribedEmails.name
string
required		 Name associated with the email subscription.

Example: John Doe
payments.rows[].recipient.subscribedEmails.email
string
required		 Email address for notifications.

Example: johndoe@example.com
payments.rows[].recipient.address
object
required if new recipient		 Address details of the recipient.
payments.rows[].recipient.address.addressType
string
optional		 Type of address.

Allowable values:
ADDR, PBOX, HOME, BIZZ, MLTO, DLVY
payments.rows[].recipient.address.streetName
string
optional		 Street name of the address.

Example: Main St
payments.rows[].recipient.address.buildingNumber
string
optional		 Building number of the address.

Example: 123
payments.rows[].recipient.address.buildingName
string
optional		 Building name of the address.

Example: Abram
payments.rows[].recipient.address.postcode
string
optional		 Postal code of the address.

Example: 10001
payments.rows[].recipient.address.city
string
optional		 City of the address.

Example: New York
payments.rows[].recipient.address.region
string
optional		 Region of the address.

Example: NY
payments.rows[].recipient.address.countryCode
string
required		 Country code in ISO 3166-1 alpha-2 format.

Example: US
payments.rows[].recipient.bankAddress
object
required if new recipient		 Bank account details of the recipient.
payments.rows[].recipient.bankAddress.bankCountryCode
string
required		 Country code of the recipient’s bank in ISO 3166-1 alpha-2 format.

Example: GB

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.

Sample responseResponse structure
Copy
Copied
{
  "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"
  }
}
Copy
Copied
{
  "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"
  }
}

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

Upload payments to a payment batch

Post/v2/payment-batches/{paymentBatchId}/payments

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.

Sample requestRequest structure
Copy
Copied
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"
          }
        }
      }
    ]
  }'
Copy
Copied
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"
          }
        }
      }
    ]
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a recipient for.

Allowable values:
An existing accountId

Path parameters

Parameter Description
paymentBatchId
string
required		 The unique ID of the Payment Batch.

Allowable values:
An existing paymentBatchId

Request body schema

Parameter Description
defaultFundingBudgetId
string
required		 The ID of the budget that will fund each payment if one isn't specified per payment.

Allowable values:
An existing BudgetId
rows
array
required		 Array of all the payments with optional fundingBudgetId. Each payment includes amount, currency, recipient, and purpose details.
rows[].amount
string
required		 Payment amount.

Example: 100.00
rows[].fundingBudgetId
string
optional		 Budget ID for the specific payment. If not included, it will default to defaultFundingBudgetId.

Example: 6ee672f6-226f-4a72-8592-0f8dc5284ab1
rows[].purposeCode
string
optional		 Purpose code for the payment. See more details on payment purpose codes guide

Example: BKF
rows[].purpose
string
optional		 Purpose description for the payment.

Example: Invoice Payment
rows[].reference
string
optional		 Reference for the payment.

Example: Payment for Services
rows[].currencyCode
string
required		 Payment currency (ISO 4217 format).

Example: USD
rows[].recipient
object
required		 Existing recipient (object) or New recipient (object).
rows[].recipient.id
string
required if existing recipient		 ID of an existing recipient (if applicable).

Example: 8lqccfgmo
rows[].recipient.defaultReference
string
optional		 Default reference for the recipient.

Example: EXT123
rows[].recipient.type
string
required if new recipient		 Type of recipient.

Allowable values:
individual, business
rows[].recipient.name
string
required if new recipient		 Name of the recipient.

Example: John Doe
rows[].recipient.displayName
string
optional		 Display name for the recipient.

Example: JD Services
rows[].recipient.paymentNetwork
string
optional		 Payment network to use.

Allowable values:
SEPA.INSTANT, SEPA.CREDITTRANSFER, SWIFT, UKFPS, CHAPS, ACH, WIRETRANSFER
rows[].recipient.accountIdentifier
string
required if new recipient		 This represents the identifier of the recipient's account, such as an Account Number or IBAN.

Example: 55555555
rows[].recipient.bankIdentifier
string
optional		 This represents the identifier of the recipient's bank, such as Sort Code, BIC or Routing Number. This field is required if the accountIdentifier provided is not an IBAN.

Example: 123456
rows[].recipient.intermediaryBankIdentifier
string
optional		 Identifier for intermediary bank.

Example: QBLCCCCV
rows[].recipient.subscribedEmails
array
optional		 List of email notifications for payments to this recipient.
rows[].recipient.subscribedEmails.name
string
required		 Name associated with the email subscription.

Example: John Doe
rows[].recipient.subscribedEmails.email
string
required		 Email address for notifications.

Example: johndoe@example.com
rows[].recipient.address
object
required if new recipient		 Address details of the recipient.
rows[].recipient.address.addressType
string
optional		 Type of address.

Allowable values:
ADDR, PBOX, HOME, BIZZ, MLTO, DLVY
rows[].recipient.address.streetName
string
optional		 Street name of the address.

Example: Main St
rows[].recipient.address.buildingNumber
string
optional		 Building number of the address.

Example: 123
rows[].recipient.address.buildingName
string
optional		 Building name of the address.

Example: Abram
rows[].recipient.address.postcode
string
optional		 Postal code of the address.

Example: 10001
rows[].recipient.address.city
string
optional		 City of the address.

Example: New York
rows[].recipient.address.region
string
optional		 Region of the address.

Example: NY
rows[].recipient.address.countryCode
string
required		 Country code in ISO 3166-1 alpha-2 format.

Example: US
rows[].recipient.bankAddress
object
required if new recipient		 Bank account details of the recipient.
rows[].recipient.bankAddress.bankCountryCode
string
required		 Country code of the recipient’s bank in ISO 3166-1 alpha-2 format.

Example: GB

Response

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

Sample responseResponse structure
Copy
Copied
{
  "format": "csv",
  "status": "accepted",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
Copy
Copied
{
  "format": "string",
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

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

Validate a payment batch

Get/v2/payment-batches/{paymentBatchId}/validate

Request

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

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
  -H 'Authorization: YOUR_API_KEY_HERE' \

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a recipient for.

Allowable values:
An existing accountId

Path parameters

Parameter Description
paymentBatchId
string
required		 The unique ID of the Payment Batch.

Response

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

Sample responseResponse structure
Copy
Copied
{
  "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"
        }
      }
    ]
  }
}
Copy
Copied
{
  "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"
        }
      }
    ]
  }
}

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

Post/v2/payment-batches/{paymentBatchId}/confirm

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.

Sample requestRequest structure
Copy
Copied
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"
    }
  }'
Copy
Copied
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"
    }
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a recipient for.

Allowable values:
An existing accountId

Path parameters

Parameter Description
paymentBatchId
string
required		 The unique ID of the Payment Batch.

Request body schema

Parameter Description
mfa
object
optional		 Object with MFA details.
mfa.provider
string
required		 Name of the MFA provider.

Allowable values:
An existing mfa.provider
mfa.sessionId
string
required		 ID of the successful MFA session.

Allowable values:
An existing mfa.sessionId
mfa.token
string
required		 MFA secret sent to the user's device.

Allowable values:
An existing mfa.token

Response

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

Sample responseResponse structure
Copy
Copied
{
  "status": "confirmed"
}
Copy
Copied
{
  "status": "string"
}

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