Padrões de integração PIX para desenvolvedores

Integrar PIX parece simples no diagrama: gera cobrança, usuário paga, sistema confirma. Na prática, desenvolvedores enfrentam quatro PSPs diferentes no mesmo projeto, webhooks que chegam fora de ordem e reconciliação manual que consome horas toda segunda-feira. Este guia descreve padrões que vimos funcionar em produção — não a especificação completa do Banco Central, mas o que sobrevive ao primeiro mês de tráfego real.

Modelos de cobrança

Existem três entradas principais para receber via PIX em aplicações B2C e B2B: QR estático vinculado a chave, QR dinâmico com valor e identificador de transação, e iniciação via API com txid gerenciado pelo recebedor. A escolha depende menos da stack tecnológica e mais do ciclo de vida do pedido.

QR estático serve para caixas físicos e doações, mas não escala para e-commerce com estoque limitado — não há garantia de unicidade por pedido. QR dinâmico resolve isso: cada cobrança carrega valor, expiração e referência interna. APIs de iniciação permitem fluxos headless, úteis em apps que não exibem QR na tela.

Desenvolvedores iniciantes costumam subestimar o tempo de expiração. Cobranças com validade de quinze minutos exigem UX que permita regenerar QR sem perder o carrinho. Documente o comportamento esperado quando o usuário paga após expiração: estorno automático nem sempre ocorre no mesmo dia.

Webhooks e confirmação assíncrona

A confirmação de pagamento PIX é assíncrona por design. O PSP notifica seu endpoint via webhook quando o SPI liquida a transação. O erro mais comum é tratar o webhook como fonte única de verdade sem idempotência.

Em um marketplace que acompanhamos em Curitiba, o mesmo endToEndId gerou três callbacks em dez segundos por retentativa do gateway. Sem chave de deduplicação, o pedido foi marcado como pago três vezes no ERP.

Padronize uma tabela de eventos recebidos com hash do payload e status de processamento. Responda HTTP 200 apenas após persistir o evento — não antes. PSPs interpretam timeout como falha e reenviam.

Valide assinatura ou certificado do webhook conforme documentação do PSP. Em homologação, muitos ambientes aceitam chamadas sem autenticação; produção não perdoa.

Quatro arquiteturas recorrentes

Mapeamos quatro desenhos que aparecem com frequência em projetos de médio porte:

• Monolito síncrono: checkout chama API do PSP, aguarda confirmação em polling. Funciona em volume baixo, degrada com latência do SPI.
• Fila + worker: webhook grava evento, worker atualiza pedido. Escala bem; exige monitoramento de fila morta.
• Orquestrador de pagamentos: camada interna abstrai múltiplos PSPs. Custo inicial alto, payback em multicanal.
• Reconciliação batch: webhooks para experiência do usuário, extrato DICT ou API de consulta noturna para fechar caixa. Comum em ERPs legados.

Nenhuma arquitetura elimina reconciliação. Mesmo com webhooks confiáveis, divergências aparecem em estornos parciais, devoluções e pagamentos com valor diferente do cobrado.

Reconciliação e suporte

Defina txid ou referência interna visível no comprovante do pagador quando possível. Suporte humano ainda resolve casos que automação não fecha — especialmente quando o cliente paga valor errado ou usa conta de terceiro.

Exporte diariamente extrato do PSP e cruze com pedidos em estado "aguardando pagamento". Ferramentas de BI ajudam, mas uma planilha com endToEndId e ID de pedido já evita a maioria dos buracos no fechamento mensal.

Para marketplaces com split, documente quem é o recebedor final em cada transação. Payloads de webhook variam entre PSPs quanto ao campo de identificação do sub-recebedor.

Checklist antes de produção

Antes de liberar tráfego real, verifique:

• Endpoint de webhook com TLS válido e IP allowlist se exigido pelo PSP
• Idempotência em todos os handlers de confirmação
• Timeout e retry documentados na integração de geração de cobrança
• Fluxo de estorno ou devolução mapeado — mesmo que manual no lançamento
• Alertas para fila de webhooks não processados há mais de cinco minutos

Este texto reflete práticas observadas entre março e maio de 2026. Especificações do Banco Central prevalecem em caso de conflito. Sugestões: [email protected].