Payment Batch Webhooks

Throughout the settlement flow, the system sends webhooks to notify the integrating partner about payment batch status changes. All webhooks have the type settlement.payment_batch_status_change and identify the batch by the 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.

Payment batch status flow

The batch moves through the statuses below until it closes. Three of them generate a webhook: paid, completed, and discarded. The first two — pending_settlements_insertion and pending_payment — result from your own batch creation and batch closing calls and do not trigger a notification.

Reading the diagram: dashed outline = status without a webhook · blue = progress webhook · green = successful closing · red = closed without processing.

Webhook structure

All payment batch webhooks follow the same structure:

Field	Type	Description
webhook_type	string	Always settlement.payment_batch_status_change.
webhook_datetime	string	Event date and time in ISO 8601 format.
data	object	Event data. See table below.

data attributes

Field	Type	Description
external_id	string	Batch identifier. See How the external_id is formed.
status	string	New batch status.
fund_class_document_number	string	CNPJ of the fund associated with the batch.
fund_class_key	string	Fund key at QI Tech (UUID).
payment_batch_key	string	Unique batch identifier generated by QI Tech (UUID).
reference_date	string	Batch reference date, in YYYY-MM-DD format.
total_value	number	Total batch value in reais. Present after the total is computed, at batch closure — that is, in the paid and completed webhooks.
description	string	Batch description. Present when the batch has one.

Standard webhook structure

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAYMENTS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

---

How the external_id is formed

The external_id is the correlation key between the batch at QI CTVM and your own records. Where the value comes from depends on how the batch was created:

Batch origin	external_id value
Creation via API	Exactly the external_id you provided in the request body.
Settlement file sent via SFTP	The file name without the extension.

Batches created from a settlement file

The webhook does not carry a field with the file name. To correlate the event with the file you sent, compare the external_id with the file name without its extension:

File sent	Batch external_id
liquidacoes_20260811_001.REM	liquidacoes_20260811_001
CNAB_BAIXAS_liquidacoes_20260811_001.REM	liquidacoes_20260811_001

As the second row shows, the CNAB_BAIXAS_ prefix, when present, is also removed.

The return file listing the inconsistencies found during processing, when generated, follows the same convention — retorno_liquidacoes_20260811_001.csv.

---

Events by status

Batch Paid

STATUS

paid

Sent when the batch payment is confirmed by QI Tech. From this point, individual settlements are processed in sequence and the respective settlement webhooks are sent as each one is completed.

Webhook Body

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "paid",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAYMENTS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

---

Batch Completed

STATUS

completed

Sent when all batch settlements have reached a final status (settled or discarded). This is the terminal status of the batch after the successful completion of the settlement cycle. Upon receiving this event, the integrating partner can consider the batch fully processed.

To identify which batch the event refers to, use the external_id — see How the external_id is formed.

Webhook Body

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "completed",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAYMENTS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

---

Batch Discarded

STATUS

discarded

Sent when the batch is discarded. This can occur by explicit request from the integrating partner at batch closure, by automatic discard of open batches by QI Tech, or after cancellation with the cash account. No settlements associated with the batch will be processed after this status.

When the batch is discarded before closure, the total value is never computed and the total_value field does not come in the payload.

Webhook Body

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "discarded",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "description": "PAYMENTS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}