Idempotency
Retry safely — a payment or a refund is never made twice.
Creating a payment, a refund or a void requires an Idempotency-Key
header: a unique value per operation, 1 to 255
visible ASCII characters (a UUID is ideal).
- Retrying with the same key and the same body answers the first result
again, with
Idempotency-Replayed: true. Nothing is created twice. - The same key with another body is refused (
IDEMPOTENCY_CONFLICT). - A key is remembered for 1 day.
So: generate the key when you decide to make the operation, store it with your
order, and reuse it on every retry of that operation — after a timeout, a lost
connection or a 5xx.