# Idempotency

> Retry any create request safely. A repeated key returns the original response.

Networks fail. If a request times out, you can't tell whether the payment was created. An idempotency key lets you send it again without charging twice.

## Send a key

Every request that creates or changes money requires an `Idempotency-Key` header of up to 255 characters:

- `POST /v1/payments`
- `POST /v1/payments/{payment_id}/refunds`
- `POST /v1/checkouts`
- `POST /v1/checkouts/{checkout_id}/capture`

Use a value tied to the operation in your system, such as your order id, or a UUID you store.

**cURL**

```bash
curl -X POST https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: refund-1524-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Idempotency-Key': 'refund-1524-1',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 500000
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
        "Idempotency-Key": "refund-1524-1",
    },
    json={
        "amount": 500000
    },
)
data = response.json()
```

## How it works

| You send | You get |
| --- | --- |
| A new key | The request runs. |
| The same key and the same body | The original response, with the original status code, and the header `Idempotent-Replayed: true`. Nothing runs again. |
| The same key and a different body | `409`. Use a new key. |
| The same key while the first request still runs | `409`. Wait and retry. |

Keys are scoped to the project, the environment, and the endpoint, including the id in the path. The same key on a different endpoint is a different operation. Results are kept for at least 7 days.

## Uncertain results

If the provider doesn't answer in time, Camel can't know whether the operation happened. It returns `202` with the resource in status `unknown`, and finds out the real result from the provider afterwards. You'll get a webhook when it settles.

> **Warning**
>
> Don't create a new payment for an `unknown` one; you could charge the customer twice. Retrying with the same key is always safe: it returns the same response.
