API reference

All bodies are JSON (Content-Type: application/json, UTF-8). Field names are camelCase. Production traffic in both directions uses HTTPS only (TLS 1.2+). For the signature headers and algorithm, see Signing.

#Common types

#Amounts

#Identifiers

Treat all ids as opaque strings. The formats above are informative. Do not parse them.

#Operator → ZooZ

#POST /api/v1/operator/sessions

Opens a real-money game session for one of your players and returns a one-time game URL.

Request headers: Content-Type: application/json plus the five request signature headers (X-ZooZ-Operator, X-ZooZ-Key-Id, X-ZooZ-Timestamp, X-ZooZ-Nonce, X-ZooZ-Signature), signed with an operator key. The path to sign is /api/v1/operator/sessions, and the query is empty.

Request body:

{
  "sessionId": "op-sess-7c1e",
  "playerId": "12345",
  "nickname": "ahmet",
  "currency": "EUR",
  "gameId": "safari-king",
  "language": "en",
  "returnUrl": "https://casino.example/lobby"
}

Unknown fields are ignored.

Response 200 (signed with an operator key, see response signature):

{
  "gameUrl": "https://games.example/safari-king/?launch=3f9c…e1",
  "launchExpiresAt": "2026-09-24T12:01:00.5160000+00:00"
}

Errors: HTTP status plus ProblemDetails. Every response except the authentication 401 is signed.

Note: a body that cannot be parsed is rejected with HTTP 400. Depending on the server configuration, the body is either ProblemDetails with INVALID_REQUEST or empty. Treat a 400 without a code as INVALID_REQUEST.

The 401 body is not ProblemDetails. It is exactly {"status":"error","code":"…"}.

#GET /api/v1/games

Public, unsigned. It lists the games in the ZooZ catalog. Games that are not enabled for your account are also listed, and launching them returns GAME_NOT_ALLOWED.

Response 200:

[
  { "id": "safari-king", "type": "slot", "name": "Safari King" },
  { "id": "sky-parrot", "type": "crash", "name": "Sky Parrot" },
  { "id": "jungle-mines", "type": "mines", "name": "Jungle Mines" },
  { "id": "monkey-dice", "type": "dice", "name": "Monkey Dice" },
  { "id": "jungle-plinko", "type": "plinko", "name": "Jungle Plinko" },
  { "id": "jungle-jewels", "type": "slot", "name": "Jungle Jewels" },
  { "id": "croc-crossing", "type": "crossing", "name": "Croc Crossing" },
  { "id": "tropic-treats", "type": "slot", "name": "Tropic Treats" }
]

#POST /api/v1/operator/conformance/runs

Signed with your operator keys, like /operator/sessions. ZooZ runs its wallet conformance test against your configured wallet URL and returns the report. About 25 signed calls are made: correct ones, and deliberately wrong ones that your wallet must refuse (wrong or missing signature, unknown key id, timestamps 10 minutes off, body changed after signing, replayed nonce, a session of another player or currency, repeated debits and credits, rollbacks before and after a debit, a debit larger than the balance, a negative amount).

The test moves real money on the session you give (debits, credits, rollbacks). A conformant wallet ends where it started. Use a staging test player with at least 3× amount. At most one run at a time and 10 runs per hour.

Request:

{ "sessionId": "your-test-session", "playerId": "test-player-1", "currency": "EUR", "amount": 1.00 }

Response 200 (signed): passed, warnings, failed, skipped, startBalance, endBalance and checks, one entry per check:

{
  "id": "debit.idempotent",
  "category": "Debit",
  "title": "Same debit again (new nonce)",
  "expected": "status ok, same operatorTransactionId, balance still 49.00",
  "outcome": "pass",
  "actual": "HTTP 200, status ok, balance 49.00, signed",
  "httpStatus": 200,
  "elapsedMs": 38,
  "request": "POST /wallet/debit\n{…}",
  "response": "HTTP 200\n{…}"
}

outcome is pass, warn (accepted by ZooZ, but not what the contract asks for, for example the wrong error code), fail (must be fixed before go-live) or skipped. Go live only with failed: 0.

#Game client → ZooZ (for reference)

#POST /api/v1/sessions/exchange

Called by the game client with the launch parameter of the gameUrl. You never call it. It is described here so that you know why a gameUrl works only once.

{ "launch": "3f9c…e1" }

Response 200: { "token": "…", "expiresAt": "2026-09-24T20:00:00+00:00" }. The token is sent as Authorization: Bearer on the game endpoints. It expires after 8 hours of inactivity by default.

The code is consumed atomically. If two tabs race, exactly one of them wins. The game endpoints behind the token (/api/v1/game/*, /api/v1/crash/*) are internal to the game clients and not part of this contract.

#ZooZ → Operator: seamless wallet

ZooZ calls POST {walletUrl}/{action}. For example, with the wallet URL https://api.casino.example/zooz/wallet, a debit goes to https://api.casino.example/zooz/wallet/debit, and the signed path is /zooz/wallet/debit.

Request headers (all four actions):

Your response (all four actions): HTTP 200 with these headers, signed with a wallet key:

Success body:

{ "status": "ok", "balance": 998.00, "operatorTransactionId": "tx-9876" }

Business error body:

{ "status": "error", "code": "INSUFFICIENT_FUNDS", "balance": 0.50 }

Any non-200 status, a missing or invalid signature, a response timestamp outside ±300 s or a malformed body means outcome unknown. See the integration guide. For request authentication failures, answer 401 with {"status":"error","code":"INVALID_SIGNATURE"} (or STALE_TIMESTAMP / REPLAY).

#POST {walletUrl}/balance

When: when a game is opened, and whenever ZooZ needs a fresh balance (for example after a round whose credit is still pending).

{ "sessionId": "op-sess-7c1e", "playerId": "12345", "currency": "EUR" }

Respond ok with balance. For an unknown session, a mismatched player or currency, or an expired session, respond error with SESSION_INVALID. ZooZ then tells the player that the wallet is unavailable. Nothing is retried automatically.

#POST {walletUrl}/debit

When: a bet is placed (one per round, or one per crash bet). No outcome exists yet.

{
  "transactionId": "01997a3c5e2b7c1d9f00aa11bb22cc33-bet",
  "roundId": "01997a3c5e2b7c1d9f00aa11bb22cc33",
  "gameId": "safari-king",
  "sessionId": "op-sess-7c1e",
  "playerId": "12345",
  "currency": "EUR",
  "amount": 1.00
}

Take amount atomically if the balance allows it. Otherwise answer INSUFFICIENT_FUNDS and move nothing. If this transactionId was already rolled back (or tombstoned), answer TRANSACTION_ROLLED_BACK. ZooZ never retries a debit. A second debit with the same id is a duplicate delivery, so answer it with the first response.

#POST {walletUrl}/credit

When: the round (or crash bet) is settled. It is sent for losses too, with amount: 0. It may arrive long after the session expired, and it may be retried.

Body: the same fields as the debit, with transactionId ending in -win and amount ≥ 0 (the total win of the round, including all free spins).

Add amount atomically and answer ok. Accept an expired session (the session must exist, and the player and currency must match). If you have a debit for this round, it must belong to the same player (in crash: this player's debit in that round). Any error makes ZooZ retry later, so do not refuse a valid credit.

#POST {walletUrl}/rollback

When: a debit must be reversed, because its outcome was unknown, the game failed before an outcome existed, or (in crash) the bet was cancelled or voided.

{
  "transactionId": "01997a3c5e2b7c1d9f00aa11bb22cc33-bet",
  "roundId": "01997a3c5e2b7c1d9f00aa11bb22cc33",
  "gameId": "safari-king",
  "sessionId": "op-sess-7c1e",
  "playerId": "12345",
  "currency": "EUR",
  "amount": 1.00
}

transactionId is the id of the debit being reversed. amount is the debit amount. When you refund, use the amount you stored for the debit. Accept an expired session.

#Wallet error codes

How ZooZ reacts to each code on each call is described in the integration guide.

#Errors (ProblemDetails)

ZooZ endpoints (except the authentication 401) return errors as RFC 7807 ProblemDetails (Content-Type: application/problem+json) with a stable code extension. Build your logic on code and the HTTP status. title repeats the code, and detail is human-readable and may change.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "UNSUPPORTED_CURRENCY",
  "status": 400,
  "detail": "Currency 'TRY' is not enabled for this operator.",
  "code": "UNSUPPORTED_CURRENCY",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Quote traceId (when present) in support requests.

#Code catalogue

The game client shows these codes to the player. They are listed here so that your support team can match player reports to wallet traffic. For example, a spike of WALLET_UNAVAILABLE usually means your wallet is slow or failing signature checks.