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

# Idempotency

> How the reference field prevents duplicate transactions on retries.

## The `reference` field

The `reference` field is your **idempotency key**. It must be unique per logical transaction — winam-payments uses it to deduplicate requests.

If you call `POST /deposits` or `POST /withdrawals` twice with the same `reference`, winam-payments returns the **existing transaction** without creating a duplicate.

```python theme={null}
# Both calls return the same transaction
response1 = client.post("/api/v1/deposits", json={..., "reference": "bet-98765"})
response2 = client.post("/api/v1/deposits", json={..., "reference": "bet-98765"})

assert response1.json()["winam_tx_id"] == response2.json()["winam_tx_id"]
```

## When to use

**Use case:** Your backend calls `POST /deposits` and the network times out before you receive the response. You don't know if winam-payments created the transaction. Retrying with the **same `reference`** is safe — you'll get the existing transaction back.

```python theme={null}
import uuid

# Generate a stable reference for each logical transaction
reference = f"bet-{bet_id}"  # or use uuid4() stored in your DB before the API call

try:
    response = client.post("/api/v1/deposits", json={..., "reference": reference})
except TimeoutError:
    # Safe to retry — winam-payments deduplicates on `reference`
    response = client.post("/api/v1/deposits", json={..., "reference": reference})
```

## Constraints

* Max length: **128 characters**
* Must be unique per logical transaction — use a different `reference` for each distinct payment
* Scope: scoped to the `player_id` + `direction` pair — the same `reference` can be reused for a deposit and a withdrawal

<Warning>
  If you use the same `reference` for two different amounts or MSDINs, winam-payments returns the original transaction — not an error. Always generate a fresh reference for each new transaction.
</Warning>