Webhooks do Lote de Pagamento

Ao longo do fluxo de liquidação, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote de pagamento. Todos os webhooks possuem o tipo settlement.payment_batch_status_change e identificam o lote pelo external_id fornecido na criação.

Configuração de webhooks

Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com integracao.dtvm@qitech.com.br para configurar.

Fluxo de status do lote

O lote passa pelos status abaixo até o encerramento. Só três geram webhook: paid, completed e discarded. Os demais — pending_settlements_insertion, pending_validation, pending_payment, pending_discard e pending_discard_on_cash_account — resultam das suas chamadas de criação e encerramento, ou de etapas internas, e não disparam notificação. Para acompanhá-los, use a consulta de lote.

Como ler o diagrama: contorno tracejado = status sem webhook · azul = webhook de andamento · verde = encerramento com sucesso · vermelho = encerramento sem processamento.

Status	Quando acontece	Webhook?
pending_settlements_insertion	Lote criado, aceitando liquidações.	Não
pending_validation	Lote encerrado com liquidações em revisão pela QI Tech. Ao fim da revisão, segue sozinho para pending_payment.	Não
pending_payment	Lote encerrado, aguardando a confirmação do pagamento.	Não
paid	Pagamento confirmado; as liquidações passam a ser processadas.	Sim
completed	Todas as liquidações chegaram a settled ou discarded. Uma liquidação em inconsistent_asset segura o lote em paid até ser tratada.	Sim
pending_discard / pending_discard_on_cash_account	Descarte solicitado (ou automático) em processamento.	Não
discarded	Lote descartado.	Sim

Estrutura do webhook

Todos os webhooks do lote de pagamento seguem a mesma estrutura:

Campo	Tipo	Descrição
webhook_type	string	Sempre settlement.payment_batch_status_change.
webhook_datetime	string	Data e hora do evento no formato ISO 8601.
data	object	Dados do evento. Veja tabela abaixo.

Atributos de data

Campo	Tipo	Descrição
external_id	string	Identificador do lote. Veja Como o external_id é formado.
status	string	Novo status do lote.
fund_class_document_number	string	CNPJ do fundo associado ao lote.
fund_class_key	string	Chave do fundo na QI Tech (UUID).
payment_batch_key	string	Identificador único do lote gerado pela QI Tech (UUID).
reference_date	string	Data de referência do lote, no formato AAAA-MM-DD.
total_value	number	Valor total do lote em reais. Presente depois que o total é apurado, no encerramento do lote — ou seja, nos webhooks de paid e completed.
description	string	Descrição do lote. Presente quando o lote possui descrição.

Estrutura padrão do webhook

{
    "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"
}

---

Como o external_id é formado

O external_id é a chave de correlação entre o lote na QI DTVM e o seu próprio controle. A origem do valor depende de como o lote foi criado:

Origem do lote	Valor do external_id
Criação via API	Exatamente o external_id que você informou no corpo da requisição.
Arquivo de liquidação enviado via SFTP	O nome do arquivo sem a extensão.

Lotes criados a partir de um arquivo de liquidação

O webhook não traz um campo com o nome do arquivo. Para correlacionar o evento ao arquivo que você enviou, compare o external_id com o nome do arquivo sem a extensão:

Arquivo enviado	external_id do lote
liquidacoes_20260811_001.REM	liquidacoes_20260811_001
CNAB_BAIXAS_liquidacoes_20260811_001.REM	liquidacoes_20260811_001

Como mostra a segunda linha, o prefixo CNAB_BAIXAS_, quando presente, também é removido.

O arquivo de retorno com as inconsistências encontradas no processamento, quando gerado, segue a mesma convenção — retorno_liquidacoes_20260811_001.csv.

---

Eventos por status

Lote Pago

STATUS

paid

Enviado quando o pagamento do lote é confirmado pela QI Tech. A partir desse momento, as liquidações individuais são processadas em sequência e os respectivos webhooks de liquidação são enviados conforme cada uma for concluída.

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

---

Lote Concluído

STATUS

completed

Enviado quando todas as liquidações do lote atingiram um status final (settled ou discarded). Este é o status terminal do lote após a conclusão bem-sucedida do ciclo de liquidação. Ao receber este evento, o parceiro integrador pode considerar o lote integralmente processado.

Para identificar a que lote o evento se refere, use o external_id — veja Como o external_id é formado.

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

---

Lote Descartado

STATUS

discarded

Enviado quando o descarte do lote é concluído. Isso ocorre:

• por solicitação do parceiro integrador no encerramento do lote (batch_status: discarded); ou
• por descarte automático, nos fundos configurados para isso: lotes que continuam em pending_settlements_insertion, pending_validation ou pending_payment quando a data contábil do fundo avança são descartados.

Quando o lote já estava em pending_payment com valor apurado, o descarte passa antes pelo cancelamento da expectativa na conta caixa (pending_discard_on_cash_account). Nenhuma liquidação associada ao lote será processada após este status, e as liquidações abertas são descartadas sem webhook próprio.

Quando o lote é descartado antes do encerramento, o valor total não chega a ser apurado e o campo total_value não vem no 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"
}