Skip to main content

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

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. 
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"
            }
          }
        }
      ]
    }
  }'

​
Query parameters

​
accountId
string
required
The ID of the account to work with.Allowable values: An existing accountId

​
Request body schema

​
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[].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.type
string
required
Type of recipient.Allowable values: individual, business
​
payments.rows[].recipient.name
string
required
Name of the recipient. Example: John Doe
​
payments.rows[].recipient.accountIdentifier
string
required
This represents the identifier of the recipient’s account, such as an Account Number or IBAN. Example: 55555555
​
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
Address details of the recipient.
​
payments.rows[].recipient.address.countryCode
string
required
Country code in ISO 3166-1 alpha-2 format. Example: US
​
payments.rows[].recipient.bankAddress
object
required
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. 
{
  "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"
  }
}
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. 
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"
          }
        }
      }
    ]
  }'

​
Query parameters

​
accountId
string
required
The ID of the account that you’re creating a recipient for.Allowable values: An existing accountId

​
Path parameters

​
paymentBatchId
string
required
The unique ID of the Payment Batch.Allowable values: An existing paymentBatchId

​
Request body schema

​
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[].currencyCode
string
required
Payment currency (ISO 4217 format). Example: USD
​
rows[].recipient
object
required
Existing recipient (object) or New recipient (object).
​
rows[].recipient.type
string
required
Type of recipient.Allowable values: individual, business
​
rows[].recipient.name
string
required
Name of the recipient. Example: John Doe
​
rows[].recipient.accountIdentifier
string
required
This represents the identifier of the recipient’s account, such as an Account Number or IBAN. Example: 55555555
​
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
Address details of the recipient.
​
rows[].recipient.address.countryCode
string
required
Country code in ISO 3166-1 alpha-2 format. Example: US
​
rows[].recipient.bankAddress
object
required
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: 
{
  "format": "csv",
  "status": "accepted",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
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. 
curl -i -X GET \
  'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
  -H 'Authorization: YOUR_API_KEY_HERE' \

​
Query parameters

​
accountId
string
required
The ID of the account that you’re creating a recipient for.Allowable values: An existing accountId

​
Path parameters

​
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: 
{
  "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"
        }
      }
    ]
  }
}
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 ScenarioIdentifier
Successful Validation - SEPA not availableIBAN: GB68SPPV00000010000001 or BIC: SPPVGB3L001
Caution ValidationIBAN: GB41SPPV00000010000002 or BIC: SPPVGB3L002
Failure ValidationIBAN: GB14SPPV00000010000003 or BIC: SPPVGB3L003
Unsupported CHAPS Network Call - CHAPS not supportedSort Code: 000000, Account: 00000002

​
Country Services

Test ScenariocountryCode
Successful country services callGB
Failure country services callNon-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. 
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

​
accountId
string
required
The ID of the account that you’re creating a recipient for.Allowable values: An existing accountId

​
Path parameters

​
paymentBatchId
string
required
The unique ID of the Payment Batch.

​
Request body schema

​
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: 
{
  "status": "confirmed"
}
For more detailed information about this request and its response, see API reference.