POST /payments e POST /payments/pix) suportam o header Idempotency-Key. Com ele, reenviar a mesma requisição em caso de timeout ou falha de rede nunca resultará em cobranças duplicadas.
Como funciona
- Gere uma chave única para cada intenção de pagamento — tipicamente o ID do pedido no seu sistema.
- Inclua o header em todas as tentativas:
- Se a transação já existe para aquela chave e empresa, o backend devolve o resultado original sem reprocessar:
Quando
Idempotent-Replayed: true estiver presente no header de resposta, o pagamento não foi processado novamente — você está recebendo o resultado cacheado da primeira tentativa bem-sucedida.Escopo
As chaves de idempotência são escopadas por empresa (company_id). A mesma chave pode ser reutilizada por empresas diferentes sem colisão.