Settlement Webhooks
Throughout settlement processing, the system sends webhooks to notify the integrating partner about status changes of 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 set it up. The fund's manager and consultant receive the webhooks for all settlements; the assignor receives only those for settlements of assets it assigned.
Settlement status flow
Not every status change generates a webhook. Only three situations notify: completion (settled) and the outcome of a QI Tech review (validated or discarded). For the other statuses, use the settlement retrieval.
Reading the diagram: dashed outline = status without a webhook · blue = progress webhook · green = successful completion · red = notified discard.
| Status | When it happens | Webhook? |
|---|---|---|
validated | At insertion, when the amount paid is within the tolerance. | No — it is the response of the insertion itself. |
pending_validation | At insertion, when the amount paid differs from the expected amount beyond the tolerance. The settlement awaits review by QI Tech. | No — it is the response of the insertion itself. |
validated (after review) | QI Tech approves a settlement that was in pending_validation. | Yes |
discarded (after review) | QI Tech discards a settlement that was in pending_validation or validated, with the batch still open. | Yes |
waiting_send_to_queue / on_queue | The batch was paid and the settlement is being sent to the fund's portfolio. | No |
settled | The settlement was reconciled in the portfolio. Final success status. | Yes |
inconsistent_asset | The portfolio rejected the payment due to an inconsistency in the asset. QI Tech handles the case and reprocesses it; the batch does not reach completed while any settlement is in this status. | No |
discarded (without notice) | The batch was discarded (open settlements are discarded along with it), or the portfolio definitively rejected a zero-value settlement. | No — when the batch is discarded, the notice is the batch webhook with discarded. |
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 the event data. See the table below. |
Attributes of each object in data
Conditional fields are echoed directly from what was sent at 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). If the settlement affects more than one asset, it carries the first one. |
Asset identification:
| Field | Type | Description |
|---|---|---|
contract_number | string | Contract number. Present if provided at creation; for CCBs and contracts, it is filled in from the portfolio even when not provided. |
asset_external_id | string | Asset external_id in the partner's system. Present if provided at creation; for CCBs and contracts, it is filled in from the portfolio even when not provided. |
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. |
new_maturity_date | string | New maturity date. Present in asset_extension. |
Installment fields — present only for installment-based settlement types (installment_* and 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": "11.222.333/0001-81",
"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 on, 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": "11.222.333/0001-81",
"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 Approved after Review
Sent when QI Tech approves a settlement that was in pending_validation. The settlement proceeds to normal processing when the batch is paid. The payload has the same structure, with settlement_status equal to validated.
Settlement Discarded
Sent when QI Tech discards a settlement after review — for example, a settlement in pending_validation whose amount is not confirmed. Discarded settlements do not generate financial movement.
Discards that happen along with the batch discard, or due to a definitive rejection by the portfolio for zero-value settlements, do not generate this webhook. See the status map.
{
"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": "11.222.333/0001-81",
"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"
}