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.

Status com webhook

O diagrama abaixo mostra os três status que geram webhooks ao parceiro integrador:

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	O external_id do lote informado na criação.
status	string	Novo status do lote.
fund_class_document_number	string	CNPJ do fundo associado ao lote.

Estrutura padrão do webhook

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

---

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": "60.910.091/0001-24"
    },
    "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.

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

---

Lote Descartado

STATUS

discarded

Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no encerramento do lote, por descarte automático de lotes em aberto pela QI Tech, ou após cancelamento junto à conta caixa. Nenhuma liquidação associada ao lote será processada após este 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"
}