> ## 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 de idempotência, 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 *** Em um fluxo de pagamento do Pix Lerian, o header `X-Idempotency` é a sua **chave de idempotência**. Envie um valor novo para cada requisição e reutilize-o apenas para repetir essa requisição. O `endToEndId` do BACEN não é a chave de nova tentativa. Trate o valor de `X-Idempotency` como a sua **chave de idempotência**: * Se você repetir uma requisição depois de um timeout, **reutilize o mesmo valor de `X-Idempotency`**. * Se a primeira tentativa teve sucesso, o Pix Lerian repete a resposta original dela, com o status, por uma hora. A repetição traz o header `X-Idempotency-Replayed: true`. * Se a primeira tentativa falhou com um `5xx`, ou se a hora já passou, leia o estado da operação antes de tentar de novo. * Dentro dessa hora, se você reutilizar o valor com uma requisição diferente, o Pix Lerian a recusa. * Se um reenvio responder `412` (`PIX-0031`) com `Retry-After: 1`, a primeira requisição ainda está em andamento. Espere e reenvie com o mesmo valor. Isso evita: * Lançamentos duplicados no ledger * Débitos em duplicidade * Correções operacionais manuais * Inconsistências de conciliação Você pode fornecer o seu próprio `endToEndId`. Os caracteres 2 a 9, depois do `E` inicial, devem conter o seu ISPB. Em um pagamento por chave ou por QR Code, envie-o ao iniciar a transferência ou omita-o, e o Pix Lerian gera um. A iniciação retorna o valor, e o processamento o reutiliza. Não envie `X-End-To-End-Id` ao processar um pagamento por chave ou por QR Code: o Pix Lerian o recusa. Em um pagamento manual, envie o valor em `X-End-To-End-Id` ao processar a transferência. Para o comportamento de idempotência no nível de header de cada produto Lerian, veja [Novas tentativas e idempotência](https://docs.lerian.studio/pt/reference/retries-idempotency.md). # 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. Confirme o status final por webhook ou por [Get Transfer](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-transfer.md): * 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. Isso 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, mas 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 Mantenha CRM, DICT e Pix Lerian consistentes entre si. # 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.