> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate transactions using idempotency keys.

Idempotency ensures that the same API call doesn't create duplicates, even when retried due to network issues.

## Why it matters

<Warning>
  Without idempotency, a connection timeout or retry can cause the **same payment to be processed twice** — resulting in double charges for your customer.
</Warning>

## How it works

<Frame caption="The first request carrying a given Idempotency-Key is processed and cached. Any retry with the same key returns the cached result — the customer is never charged twice.">
  <img src="/images/idempotency-flow.svg" alt="Diagram: first request is processed and cached (MISS); a retry with the same key returns the cached 201 result (HIT) without contacting the processor." />
</Frame>

<Steps>
  <Step title="Generate a unique key">
    For each payment, generate a UUID v4 as your idempotency key.
  </Step>

  <Step title="Send the key with your request">
    Add the `Idempotency-Key` header to your payment creation request:

    ```bash
    curl -X POST https://api.simiz.io/v1/transactions \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
      -d '{
        "amount": 5000,
        "currency": "XAF",
        "payment_method": "ORANGE_MONEY",
        "payer": {
          "phone": "237690000000",
          "name": "John Doe"
        },
        "description": "Order #12345"
      }'
    ```
  </Step>

  <Step title="Handle the response">
    * **First request** → Creates the transaction normally
    * **Subsequent requests with the same key** → Returns the existing transaction without creating a new one
  </Step>
</Steps>

## Key format

| Property       | Value                                                       |
| -------------- | ----------------------------------------------------------- |
| **Format**     | Any string up to 255 characters (UUID v4 recommended)       |
| **Uniqueness** | One key per operation — reuse the same key only for retries |

## Best practices

<CardGroup cols={2}>
  <Card title="Use UUID v4" icon="fingerprint">
    UUID v4 guarantees sufficient uniqueness. Avoid time-based or sequential keys.
  </Card>

  <Card title="One key per operation" icon="key">
    Create a new key for each new operation. Reuse the same key only for retries of the same request.
  </Card>

  <Card title="Store the key" icon="database">
    Save the idempotency key alongside the transaction in your database for audit trails.
  </Card>

  <Card title="Don't reuse across operations" icon="circle-xmark">
    Using the same key for different operations may return unexpected results.
  </Card>
</CardGroup>

## Common errors

| Scenario                       | Result                                             |
| ------------------------------ | -------------------------------------------------- |
| Same key, same parameters      | Returns the original response                      |
| Same key, different parameters | Returns the original response (new params ignored) |
| Key too long (>255 chars)      | `400 Bad Request`                                  |