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.

Statuses with webhook

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

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	The batch external_id provided at creation.
status	string	New batch status.
fund_class_document_number	string	CNPJ of the fund associated with the batch.

Standard webhook structure

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "60.910.091/0001-24"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

---

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"
    },
    "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.

Webhook Body

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "completed",
        "fund_class_document_number": "60.910.091/0001-24"
    },
    "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.

Webhook Body

{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "discarded",
        "fund_class_document_number": "60.910.091/0001-24"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}