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.

Webhook configuration

To receive webhooks, you must have a callback URL configured with QI Tech. Contact integracao.dtvm@qitech.com.br to configure.

Statuses with webhook

The diagram below shows the three statuses that generate webhooks to the integrating partner:

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

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.

Standard webhook structure
{
    "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",
            "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

STATUS

settled

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.

Webhook Body
{
    "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",
            "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

STATUS

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.

Webhook Body
{
    "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",
            "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"
}

Statuses with webhook​

Webhook structure​

Attributes of each object in data​

Events by status​

Settlement Completed​

Settlement Discarded​