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

An exact retry of an already created Refund returns its stored creation response, even if the source Payment uses a currency that is no longer accepted for new Refunds. A new key for that source Payment is a new Refund request and receives 422 currency_not_supported with param: payment_id. 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: For both Payment create operations, the exact merchant_customer_id participates in the fingerprint. Its case, leading or trailing whitespace, internal whitespace, and content are not normalized. Changing any of them while reusing a key returns 409 idempotency_key_reused; an exact retry uses the original value unchanged. 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. Apple Pay and Google Pay are Experimental: their support and this guidance are still being refined and are not final. Wallet requests use the same idempotency reservation as other Direct Payments. Wallet request identity distinguishes the method, format, and required Google auth_method, not the credential bytes. PAN/DPAN, CVC, cryptogram, ECI, and wallet tokens are excluded; so are all nine browser_information values. Changing credentials or browser values is not a way to request another Payment under the same key. Idempotency identifies a Payment attempt, not proof that credentials match. Encrypted wallet input is reserved and rejected before Payment registration in this release. The existing card identity above is unchanged. Browser information is excluded even when supplied with an ordinary card. customer_ip_address remains in the existing identity; the browser-value exclusion does not exclude or change its handling. See wallet contract availability. 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. Flowlix’s bounded provider retries reuse the existing order and prepared request. They do not change merchant idempotency conflicts: a same-key request that is still in progress can still return 409 idempotency_key_in_use, and a changed effective identity still returns 409 idempotency_key_reused. A same-key replay does not resume or resubmit money movement. Use object retrieval for current state.