Skip to main content
Every POST under /v1 accepts an Idempotency-Key header, so a client can retry safely after a timeout or network error.
  • Scope. Keys are per merchant and per mode: the same key in test and live mode are different keys.
  • Format. 1–255 characters. Use a fresh random value (for example a UUID) per logical operation.
  • Same request, same key. The original response is replayed with its status code and body, plus the header Idempotent-Replayed: true. “Same request” means the same method, path and query, and the same raw body bytes.
  • Different request, same key. 409 IDEMPOTENCY_CONFLICT.
  • Retry while the first is still running. 409 IDEMPOTENCY_IN_PROGRESS; retry after a short delay.
  • Server errors are not stored. A 5xx response releases the key, so the retry runs the request again.
  • Abandoned requests. If a request dies without answering, the next retry takes its key over after 60 seconds.
  • Expiry. Keys are kept for 24 hours, after which the key can be reused.
Keys are checked after authentication and request-signature verification, so an unauthenticated or unsigned request can never claim or replay a key.