Idempotency
POST /sdk/server/create-payment requires the header X-Idempotency-Key. This lets you safely retry network failures without creating duplicate payments for the same business operation.
Header
X-Idempotency-Key
Non-empty string (opaque; UUIDs recommended)
Yes
Semantics
First request with a new key
Request is processed normally.
Retry with the same key and same raw body
If a successful response was already produced, that response is returned again from cache (see below).
Same key, different body
409 — IDEMPOTENCY_CONFLICT.
Concurrent duplicate requests
May receive 409 — DUPLICATE_REQUEST while the first is still in flight.
Success responses are cached for idempotent replay when the JSON body matches (success === true or status === true in the response body per implementation).
TTL
Default time-to-live for idempotency records is 24 hours, configurable via environment variable KOLLECT_S2S_IDEMPOTENCY_TTL_SEC on the Kollect deployment.
Storage backend
Idempotency relies on a shared store (typically Redis). If Redis is unavailable in production, you may receive 503 in some configurations (REDIS_REQUIRED-style errors). Coordinate with your platform team for high availability.
Operational guidance
Use one idempotency key per business transaction (e.g. order id or checkout session id).
Never reuse a key for a different cart, amount, or payer.
On
409 DUPLICATE_REQUEST, back off and optionally GET internal state using your own order id, or retry later.
Related pages
Last updated
Was this helpful?