Skip to main content

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.

​
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: scoped to the player_id + direction pair — the same reference can be reused for a deposit and a withdrawal
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.