Integrar PIX via API significa criar cobranças a partir do seu próprio sistema e reagir ao pagamento sem intervenção humana. O fluxo tem quatro etapas: autenticar, criar a cobrança, receber o evento e reconciliar.
A maior parte dos problemas em produção não está na criação da cobrança — está no que acontece depois dela.
1. Autenticação
Cada requisição deve ser assinada. Em um esquema HMAC-SHA256, o cliente calcula uma assinatura sobre o corpo da requisição usando a chave secreta, e o servidor recalcula para confirmar a origem. Isso evita depender de um token estático que, uma vez vazado, funciona indefinidamente.
- Guarde a chave secreta em variável de ambiente no servidor, nunca no código do cliente.
- Nunca chame a API de pagamentos direto do navegador ou do aplicativo.
- Rotacione credenciais quando alguém com acesso sair da equipe.
2. Criação da cobrança
A cobrança nasce com valor, descrição e — o campo mais importante — a sua referência interna. É esse identificador que amarra a transação ao pedido dentro do seu banco de dados.
Cobrança sem referência própria é cobrança que você vai reconciliar à mão depois.
A resposta traz o QR Code e o código copia e cola. Persista o identificador da cobrança junto ao pedido antes de exibir qualquer coisa para o cliente.
3. Recebimento do webhook
Quer taxas e prazos aplicados ao seu volume?
Preencha nome, e-mail e objetivo. Respondemos com a simulação e o caminho de integração.
Quando o pagamento é confirmado, a plataforma envia um POST para o endpoint que você cadastrou. Esse endpoint precisa ser público, rápido e defensivo.
- Valide a assinatura antes de ler o conteúdo como confiável.
- Responda 2xx rapidamente e processe o trabalho pesado de forma assíncrona; timeout gera reenvio.
- Trate reenvio como normal: o mesmo evento pode chegar mais de uma vez.
- Nunca confie no valor vindo do corpo sem comparar com o valor esperado do pedido.
Idempotência na prática
Antes de liberar o acesso ou disparar a entrega, verifique se aquele pedido já foi marcado como pago. Uma trava simples no banco de dados — status do pedido mais identificador da transação — evita entregar duas vezes por causa de um reenvio.
4. Reconciliação
Webhook é o caminho principal, não o único. Redes falham, servidores caem e deploys derrubam endpoints por alguns minutos. Uma rotina que consulta o status das cobranças pendentes fecha essa lacuna e transforma perda de evento em atraso, não em pedido perdido.
Erros comuns
- Liberar o pedido no retorno da tela do cliente, em vez de esperar o evento do servidor.
- Ignorar a validação de assinatura porque 'só o provedor conhece a URL'.
- Não registrar o payload recebido, o que torna qualquer investigação impossível.
- Tratar erro de rede como falha definitiva, sem nova tentativa.
Resumo
Criar a cobrança leva uma tarde. O que sustenta a operação é o webhook validado, a idempotência e uma rotina de reconciliação — as três coisas que evitam abrir o banco de dados no meio da noite.
Quer ver isso funcionando na sua operação?
Deixe nome, e-mail e objetivo — nosso time apresenta a plataforma e avalia o encaixe com o seu fluxo de cobrança.