Payment Batch Creation
This is the first step of the asset settlement flow. Creating the payment batch reserves a grouping where the settlements to be processed will be inserted in subsequent steps.
Before creating a batch, you need the fund_class_key — the unique fund key in which assets will be settled. This key is part of the endpoint used throughout this API:
/settlement/fund_class/{fund_class_key}
For more details about the complete flow, see the introduction page.
Each batch must have a unique external_id per fund. The system will not allow the creation of two batches with the same identifier.
Request
{
"external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"description": "PAYMENTS - ABC - 2025-01-01",
"account": {
"account_number": "123456",
"account_digit": "0",
"account_branch": "0001",
"financial_institution_code": "329"
}
}
Body attributes
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string | required | Unique identifier for this batch in the integrating partner's system. Maximum 50 characters. |
description | string | optional | Settlement batch description. Maximum 255 characters. |
account | object | optional | Data of the account where the settlement will be credited. When not provided, the settlement will be generated in the fund's main account. See Account attributes. |
account_key | string | optional | Key of the account where the settlement will be credited (UUID, 36 characters). Alternative to the account field. |
reference_date | string | optional | Settlement reference date in YYYY-MM-DD format. |
end_to_end_id | string | optional | End-to-end PIX identifier of the financial counterpart of the settlement. Maximum 32 characters. |
source_document_number | string | optional | CPF or CNPJ of the financial counterpart of the settlement, with punctuation (e.g., 12.345.678/0001-90 or 123.456.789-00). |
The account and account_key fields must not be passed simultaneously. If neither is provided, the settlement will be generated in the fund's main account. Account information must refer to an account belonging to the fund.
Account attributes
| Field | Type | Required | Description |
|---|---|---|---|
account_number | string | required | Account number. Maximum 20 characters. |
account_digit | string | required | Account check digit. 1 character. |
account_branch | string | required | Account branch. Maximum 4 characters. |
financial_institution_code | string | required | Financial institution code. Maximum 20 characters. |
Response
{
"external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"description": "PAYMENTS - ABC - 2025-01-01",
"fund_class": {
"name": "CREDIT RIGHTS INVESTMENT FUND",
"manager": {
"name": "EXAMPLE CAPITAL",
"manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
"document_number": "45.585.471/0001-47"
},
"fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
"document_number": "60.910.091/0001-24"
},
"payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
"status": "pending_settlements_insertion",
"reference_date": "2025-01-01",
"account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}
Response attributes
| Field | Type | Description |
|---|---|---|
external_id | string | The same external key provided in the request. |
description | string | Batch description. |
fund_class | object | Data of the fund associated with the batch. See fund_class attributes. |
payment_batch_key | string | Unique batch identifier generated by QI Tech (UUID). |
status | string | Initial batch status. Always returns pending_settlements_insertion, indicating the batch is ready to receive settlements. |
reference_date | string | Settlement reference date in YYYY-MM-DD format. |
account_key | string | Key of the account associated with the batch (UUID). |
fund_class attributes
| Field | Type | Description |
|---|---|---|
name | string | Fund name. |
manager | object | Fund manager data. See manager attributes. |
fund_class_key | string | Unique fund key (UUID). |
document_number | string | Fund CNPJ. |
manager attributes
| Field | Type | Description |
|---|---|---|
name | string | Manager name. |
manager_key | string | Unique manager key (UUID). |
document_number | string | Manager CNPJ. |
Possible errors
Fund not found
The fund_class_key provided in the URL does not match any registered fund. Verify that the key is correct.
{
"title": "Fund Class not Found",
"description": "Fund Class with key {fund_class_key} was not found.",
"translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.",
"code": "SET000005"
}
Duplicate External ID
A batch with the provided external_id already exists. Each batch must have a unique identifier. Generate a new external_id and try again.
{
"title": "Payment batch external id already exists",
"description": "The Payment Batch with external id {payment_batch_external_id} already exists",
"translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe",
"code": "SET000009"
}
Accounting date mismatch
The batch is being created on a date different from the fund's current accounting date. Verify the fund's accounting date and try again.
{
"title": "Bad Request",
"description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}",
"translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}",
"code": "SET000044"
}
Account not found
The account_key provided does not match any registered account. Verify that the key is correct and that the account belongs to the fund.
{
"title": "Account not found",
"description": "The account with key ({account_key}) was not found.",
"translation": "A conta com chave({account_key}) não foi encontrada.",
"code": "SET000009"
}
Next steps
After creating the batch, the flow continues with:
- Settlement insertion — add settlements (installment payments, amortizations, etc.) to the batch.
- Batch closure — signal that all settlements have been inserted so that processing can begin.