> ## 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 > Boas práticas para integrações Pix confiáveis: chaves endToEndId idempotentes, confirmação por webhook, assinaturas HMAC e padrões de nova tentativa e observabilidade. Seguir as práticas abaixo ajuda a garantir comportamento previsível, segurança operacional e conformidade com o que o BACEN espera, principalmente em cenários de volume, instabilidade de rede ou disputa. Essas recomendações valem para todos os casos de uso do Pix: carteiras, pagamentos a estabelecimentos, cash-outs, fluxos de QR Code, operações recorrentes e transferências internas. # 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. Isso evita: * Lançamentos duplicados no ledger * Débitos em duplicidade * Correções operacionais manuais * Inconsistências de conciliação **Nunca gere um novo `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](/pt/reference/retries-idempotency). # 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 Esperar o webhook alinha sua UI à **liquidação confirmada pelo SPI**, o que reduz disputas e falsos positivos. # 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 Isso protege contra: * Callbacks falsos * Payloads adulterados * Requisições não autorizadas chegando ao seu endpoint A segurança do webhook é um requisito no nível do PSP. # 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) Abordagem recomendada: * 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 O Pix Lerian roda workers em segundo plano para garantir consistência eventual: * Repetir callbacks * Conciliar estados intermediários * Detectar operações travadas Suas responsabilidades: * Monitorar as transações pendentes com frequência * Configurar alertas para excesso de novas tentativas * Integrar logs, métricas e traces para observabilidade **Pending ≠ falha**, mas um pending prolongado exige investigação. # 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 Isso reduz: * Pagamentos a recebedores errados * Casos de MED por chaves incorretas * Atrito no suporte A consistência entre CRM ↔ DICT ↔ Pix Lerian é essencial. # 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) Mostre sempre: * “Processando…” enquanto a confirmação não chega * A orientação “Tente de novo” quando o limite é estourado Sua UX deve espelhar o comportamento regulatório do Pix. # 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) Ciclo de conciliação recomendado: * 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 Isso reduz o ruído operacional e sustenta a prontidão para auditoria. # 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 Teste também cenários de **Pix dentro do mesmo ledger**, quando as duas contas existem no Midaz. Seu checklist de validação: * 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 Fluxos de suporte claros reduzem o atrito do usuário e evitam disputas de MED indevidas.