Retrying a request
How to retry creating a payment after a dropped connection without creating a second payment.
The response to creating a payment may never arrive: the connection dropped, a timeout expired, a 5xx response came back. The payment may have been created anyway. A retry with the same retry key returns that payment and does not create a second one.
Retry key
The Idempotency-Key header: 1 to 128 visible ASCII characters without spaces. One key per intent to pay.
| What arrives | Response |
|---|---|
| The same key and the same body | The same payment as it is now, code 200 or 201 and the Idempotency-Replayed: true header. No new payment |
| The same key and a different body | A 409 error with the rule idempotency_key_reused |
| The same key while the first request is still running | A 409 error with the rule request_in_progress. Retry in a few seconds |
- The body is compared by content: the order of fields in the JSON does not matter.
- A key works within its environment: test and live keys never collide.
- If the request itself is rejected (an invalid body, an unavailable service, an amount out of limits), no payment is created and the key stays free. Fix the request and send it with the same key.
- If the first request broke off before it created a payment, the key is released after 60 seconds and a retry runs anew.
Without a key
The order number protects against a second payment: reference is unique per merchant within an environment. A retry with the same order number gets a 409 error with the rule payment_reference_exists, and details.paymentId names the payment that was already created. If the creation response never arrived and there was no key, find the payment by the order number: lookup by order number.