Integrar Pix é menos sobre escrever código e mais sobre cobrir os caminhos que dão errado. A parte feliz do fluxo costuma ficar pronta na primeira tarde.
Etapas de uma integração
- Criar conta e gerar credencial de teste.
- Criar a primeira cobrança e exibir QR Code e Copia e Cola.
- Expor o endpoint de webhook e validar assinatura.
- Tornar o consumo idempotente e registrar cada evento.
- Tratar expiração, cancelamento e estorno.
- Rodar o fluxo completo em ambiente de teste.
- Trocar a credencial para produção e monitorar.
Erros comuns
- Confiar apenas na tela e não implementar webhook.
- Validar assinatura sobre o JSON já convertido, em vez do corpo bruto.
- Criar cobrança nova a cada carregamento da página.
- Esquecer idempotência e gerar cobrança duplicada em retry.
- Deixar a chave secreta chegar ao front-end.
- Não registrar o identificador da cobrança junto ao pedido.
O que monitorar depois de subir
Taxa de erro por endpoint, latência de criação de cobrança, entregas de webhook com falha e cobranças pendentes há muito tempo. Esses quatro números explicam quase todo incidente.