Idempotência
Processe pagamentos com segurança em redes instáveis.
Os endpoints de criação de pagamento (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:
Idempotency-Key: ORD-2026-12345- Se a transação já existe para aquela chave e empresa, o backend devolve o resultado original sem reprocessar:
HTTP/1.1 200 OK
Idempotent-Replayed: true{
"status": "approved",
"transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
...
}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.
Recomendações
| Situação | Recomendação |
|---|---|
| Timeout na requisição | Reenvie com a mesma Idempotency-Key |
| Nova tentativa de pagamento (cliente) | Gere uma nova Idempotency-Key |
| Formato da chave | Use o ID do pedido do seu sistema (ex: ORD-2026-12345) |
| Ausência do header | O pagamento é processado normalmente, sem proteção contra duplicatas |