> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Boas práticas > O Pix é um sistema de pagamento em tempo real, mas uma integração confiável depende de mais do que apenas chamar APIs. 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 Pix Switch 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.** Além disso, o Pix Switch suporta o header HTTP padrão IETF `Idempotency-Key` nos endpoints de criação de pagamento e iniciação de devolução. O middleware faz replay da resposta em cache completa de forma transparente para requisições duplicadas (o Pix Switch não retorna o header `X-Idempotency-Replayed`). Para mais detalhes, consulte [Retentativas e idempotência](/pt/reference/retries-idempotency). # 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 confiável é 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 Pix Switch 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 ↔ Pix Switch é 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.