Step 1: create a payment batch
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 seperate request, upload payments to the created batch using the /v2/payment-batches/{paymentBatchId}/payments endpoint, then confirm using . Payments can be added by uploading a file CSV or by sending the data in JSON format. A blank template can also be optionally 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 afterward. After the batch is created, you can confirm it using /v2/payment-batches/{paymentBatchId}/confirm to initiate the payment process.
Sample requestRequest structure
curl -i -X POST \
'https://api.equalsmoney.com/v2/payment-batches?accountId=F50091' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'requestid: string' \
-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"
}
}
}
]
}
}'curl -i -X POST \
'https://api.equalsmoney.com/v2/payment-batches?accountId=F50091' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'requestid: string' \
-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"
}
}
}
]
}
}'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
{
"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"
}
}{
"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"
}
}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
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"
}
}
}
]
}'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"
}
}
}
]
}'If your request is successful, you will receive a 202 Accepted response with the following structure:
Sample responseResponse structure
{
"format": "csv",
"status": "accepted",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"format": "string",
"status": "string",
"createdAt": "string",
"updatedAt": "string"
}Use this endpoint optionally to validate if a payment batch is in a state which it can be confirmed.
Sample requestRequest structure
curl -i -X GET \
'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'requestid: string' \curl -i -X GET \
'https://api.equalsmoney.com/v2/payment-batches/{paymentBatchId}/validate?accountId=F50091' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'requestid: string' \If your request is successful, you will receive a 200 OK response with the following structure:
Sample responseResponse 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"
}
}
]
}
}{
"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"
}
}
]
}
}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
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"
}
}'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"
}
}'If your request is successful, you will receive a 200 OK response with the following structure:
Sample responseResponse structure
{
"status": "confirmed"
}{
"status": "string"
}