Construir um gateway Pix é um projeto de engenharia financeira, não um CRUD. A parte de gerar QR Code é a menor delas; o difícil é garantir que nenhum centavo se perca em falha de rede.
Componentes mínimos
- Camada de API com autenticação por credencial e escopo por loja.
- Reserva de idempotência atômica antes de executar qualquer criação.
- Fila de entrega de webhooks com retentativa e backoff.
- Ledger financeiro imutável como fonte única da verdade.
- Isolamento rígido de dados entre lojas.
- Observabilidade: latência por endpoint, taxa de erro e alertas.
Riscos que costumam ser subestimados
- Concorrência: duas requisições simultâneas com a mesma chave.
- Ordem de eventos: uma confirmação chegando depois de um cancelamento.
- Reprocessamento: o mesmo webhook consumido duas vezes.
- Divergência entre o status exibido no painel e o valor no ledger.
- Vazamento de dados entre lojas por consulta sem filtro de escopo.
Quando não vale a pena construir
Se o objetivo é vender um produto, e não vender infraestrutura de pagamento, usar um gateway existente economiza meses e evita uma classe inteira de bugs financeiros. Construir faz sentido quando o pagamento é o produto.