1. Use uma chave de pagamento idempotente
No fluxo de pagamento Pix, o
endToEndId do BACEN é a sua chave de idempotência. É um identificador único e imutável de 32 caracteres que você fornece ou que o Pix Lerian gera. Você pode repetir a chamada com segurança apenas quando é dono do valor.
Trate o endToEndId como a sua chave de idempotência:
- Se você repetir uma requisição depois de um timeout, reutilize o mesmo
endToEndId. - Se a primeira tentativa já criou o pagamento, o Pix Lerian repete o pagamento existente.
- Se a primeira tentativa falhou antes do processamento, a nova tentativa cria o pagamento exatamente uma vez.
- Lançamentos duplicados no ledger
- Débitos em duplicidade
- Correções operacionais manuais
- Inconsistências de conciliação
endToEndId para uma nova tentativa.
Para o comportamento de idempotência no nível de header de cada produto Lerian, veja Novas tentativas e idempotência.
2. Conte com os webhooks para o status final da transação
Um
200 OK da API não garante que o Pix foi concluído.
Significa apenas que a requisição entrou no fluxo de orquestração.
O status autoritativo é o do webhook:
- Mostre o status final ao usuário apenas depois da confirmação do webhook
- Persista o status do webhook no seu sistema
- Trate as notificações de sucesso e as de falha
3. Valide a autenticidade do webhook
Cada webhook inclui uma assinatura HMAC (por exemplo,
X-Signature).
Boas práticas:
- Guarde o segredo em um cofre
- Recalcule o HMAC usando o corpo bruto da requisição
- Compare com o header
- Rejeite e registre em log as divergências
- Callbacks falsos
- Payloads adulterados
- Requisições não autorizadas chegando ao seu endpoint
4. Projete para falhas e novas tentativas
O Pix é instantâneo. A rede em volta dele não é. Espere falhas em:
- Conectividade do PSTI / provedor direto
- Entrega de telecom / SMS (para confirmação de chave)
- Timeouts de rede
- Validações internas do ledger
- Verificações de limite e antifraude (reguladas)
- Implemente políticas claras de nova tentativa (backoff exponencial, laços controlados)
- Nunca repita a tentativa às cegas
- Mostre ao usuário mensagens acionáveis
- Registre em log todas as falhas com IDs de correlação
- Trate “pending” como um estado intermediário normal
5. Monitore transações pendentes e jobs em segundo plano
Um Pix pode entrar em PENDING enquanto espera:
- O processamento do provedor
- A confirmação do SPI
- A entrega do webhook
- Os ciclos de nova tentativa
- Repetir callbacks
- Conciliar estados intermediários
- Detectar operações travadas
- Monitorar as transações pendentes com frequência
- Configurar alertas para excesso de novas tentativas
- Integrar logs, métricas e traces para observabilidade
6. Mantenha as chaves Pix e os dados dos clientes sincronizados
Como as chaves estão ligadas à identidade:
- Se um usuário muda de telefone/e-mail → atualize ou remova as chaves Pix associadas
- Mantenha os registros do CRM alinhados aos dados do DICT
- Remova chaves desatualizadas para evitar roteamento errado
- Para instituições que usam o DICT: Garanta que as reivindicações de portabilidade e de posse sigam as regras do BACEN
- Pagamentos a recebedores errados
- Casos de MED por chaves incorretas
- Atrito no suporte
7. Respeite as expectativas de SLA e as janelas de tempo
A liquidação do Pix acontece em até 10 segundos, mas os SLAs legais também contam. Projete sua UX para respeitar:
- As tolerâncias máximas do SPI
- Os ajustes de limite noturno (20:00–06:00)
- Os prazos de redução de limite pedida pelo cliente (imediata)
- Os aumentos de limite pedidos pelo cliente (podem exigir autenticação ou período de espera)
- “Processando…” enquanto a confirmação não chega
- A orientação “Tente de novo” quando o limite é estourado
8. Implemente conciliação e validação contábil
A conciliação fecha o ciclo entre:
- Seu sistema
- Pix Lerian
- A liquidação no SPI
- Os lançamentos no ledger (Midaz)
- Confirme cada Pix liquidado pelo seu log de webhooks
- Case cada ID de Pix com um lançamento no ledger
- Compare os resumos diários com as saídas do provedor/SPB
- Marque qualquer divergência para revisão manual
9. Teste de ponta a ponta com fluxos realistas
Antes de entrar em produção, simule:
- Cash-in e cash-out
- Limites de valor alto
- Chaves inválidas
- QR Codes expirados
- Devoluções (recebidas + enviadas)
- Gatilhos de devolução ligados ao MED
- Indisponibilidade do webhook
- Padrões de timeout e de nova tentativa na API
- Lançamentos corretos no ledger
- Transições corretas de status do Pix
- Tratamento adequado do webhook
- Aplicação adequada dos limites
- Comportamento contábil adequado
10. Prepare seus times de suporte e operações
Recomenda-se que os times de suporte entendam:
- Os prazos do Pix (incluindo as regras de limite noturno)
- A diferença entre “initiated”, “pending”, “completed”, “refunded”, “failed”
- Como ler os E2E IDs
- Como acompanhar problemas do DICT
- Quando se aplica o MED e quando se aplicam as devoluções normais