Skip to main content
Every public create operation requires an Idempotency-Key header: Generate and persist the key before sending the request. A UUID or a stable key derived from the business operation both work, provided you never reuse it for a different request.

​
Retry outcomes

Keys are scoped to the API key and operation. The same text used for POST /v1/payments and POST /v1/refunds identifies two independent operations, but reusing values across operations makes incident analysis much harder. Prefer a new key for every new business operation or Payment attempt. No fixed idempotency retention period is promised by this API contract.

​
Operation-specific effective request identity

Identity is derived from parsed fields, not raw JSON bytes. JSON property order and whitespace do not change the identity. The fields and normalization rules are different for each operation: A Payout replay returns the saved creation response, not a refreshed status. It can remain PROCESSING after the operation completes. Use GET /v1/payouts/{payout_id} for the current state; do not use a new key to resolve an uncertain existing Payout. For Direct Payment, changing only card fields while retaining the key replays the original Payment; it does not submit the changed card. A new card attempt is a new Payment attempt and requires a new key. For Payout, the destination card is part of the identity. A retry of one Payout therefore needs the same destination data, while a distinct Payout gets a new key.

​
Retry recipe

  1. Create and persist the key before the first request.
  2. Persist the non-sensitive fields that define the operation’s effective identity.
  3. On a timeout or retryable HTTP error, retry with the original key and an equivalent effective request identity, using exponential backoff.
  4. On idempotency_key_in_use, wait briefly and retry the same operation.
  5. On idempotency_key_reused, compare the effective identity fields. Retry the original operation or deliberately start a new business operation with a new key.

​
Card-data retry recipe

Direct Payment and Payout requests contain card data. Persist the key and non-sensitive operation data, but never persist PAN, CVC, or a complete card-data request body merely to support retries.
  • Keep card data only inside your approved PCI handling boundary for as long as the active request attempt needs it.
  • While the original body remains available there, a lost response can be retried with the same key and equivalent effective request identity.
  • For Direct Payment, card fields are deliberately excluded from idempotency. Reusing the key with unchanged non-card fields returns the original Payment, even if different card fields are supplied.
  • A new card attempt is a new Payment attempt and requires a new key.
  • For Payout, retain destination data only within the approved PCI boundary while retrying the original operation.
merchant_reference does not prevent duplicates. Two create requests with the same merchant_reference and different idempotency keys can create two objects.
After a terminal FAILED or EXPIRED Payment, a customer retry is a new Payment attempt and therefore needs a new key. Retrying a lost HTTP response is the same operation and therefore keeps the original key.