Idempotência
A idempotência é garantida na camada de aplicação (lookup em banco):
| Operação | Onde | Comportamento |
|---|---|---|
Cobrança PIX (POST /payments/merchant/...) | campo idempotencyKey no body | Usado como externalRef da order. Se já existe order com esse externalRef na empresa, a order existente é retornada/recobrada (sem duplicar) |
Saque (POST /withdraws/merchant) | campo idempotencyKey no body | Se já existe saque da sua empresa com essa chave, o registro existente é retornado. A chave é única na plataforma inteira: chave já usada por outra empresa → 409 IDEMPOTENCY_KEY_CONFLICT. Use UUID. Sem resposta do POST? Consulte GET /withdraws/merchant/by-idempotency-key/:key |
Reembolso (POST /payments/transactions/:id/refunds) | header Idempotency-Key (obrigatório) | Ausente → 400 |
Saque cripto para cliente (POST /crypto/payouts) e saque cripto da loja (POST /crypto/withdrawals) | header Idempotency-Key (obrigatório, 8 a 160 caracteres A-Z a-z 0-9 _ -) | Ausente ou inválido → 400 idempotency_key_required. Mesma chave com o mesmo corpo devolve o mesmo saque; com corpo diferente → 409 idempotency_conflict |