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 set it up.

Payment batch status flow

The batch moves through the statuses below until it closes. Only three generate a webhook: paid, completed and discarded. The others — pending_settlements_insertion, pending_validation, pending_payment, pending_discard and pending_discard_on_cash_account — result from your creation and closure calls, or from internal steps, and do not trigger a notification. To track them, use the batch retrieval.

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

Status	When it happens	Webhook?
pending_settlements_insertion	Batch created, accepting settlements.	No
pending_validation	Batch closed with settlements under review by QI Tech. When the review ends, it moves on to pending_payment by itself.	No
pending_payment	Batch closed, awaiting payment confirmation.	No
paid	Payment confirmed; the settlements start being processed.	Yes
completed	All settlements reached settled or discarded. A settlement in inconsistent_asset holds the batch in paid until it is handled.	Yes
pending_discard / pending_discard_on_cash_account	Requested (or automatic) discard in progress.	No
discarded	Batch discarded.	Yes

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 the 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 BRL. Present once the total is computed, at batch closure — that is, in the paid and completed webhooks.
description	string	Batch description. Present when the batch has a description.

Standard webhook structure

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "11.222.333/0001-81",
        "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": "PAGAMENTOS - 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 DTVM 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 on, the 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": "11.222.333/0001-81",
        "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": "PAGAMENTOS - 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": "11.222.333/0001-81",
        "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": "PAGAMENTOS - 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 discard is completed. This happens:

• at the integrating partner's request at batch closure (batch_status: discarded); or
• by automatic discard, in funds configured for it: batches still in pending_settlements_insertion, pending_validation or pending_payment when the fund's accounting date advances are discarded.

When the batch was already in pending_payment with a computed value, the discard first goes through cancelling the expected entry in the cash account (pending_discard_on_cash_account). No settlement associated with the batch will be processed after this status, and open settlements are discarded without a webhook of their own.

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

Webhook Body

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