Idempotency
Retry a request that moves money without doing it twice.
Send an Idempotency-Key header so you can retry a request without charging a customer twice. A retry with the same
key gets the first result back.
Which requests need a key
Send one on every request that moves money:
Choosing a key
Use a new random value for each new payment or reversal. A UUID works well. Use 1 to 255 visible ASCII characters
with no spaces, or the request is refused with 400. Store the key with your own record of the operation, so a retry
sends the same one.
Never put personal data in a key, such as the customer's phone number or email address. Your own order number is fine.
Idempotency-Key: 5f1c1e0a-3b7e-4c8e-9d1a-2f6b8a4c7e11A key you used with a test key is new again with a live key, and a reversal's key only counts for its own payment.
What you get back
| You send | You get |
|---|---|
| A new key | The payment is created: 201. A reversal starts: 202. |
| The same key again | The original result with 200 and the header Idempotent-Replayed: true. Nothing new happens. |
| The same key with a different payment body | 409. Use a new key for a different payment. |
When to retry
Retry with the same key after a network error, a timeout or a 5xx. Do not retry a 4xx unchanged: the request itself
has to change, and a changed request needs a new key.