Como automatizar a conciliação de pagamentos com API e webhooks

Automatizar a conciliação é casar cada cobrança com o evento de pagamento — e com estornos ou disputas — sem planilha. O caminho mínimo: cobrança com ID externo, webhook (ou API), baixa no ERP/loja e fila de exceções. Na AbacatePay, webhooks assinados e retentativas cobrem a notificação; o matching fica no seu sistema.

Se ainda falta o conceito (pagamentos × bancária, o que entra no cruzamento), comece por o que é conciliação de pagamentos. Aqui o foco é implementação.

Arquitetura mínima

Cinco peças, nessa ordem:

1. Cobrança com referência externa — ao criar Pix, boleto ou checkout, grave o order_id / referência da loja junto da cobrança.
2. Evento — webhook (push) ou consulta pontual à API (rede de segurança).
3. Matching — pelo ID da cobrança e/ou referência externa; nunca só por valor + data.
4. Baixa — marque o pedido como pago, atualize estoque/acesso, registre o líquido esperado.
5. Fila de exceções — valor divergente, evento sem pedido, estorno tardio, disputa.

O gateway entrega o sinal; o ERP aplica a regra. Página de integração: /desenvolvedores.

Webhook × polling

Polling pergunta à API o tempo todo se a cobrança já pagou. Funciona, mas atrasa e escala mal.

Webhook inverte o fluxo: a AbacatePay envia um POST HTTPS quando o evento acontece. Responda 2xx em até 30 segundos; há até 7 retentativas se a entrega falhar. Todas as tentativas do mesmo evento compartilham o mesmo id — use para idempotência.

Conceito completo: o que é webhook de pagamento. Referência: docs de webhooks.

Polling (ou reconsulta) continua útil como rede de segurança quando o endpoint cai — não como caminho principal.

Conciliação por meio

No checkout, Pix, boleto e cartão (sob consulta) compartilham a mesma família de eventos (checkout.* / transparent.*), o que simplifica o matching multi-meio.

Identificadores que evitam ambiguidade

Não case só por valor e horário. Prefira, nesta ordem de confiança:

1. ID da cobrança no gateway
2. Referência externa que você enviou na criação (order_id, SKU interno, etc.)
3. id do evento de webhook — único por entrega lógica; igual em todas as retentativas

Dois pedidos de R$ 49,90 no mesmo minuto quebram qualquer planilha “por valor”. ID estável não.

Edge cases

Deduplicar pelo id e ter um job de reconciliação/reconsulta ficam no seu sistema: o gateway notifica; você casa e trata exceções. Detalhe de retentativas e segurança: docs de webhooks.

Checklist do que pedir ao gateway (e à doc)

Antes de codificar, confirme:

• Webhook HTTPS com retentativa e mesmo id nas retentativas
• Eventos de pagamento, reembolso e disputa por meio
• Campo para referência externa na criação da cobrança
• Consulta à API da cobrança (rede de segurança)
• Ambiente de teste (Dev mode) sem dinheiro real
• Documentação pública dos nomes de evento — na AbacatePay: webhooks

Eventos úteis: checkout.completed / refunded / disputed, transparent.completed / refunded / disputed, subscription.completed / cancelled / renewed, payout.completed / failed, pix_key.received / refunded.

Como fazer com a AbacatePay

1. Cadastre o endpoint em /desenvolvedores / dashboard de webhooks.
2. Crie cobranças pelo checkout, API Pix ou transparente — sempre com referência ao pedido.
3. Processe *.completed para baixa; *.refunded / *.disputed para ajuste.
4. Use o id do evento para não processar duas vezes.
5. Para Pix pontual, o mapa já publicado é confirmar pagamento Pix automaticamente; para QR: como gerar QR Code Pix via API.

Assinaturas e Pix Automático também disparam eventos de renovação — veja assinaturas e pagamento recorrente.

Quer receber eventos de pagamento no seu ERP? Fale com a gente.

Voltar ao conceito

Se alguém do time financeiro ainda pergunta “o que estamos conciliando, afinal?”, o mapa conceitual — pagamentos × bancária, o que entra no cruzamento e sinais de falha — está em o que é conciliação de pagamentos.

Perguntas frequentes

Preciso de ERP para automatizar?

Não necessariamente. Loja, back-office ou um banco de dados próprio bastam, desde que haja matching por ID e fila de exceções. ERP ajuda no fechamento contábil; não é pré-requisito do webhook.

Webhook sozinho resolve a conciliação?

Não. Webhook notifica; a conciliação é a regra que casa o evento com o pedido e trata divergências. Sem matching e sem rede de segurança (reconsulta), sobra buraco quando a URL cai.

Como conciliar cartão se a liquidação não é no mesmo dia da captura?

Separe os momentos: aprovação/captura (operacional) e liquidação no prazo escolhido (caixa). Na AbacatePay o crédito cai no prazo D+1, D+7, D+15 ou D+30; a antecipação automática embute isso na taxa do prazo. Estorno e disputa entram depois, pelos eventos *.refunded / *.disputed.

O que fazer quando o webhook não chega?

Responda rápido quando chegar; se falhar, a AbacatePay retenta. Mesmo assim, rode um job que consulta cobranças ainda pendentes na API e reconcilia o que faltou.

Posso misturar CNAB e API?

Em muitos ERPs legados, sim: o arquivo de retorno cobre um pedaço do boleto bancário, e a API/webhook cobre o gateway. Não misture os dois no mesmo matching sem chave comum (ID da cobrança). Na AbacatePay a automação de conciliação passa por API e webhook.

Pix Automático muda a conciliação?

Muda o ritmo (renovações recorrentes), não o princípio: cada cobrança com ID, cada evento com id, baixa idempotente. Produto: assinaturas / Pix Automático.

Como evitar processar o mesmo pagamento duas vezes?

Guarde o id do evento de webhook. Se ele já existir na sua base, responda 2xx e não repita a baixa. O mesmo id volta em todas as retentativas.

Onde está o conceito de conciliação?

No post principal do par: o que é conciliação de pagamentos.

Quer receber eventos de pagamento no seu ERP? Fale com a gente.

Leia também: o que é conciliação de pagamentos · o que é webhook de pagamento · confirmar Pix automaticamente · gerar QR Pix via API · desenvolvedores · API Pix · checkout