> For the complete documentation index, see [llms.txt](https://kreatorverse-2.gitbook.io/kollect-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kreatorverse-2.gitbook.io/kollect-documentation/security/idempotency.md).

# 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

| Header              | Format                                       | Required |
| ------------------- | -------------------------------------------- | -------- |
| `X-Idempotency-Key` | Non-empty string (opaque; UUIDs recommended) | Yes      |

***

## Semantics

| Scenario                                              | Behavior                                                                                                       |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **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

* [Create payment URL](/kollect-documentation/api-reference/create-payment.md)
* [Best practices](/kollect-documentation/guides/best-practices.md)