Idempotency - Winam Payments API

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.

# 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.

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: unique across the whole platform, for deposits and withdrawals alike — never reuse a deposit’s reference for a withdrawal
Prefix your references with your platform name (for example gr8star-bet-98765): a reference already used by another application is rejected with 409 {"detail": "Reference already used by another application."}

If you use the same reference for two different amounts or MSDINs, winam-payments returns the original transaction — not an error. Reusing a deposit’s reference for a withdrawal also returns the original deposit. Always generate a fresh reference for each new transaction.