Payment Batch Creation

This is the first step of the asset settlement flow. Creating the payment batch reserves a grouping into which the settlements to be processed will be inserted in the following steps.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Create Batches
Assignor	assignor-api	Write

Base URL for each host: Environments (Hosts).

Prerequisites

Before creating a batch, you need the fund_class_key — the unique key of the fund in which the 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.

Attention

Each batch must have a unique external_id per fund.

If an error occurs, resend the request. A duplicate (SET000009) means the batch already exists: look it up through the batch retrieval instead of recreating it. See Retry and duplicates.

Request

ENDPOINT

/settlement/fund_class/{fund_class_key}/payment_batch

METHOD

POST

Request Body

{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - 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 of 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	Batch reference date in YYYY-MM-DD format. When omitted, the current date (Brasília time) applies. It cannot be earlier than the fund's current accounting date.
end_to_end_id	string	optional	End-to-end Pix identifier of the settlement's financial counterparty (32 characters, starting with E).
source_document_number	string	optional	CPF or CNPJ of the settlement's financial counterparty, with punctuation (e.g., 11.222.333/0001-81 or 969.698.790-03). When omitted, it may be filled in with the default document from the fund's settlement configuration.
settlement_expenses	array	optional	Settlement expenses deducted in the batch, at most one per type. See settlement_expenses attributes.

Attention

The account and account_key fields must not be sent together (SET000034). If neither is provided, the settlement will be generated in the fund's main account. The account must belong to the fund or have it as an authorized agent (SET000032).

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.

settlement_expenses attributes

Field	Type	Required	Description
amount	number	required	Expense amount.
expense_type	string	required	bank_account (bank expense) or collection_agent_fee (collection agent fee).
description	string	optional	Expense description. Maximum 255 characters.

Response

STATUS

201

Response Body

{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "payment_batch_automatic_discard": false
    },
    "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 that the batch is ready to receive settlements.
reference_date	string	Batch reference date in YYYY-MM-DD format.
account_key	string	Key of the account associated with the batch (UUID).
settlement_expenses	array	Settlement expenses created, with settlement_expense_key, amount, status, description and type. Present only when provided.

The response also echoes the other fields sent in the body (for example account, source_document_number, end_to_end_id).

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.
accounting_date	string	Current accounting date of the fund, in YYYY-MM-DD format.
payment_batch_automatic_discard	boolean	Indicates whether the fund automatically discards batches left open.

manager attributes

Field	Type	Description
name	string	Manager name.
manager_key	string	Unique manager key (UUID).
document_number	string	Manager CNPJ.

Next steps

After creating the batch, the flow continues with:

1. Settlement insertion — add the settlements (installment payments, amortizations, etc.) to the batch.
2. Batch closure — signal that all settlements have been inserted so that processing can begin.

Errors

Status	Code	When it happens
409	SET000009	A batch with this external_id already exists in the fund. Look it up instead of recreating it.
404	SET000005	The fund_class_key does not exist.
403	SET000028	The fund does not belong to your profile (the fund's manager, a linked consultant or an associated assignor).
400	SET000044	reference_date is earlier than the fund's current accounting date.
404	SET000031	The account provided (account_key or account) was not found.
400	SET000032	The account provided does not belong to the fund.
400	SET000034	account and account_key sent together.
403	SET000085	Escrow account not authorized to operate for this fund.
400	SET000001	source_document_number is not a valid CPF/CNPJ.
400	SET000050 / SET000051	Invalid expense_type, or more than one expense of the same type.
400	QIT000001	Invalid body (missing required field, invalid format or field not accepted).

Authentication, permission and host errors: see API errors.