Idempotency
Safely retry POST requests.
Network calls fail in ambiguous ways: a request times out, but you don't know whether the server processed it. Idempotency lets you retry a write safely — the same logical operation runs at most once, no matter how many times you send it.
The Idempotency-Key header
Send an Idempotency-Key header on a write request. If you ever replay the exact
same request with the same key, ShiftxPay returns the original response instead
of performing the operation again.
curl https://api.lite.shiftxpay.com/v1/payments \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff" \
-d '{ "checkout_session_id": "cs_3Nk2p8c9aBcDeFgHiJkLmNoP" }'Use a fresh UUID per logical operation — one key for "charge order #1234", reused only when retrying that same charge. Do not reuse a key across different operations.
Where it is honored
Idempotency is honored on exactly these POST endpoints:
| Endpoint | Operation |
|---|---|
POST /v1/checkout-sessions | Create a checkout session |
POST /v1/payments | Create a payment |
POST /v1/payments/{id}/refunds | Create a refund |
Other endpoints ignore the header.
Replay behavior
| Situation | Result |
|---|---|
| Same key, same request body | The original response is replayed. |
| Same key, different body | 422 idempotency_key_reuse |
| Same key, request still in flight | 409 idempotency_conflict |
- Replay is the happy path: a safe retry returns the first outcome, so you never double-charge.
422 idempotency_key_reusemeans you reused a key for a genuinely different request. Keys are bound to the body they first saw; pick a new key for a new operation.409 idempotency_conflictmeans an earlier request with the same key is still being processed. Wait and retry; do not spin in a tight loop.
See Errors for the full status list.