ZooZ Games operator integration

This guide is for casinos and sportsbooks ("operators") that want to offer ZooZ Games titles to their players: slots, crash, mines and dice. Every game uses one integration, the ZooZ Operator API v1.

• Seamless wallet. The player's balance always stays with you. ZooZ never holds player funds. For every bet and every payout, ZooZ calls your wallet, and your wallet is the system of record.
• Server-authoritative games. All outcomes (RNG, wins, features, crash points) are computed on the ZooZ Remote Game Server (RGS). The browser only displays them.
• Signed in both directions. Every request and every response carries an HMAC-SHA256 signature over the method, path, time, nonce and raw body. Replays are rejected. No long-lived token ever appears in a URL.

#How it works in one picture

flowchart LR
    P[Player browser] -- opens game --> O[Operator backend]
    O -- "1. POST /api/v1/operator/sessions (signed)" --> Z[ZooZ RGS]
    Z -- "gameUrl with 60 s one-time launch code (signed)" --> O
    O -- "iframe src = gameUrl" --> P
    P -- "2. game client exchanges the launch code" --> Z
    Z -- "3. POST walletUrl/balance, debit, credit, rollback (signed)" --> O

1. Launch. Your backend opens a game session with one signed call and receives a gameUrl.
2. Play. You put the gameUrl in an iframe (or redirect to it). The game client exchanges the one-time code for its own session. You do not need to do anything for this step.
3. Money. While the player plays, ZooZ calls your four wallet endpoints. Each call is signed, and each of your answers must be signed too.

#Documentation

#Onboarding checklist

#What ZooZ issues to you

Each secret is at least 32 random bytes, base64-encoded. The two families are separate, so a leaked wallet key cannot be used to open sessions, and the reverse. ZooZ sends secrets over a secure channel, never by plain email. Keep them in a vault or in environment variables, and never log them.

#What you give ZooZ

#Staging

1. Receive your staging operator id and both key families.
2. Run one of the samples, or your own code, against the test vectors. Do not go further until your code reproduces them exactly.
3. Implement the four wallet endpoints according to the rules. Give ZooZ your staging wallet URL.
4. Open a session with POST /api/v1/operator/sessions. Verify the response signature, then load the gameUrl in an iframe.
5. Play every enabled game type (slot, crash, mines, dice, plinko, crossing). For every round, check that your ledger has exactly one debit and then either one credit (including zero credits) or one rollback.
6. Run the wallet conformance test until it reports failed: 0. It sends correct and deliberately wrong signed calls to your wallet and checks every answer.
7. Test the remaining failure cases in the go-live test plan: timeouts, expired sessions and your own retries.

#Production

1. ZooZ issues production keys. They are different from the staging keys, and the staging keys never work in production.
2. Give ZooZ your production wallet URL (HTTPS) and, optionally, your source IPs.
3. Check that your servers' clocks are NTP-synchronised. Signatures are valid for ±300 seconds.
4. Launch a small set of games for internal accounts first. Reconcile your ledger against the ZooZ round report.
5. Open the games to all players.

#Conventions

• Amounts are JSON numbers in the currency's major unit (for example 1.5 = EUR 1.50). Parse them as decimals, never as binary floating point. Every amount ZooZ sends is written with exactly the currency's decimal places (EUR: 1.00, 2.50). See API reference → Amounts.
• Currencies are ISO 4217 codes in upper case.
• Times in signature headers are Unix seconds. Times in JSON bodies are ISO 8601 date-times with an offset.
• Contract changes. Adding fields is backward compatible, so ignore JSON fields you do not know. Removing a field or changing its meaning requires a new version (v2), which is announced in advance.