Settlement Webhooks
Throughout the settlement processing, the system sends webhooks to notify the integrating partner about status changes for each individual settlement. All webhooks have the type settlement.settlement_status_change and identify the settlement by the settlement_external_id provided at creation.
To receive webhooks, you must have a callback URL configured with QI Tech. Contact integracao.dtvm@qitech.com.br to configure.
Settlement status flow
Each settlement inserted into the batch stays in validated and is only processed after the payment batch reaches paid. From there it reaches one of the two final statuses that generate a webhook: settled or discarded. The validated status does not trigger a notification — it is the result of the settlement insertion call itself.
Reading the diagram: dashed outline = status without a webhook · green = successful completion · red = closed with no financial movement.
Webhook structure
All settlement webhooks follow the same base structure:
| Field | Type | Description |
|---|---|---|
webhook_type | string | Always settlement.settlement_status_change. |
webhook_datetime | string | Event date and time in ISO 8601 format. |
data | array | List with event data. See table below. |
Attributes of each object in data
Conditional fields are echoed directly from what was sent during settlement creation. The payload varies according to the settlement_type and the asset identification method used.
Always present fields:
| Field | Type | Description |
|---|---|---|
payment_batch_external_id | string | The external_id of the payment batch. |
settlement_external_id | string | The external_id of the settlement. |
settlement_status | string | New settlement status. |
settlement_type | string | Settlement type. |
total_value | number | Total settlement amount in BRL. |
fund_class_document_number | string | CNPJ of the associated fund. |
fund_class_key | string | Fund key at QI Tech (UUID). |
asset_key | string | Internal asset key at QI Tech (UUID). |
Asset identification — only one of the fields below will be present, according to what was provided at creation:
| Field | Type | Description |
|---|---|---|
contract_number | string | Contract number. Present if provided at creation. |
asset_external_id | string | Asset external_id in the partner's system. Present if provided at creation. |
Other fields echoed when provided:
| Field | Type | Description |
|---|---|---|
if_code | string | Financial instrument code (B3). Present if provided at settlement creation. |
participant_control_number | string | Participant control number. Present if provided at settlement creation. |
source_document_number | string | CPF or CNPJ of the financial counterparty. Present if provided at batch creation. |
Installment fields — present only for installment-based settlement types (installment_settlement, installment_amortization, installment_fine_payment, gloss):
| Field | Type | Description |
|---|---|---|
installment_number | integer | Installment number. |
installment_maturity_date | string | Installment maturity date in YYYY-MM-DD format. Present when provided at creation. |
installment_external_id | string | Installment external_id. Present when provided at creation. |
{
"data": [
{
"payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"settlement_status": "STATUS",
"settlement_type": "installment_settlement",
"total_value": 130.50,
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"contract_number": "0032226586/NNT",
"installment_number": 3
}
],
"webhook_type": "settlement.settlement_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Events by status
Settlement Completed
Sent when the settlement is successfully processed and the amount has been properly reconciled in the fund's portfolio. This is the final status of a successful settlement — from this moment, the financial movement is effective.
{
"data": [
{
"payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"settlement_status": "settled",
"settlement_type": "installment_settlement",
"total_value": 130.50,
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"contract_number": "0032226586/NNT",
"installment_number": 3
}
],
"webhook_type": "settlement.settlement_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Settlement Discarded
Sent when the settlement is discarded from the processing flow. Discarded settlements do not generate financial movement. There are three situations that cause this status:
- Manual removal before batch closure — the integrating partner removes the settlement via the settlement removal endpoint while the batch is still open.
- Internal discard after review — the QI Tech team discards a settlement that was under manual review (
pending_validation), for example due to data inconsistency. - Rejection — during processing, the fund's portfolio returns a definitive rejection for a settlement with zero value. In these cases, the system determines that reprocessing the settlement would produce the same result and discards it.
{
"data": [
{
"payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"settlement_status": "discarded",
"settlement_type": "installment_settlement",
"total_value": 130.50,
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"contract_number": "0032226586/NNT",
"installment_number": 3
}
],
"webhook_type": "settlement.settlement_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}