Como confirmar um Pix automaticamente (webhook e txid)

Liberar pedido porque o cliente mandou um print é o caminho mais curto para o golpe do comprovante de Pix falso. A alternativa madura é outra: cada cobrança com identidade própria e confirmação automática quando o dinheiro liquida.

Este texto é o guia conceitual — QR dinâmico, txid, webhook, idempotência e conciliação. Não substitui a página de produto para quem integra API (/api-pix, /desenvolvedores) nem a referência de eventos (/api/webhooks e a doc de webhooks). Aqui você entende o desenho; lá você implementa.

Por que não confiar em comprovante

Comprovante visual é fácil de editar. Pix agendado parece “já pago”. Valor errado passa em conversa corrida. A loja que libera no olho assume o risco inteiro.

A regra operacional é a mesma do post comprovante de Pix falso: só libera com status pago / saldo creditado, de preferência sem humano no meio. O resto deste artigo é como chegar lá.

QR Code estático x dinâmico

O Manual de Padrões para Iniciação do Pix do Banco Central descreve a iniciação por QR Code estático e dinâmico (e o ecossistema está em github.com/bacen/pix-api).

Na prática da loja:

Para vender online com baixa automática, dinâmico é o padrão. Na AbacatePay isso passa pela API Pix (gerar cobrança / QR) e pelo checkout ou link de pagamento quando você não quer montar a tela.

O que é o txid e como liga pagamento ao pedido

Txid (transaction identification) é o identificador da cobrança Pix no arranjo. Ele existe para amarrar o pagamento à cobrança que você criou — e, no seu sistema, ao order_id / external_id do pedido.

Fluxo mental:

1. Seu backend cria o pedido #1234.
2. Você cria a cobrança Pix com referência ao #1234 e recebe o txid (e o QR / copia e cola).
3. O cliente paga.
4. O evento de confirmação traz o txid (e/ou o id da cobrança no gateway).
5. Você marca #1234 como pago — só esse pedido.

Sem txid (ou equivalente), sobra conciliação por valor+horário: frágil quando dois pedidos têm o mesmo preço no mesmo minuto.

Como funciona um webhook

Webhook é um POST HTTP que o gateway envia para a URL que você cadastrou quando algo acontece (pagamento confirmado, cobrança expirada, etc.). Em vez de ficar perguntando “já pagou?” a cada segundo, o seu servidor é avisado.

Boas práticas genéricas (padrão de mercado / arranjo Pix; detalhes de assinatura e retentativa da AbacatePay estão na doc de webhooks e em /api/webhooks):

• Evento — tipo + payload com id da cobrança / txid / status
• Resposta rápida — responda 2xx; processe pesado em fila se precisar
• Reenvio — se sua URL cair, o provedor tenta de novo; prepare-se para duplicata
• Idempotência — o mesmo event_id (ou o mesmo pagamento) processado duas vezes não libera o pedido duas vezes

Pseudocódigo genérico (sem endpoint inventado):

ao receber POST /hooks/pix:
  se assinatura inválida → 401
  se event_id já processado → 200 (idempotente)
  carregar cobrança pelo txid / id
  se status != pago → 200 e ignore
  se pedido já liberado → 200
  liberar pedido + registrar event_id
  responder 200

Quem está montando a stack de integração (SDKs, CLI, modo de teste) começa pela página /desenvolvedores — este post não compete com ela; aponta para ela.

Boas práticas: origem, status e duplicidade

1. Valide a origem do webhook (assinatura / segredo conforme a doc do provedor).
2. Consulte o status da cobrança na API antes de liberar, se o evento for só um aviso.
3. Trate duplicidade com chave única (event id ou “pedido já pago”).
4. Não confie no body sozinho se puder revalidar no servidor.
5. Logue txid, pedido e resultado — auditoria salva suporte e contestação.

Teste o caminho feliz e o reenvio no sandbox / Dev mode.

Integre o Pix com confirmação automática — ou vá direto em /api-pix.

Conciliação: pedido x pagamento x extrato

Três camadas:

1. Pedido no seu ERP/loja (itens, cliente, valor).
2. Pagamento no gateway (cobrança, txid, status pago).
3. Extrato na conta (crédito liquidado).

Em operação saudável, (1) e (2) fecham sozinhos via webhook; (3) fecha no financeiro. Divergência (pago no gateway e sem crédito, ou crédito sem pedido) vira fila de exceção — não liberação no WhatsApp.

MED e golpe: chargeback no Pix / MED.

Testando em sandbox

Antes do Pix real:

1. Crie cobrança no modo de teste.
2. Simule o pagamento.
3. Confirme que o webhook chegou assinado.
4. Reenvie / repita o evento e veja se a idempotência segura.
5. Só então troque a chave de produção.

Passo a passo na AbacatePay: como testar o gateway no sandbox.

Comparando stacks de API? AbacatePay vs Stripe ou AbacatePay vs Asaas.

Checklist anti-golpe

• Cobrança dinâmica por pedido (não chave estática reutilizada para tudo)
• Liberação somente com status pago
• Webhook com validação de origem + idempotência
• Equipe treinada: print não libera
• Runbook para comprovante falso e possível MED

Sem time de engenharia? Dá para começar com /checkout ou /link-de-pagamento e evoluir para a API Pix.

Perguntas frequentes

O que é webhook de Pix?

É a notificação HTTP que o provedor envia ao seu sistema quando o status da cobrança muda (por exemplo, de pendente para pago). Detalhe de implementação: /api/webhooks e docs.

Qual a diferença entre QR Code estático e dinâmico?

Estático reutiliza o mesmo QR; dinâmico é gerado para uma cobrança específica, com valor e identificação próprios. Para e-commerce, dinâmico facilita conciliar pedido e pagamento. Fonte de padrões: Manual de Iniciação do Pix (BCB).

O que é txid?

É o identificador da cobrança Pix no arranjo. Serve para amarrar o pagamento à cobrança — e, no seu sistema, ao pedido.

E se o webhook falhar?

Trate retentativa do provedor, mantenha idempotência e tenha um caminho de consulta de status da cobrança (polling / painel) para não ficar cego se a URL cair. Veja a doc do seu gateway.

Preciso de programador?

Para webhook e API, sim (ou no-code + endpoint). Sem código, use /checkout ou /link-de-pagamento e acompanhe o status no painel — ainda assim, não liberar no print. Stack completa de integração: /desenvolvedores.

Integre o Pix com confirmação automática · produto /pix · API /api-pix.