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

# Idempotency

# Idempotency

Idempotency is a critical feature for payment systems. It ensures that performing the same operation multiple times has the same effect as performing it once.

## Why Idempotency Matters

In distributed systems, network requests can fail in ways that leave the state of the request ambiguous. For example:

* Your server sends a "Create Payment" request to fype.
* fype processes the request and creates the payment.
* The network connection drops before fype can send the response.
* Your server retries the request.

Without idempotency, this would result in two duplicate payments. With idempotency, fype recognizes the retry and returns the existing payment.

## Using Idempotency Keys

To perform an idempotent request, provide an `Idempotency-Key` header with a unique string.

```bash theme={null}
curl -X POST https://api.fype.dev/v1/payments \
 -H "Authorization: Bearer <API_KEY>" \
 -H "Idempotency-Key: unique_order_ref_987" \
 -d '{ ... }'
```

## How fype Handles Idempotency Keys

1. **Unique Key**: fype stores the `Idempotency-Key` and the associated merchant ID for 24 hours.
2. **Matching Request**: If a second request arrives with the same key and same merchant, fype checks if the request body is identical.
3. **Replay Response**: If the body matches, fype returns the cached response from the original request instead of creating a new payment.
4. **Error on Mismatch**: If the `Idempotency-Key` is the same but the request body is different, fype returns a `400 Bad Request` to prevent accidental state corruption.

## Best Practices

* **Generate Keys on Your End**: Use your internal database IDs or a UUID as the `Idempotency-Key`.
* **Scope Keys**: Keys are scoped to your merchant account. You can use the same key in Test and Live modes, as they are isolated.
* **Retry Safely**: Always implement a retry strategy with exponential backoff for network-related errors (HTTP 5xx or connection timeouts), using the same `Idempotency-Key` for every retry.