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 arrivesResponse
The same key and the same bodyThe 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 bodyA 409 error with the rule idempotency_key_reused
The same key while the first request is still runningA 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.

The rule for your checkout code

API v1 · built 2026-11-18 · release f13e6bf

The API reference is built from the server code: it never describes an endpoint that does not exist.