Pular para o conteúdo principal
Seguir as práticas abaixo ajuda a garantir comportamento previsível, segurança operacional e conformidade com as expectativas do BACEN — especialmente sob volume, instabilidade de rede ou cenários de disputas. Essas recomendações se aplicam a todos os casos de uso do Pix: carteiras digitais, pagamentos a comerciantes, cash-outs, fluxos de QR Code, operações recorrentes e transferências internas.

​
1. Use IDs de transação idempotentes

Sempre envie um transactionId único e imutável criado pelo seu sistema. Trate-o como sua chave de idempotência:
  • Se você retentar uma requisição devido a timeout, reutilize o mesmo ID.
  • Se a primeira tentativa teve sucesso, o Plugin Pix retornará o mesmo resultado.
  • Se a primeira tentativa falhou antes do processamento, a retentativa criará a transação exatamente uma vez.
Isso previne:
  • Lançamentos duplicados no ledger
  • Débitos duplicados
  • Correções operacionais manuais
  • Inconsistências de conciliação
Nunca gere um novo ID durante uma retentativa.

​
2. Confie nos 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 webhook:
  • Exiba o status final ao usuário somente após a confirmação do webhook
  • Persista o status do webhook no seu sistema
  • Trate tanto notificações de sucesso quanto de falha
Aguardar o webhook alinha sua UI à liquidação confirmada pelo SPI, reduzindo disputas e falsos positivos.

​
3. Valide a autenticidade do webhook

Todo webhook inclui uma assinatura HMAC (ex.: X-Signature). Boas práticas:
  • Armazene o segredo em um cofre (vault)
  • Recompute o HMAC usando o corpo bruto da requisição
  • Compare com o header
  • Rejeite e registre incompatibilidades
Isso protege contra:
  • Callbacks falsos
  • Payloads adulterados
  • Requisições não autorizadas atingindo seu endpoint
A segurança de webhooks é um requisito de nível PSP — trate-a como tal.

​
4. Projete para falhas e retentativas

O Pix é instantâneo; a rede ao redor dele não é. Espere falhas em:
  • Conectividade com PSTI / provedor direto
  • Entrega de telecom / SMS (para confirmação de chave)
  • Timeouts de rede
  • Validações internas do ledger
  • Verificações de limites e antifraude (reguladas)
Abordagem recomendada:
  • Implemente políticas claras de retentativa (backoff exponencial, loops controlados)
  • Nunca retente cegamente
  • Exiba mensagens acionáveis ao usuário
  • Registre todas as falhas com IDs de correlação
  • Trate “pendente” como um estado intermediário normal
Uma integração Pix robusta é resiliente por design.

​
5. Monitore transações pendentes e jobs em background

Um Pix pode entrar em PENDING enquanto aguarda:
  • Processamento do provedor
  • Confirmação do SPI
  • Entrega de webhook
  • Ciclos de retentativa
O Plugin Pix executa workers em background para garantir consistência eventual:
  • Retentativa de callbacks
  • Conciliação de estados intermediários
  • Detecção de operações travadas
Suas responsabilidades:
  • Monitore transações pendentes regularmente
  • Configure alertas para tentativas excessivas de retentativa
  • Integre logs, métricas e traces para observabilidade
Pendente ≠ falha, mas pendência prolongada requer investigação.

​
6. Mantenha chaves Pix e dados do cliente sincronizados

Como as chaves estão vinculadas à identidade:
  • Se um usuário mudar de telefone/e-mail → atualize ou remova as chaves Pix associadas
  • Mantenha os registros do CRM alinhados com os dados do DICT
  • Remova chaves desatualizadas para evitar roteamento incorreto
  • Para instituições que usam o DICT: Garanta que portabilidade e reivindicações de propriedade sigam as regras do BACEN
Isso reduz:
  • Pagamentos para destinatários errados
  • Casos de MED devido a chaves incorretas
  • Fricção no suporte
Consistência entre CRM ↔ DICT ↔ Plugin Pix é essencial.

​
7. Respeite as expectativas de SLA e janelas de tempo

A liquidação do Pix ocorre em até 10 segundos, mas SLAs legais também importam. Projete sua UX para respeitar:
  • Tolerâncias máximas do SPI
  • Ajustes de limites noturnos (20:00–06:00)
  • Reduções de limite solicitadas pelo cliente (imediatas)
  • Aumentos de limite solicitados pelo cliente (podem exigir autenticação ou período de espera)
Sempre exiba:
  • “Processando…” enquanto aguarda confirmação
  • Orientação “Tente novamente” para violações de limite
Sua UX deve espelhar o comportamento regulatório real do Pix.

​
8. Implemente conciliação e validação contábil

A conciliação fecha o ciclo entre:
  • Seu sistema
  • O Plugin Pix
  • Liquidação do SPI
  • Lançamentos no ledger (Midaz)
Ciclo de conciliação recomendado:
  • Confirme cada Pix liquidado usando seu log de webhooks
  • Associe cada ID Pix a um lançamento no ledger
  • Compare resumos diários com saídas do provedor/SPB
  • Sinalize qualquer incompatibilidade para revisão manual
Isso reduz ruído operacional e apoia a prontidão para auditoria.

​
9. Teste de ponta a ponta com fluxos realistas

Antes de ir para produção, simule:
  • Cash-in e cash-out
  • Limites de alto valor
  • Chaves inválidas
  • QR Codes expirados
  • Devoluções (entrada + saída)
  • Gatilhos de devolução relacionados ao MED
  • Indisponibilidade de webhook
  • Padrões de timeout e retentativa de API
Também teste cenários de Pix intra-ledger quando ambas as contas existem no Midaz. Seu checklist de validação:
  • Lançamentos corretos no ledger
  • Transições corretas de status do Pix
  • Tratamento adequado de webhooks
  • Aplicação adequada de limites
  • Comportamento contábil adequado

​
10. Prepare suas equipes de suporte e operações

As equipes de suporte devem entender:
  • Prazos do Pix (incluindo regras de limites noturnos)
  • Diferença entre “iniciado”, “pendente”, “concluído”, “devolvido”, “falhou”
  • Como ler E2E IDs
  • Como rastrear problemas do DICT
  • Quando o MED se aplica vs devoluções normais
Fluxos de suporte claros reduzem fricção do usuário e evitam disputas de MED falsas.