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

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

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

  ```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' \
    -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"
              }
            }
          }
        ]
      }
    }'
  ```
</CodeGroup>

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>

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>

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>

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' \
    -H 'requestid: string' \
  ```

  ```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' \
    -H 'requestid: string' \
  ```
</CodeGroup>

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>

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>

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>