Concepts

A short tour of terms you'll see repeated throughout the integration docs. Skim this once before diving in. Bingo-specific terms are introduced as plain English first.

How the game works (one paragraph)

Players join a room (a shared bingo game with multiple players in it at the same time). They buy one or more cards (each card is a numbered grid). Numbers are called over a live video stream by a human host (the host stream). Players match called numbers on their cards, and at the end of the round (one complete game in that room), winners get paid.

You don't need to understand any of the bingo math to integrate. You only need to know when a round started and ended, and how much money moved.

Players, rounds, and rooms

Room — a shared live game multiple players join at the same time. Each room runs back-to-back rounds.
Round — one bingo game from card purchase to result payout. A round belongs to exactly one room. Each round has a globally unique roundid (UUID).
Card — one numbered grid a player has bought for a round. A player can hold several cards in one round.
Stake / wager — how much a player bets per card. Same thing, two words used interchangeably across the industry.
Side bet — an optional extra bet a player makes alongside their cards (e.g., "lucky line" — a small extra wager that pays out if the player matches numbers in a specific pattern). Independent from the main card win.
Settlement — the moment a round's outcome is finalised and money is paid out to winners. Your wallet endpoint sees this as a credit call.
Host stream — the live video of a human host calling balls. Embedded inside our iframe; you don't connect to it separately.

Each player has their own roundid, even when they share a room. Wallet calls are always per-player, never per-room. Two players in the same bingo room playing the same round will see two different roundid values in their wallet logs. This is the single most counterintuitive fact in these docs — keep it in mind.

Session

A session is one player's authorised window to play. Sessions are created when an aggregator (or you, if integrating directly) calls our /gamelauncher/play endpoint. Each session carries an operator, brand, currency, mode, and two IDs:

sessionid — our identifier for the session. We generate it.
externalsessionid — your identifier for the session (or your aggregator's). You generate it. We treat (operator, externalsessionid) as the idempotency key for /gamelauncher/play, so re-calling with the same pair returns the existing session rather than creating a duplicate.

A session is created with an absolute lifetime of 24 hours by default (configurable; talk to us during onboarding). The lifetime is fixed at creation — there is no "keep-alive on activity". When the lifetime expires, the session row is reaped passively from our database. We do not currently signal the casino's wallet that a session ended.

The launch code embedded in the launch URL is much shorter-lived: 10 minutes by default. Once consumed, it's gone — request a fresh launch URL each time you start a player session.

Launch code

/gamelauncher/play returns a launch URL that contains a short-lived launchCode. The casino embeds this URL in an iframe. Our frontend exchanges the launch code once for a session token, then loads the game. Launch codes are single-use and expire within minutes — request a fresh one for every new player session.

Transaction

Every wallet operation (debit, credit, reverse) carries a unique transid (UUID). Transaction IDs are idempotency keys — calling twice with the same transid MUST produce the same result, not two effects. This matters because we retry on network failures (3 attempts with exponential backoff).

Mode

Mode	Real money?	Player identity required?	Use for
`DEMO`	No	No	Sandbox testing, integration development
`REAL`	Yes	Yes	Production play

Source of truth for round outcomes

This is important — read it once, don't forget it.

Aggregator path: the aggregator's wallet is the source of truth. When a player wins, we send a credit call to the aggregator. Their record of the credit is what your reporting reconciles against.
Direct integration path: the credit call we send to your wallet is the source of truth. Your record of that call is the authoritative outcome.

The iframe does not currently emit any lifecycle events to its parent window — there is no postMessage contract today. Rely on the wallet records.

Identifiers you'll provide

Field	Purpose
`operator`	Your operator identifier with us — assigned during onboarding
`brand`	A sub-identity within your operator. Some operators run multiple brands (different sites, different markets); you can leave it equal to `operator` if you only have one
`gamecode`	Which of our games you're launching (e.g., `BINGO25`)
`externalsessionid`	Your session identifier; we use it as an idempotency key
`currency`	ISO 4217 alphabetic code (USD, EUR, GBP, ...). ISO 4217 is the international currency-code standard
`playerid`	Your stable identifier for the player
`country`	ISO 3166 two-letter country code for the player. Used for geo-rule enforcement when a jurisdiction requires it
`ipaddress`	Player's IP address. Captured for audit; geo-rule enforcement is opt-in per operator

Money

All amounts are sent as integer cents — the main currency unit times 100. There are no decimals or floats anywhere in the API.

Currency	Main unit	Wire amount	Example
USD, EUR, GBP	dollar / euro / pound	main × 100	$1.00 → `100`
Any other two-decimal currency	main unit	main × 100	0.50 PLN → `50`

Today only currencies whose minor unit is 1/100 of the main unit are fully supported. ISO 4217 currencies with a different minor unit (JPY: none; BHD: 1/1000; cryptocurrencies: variable) need per-operator configuration before go-live — talk to us during onboarding so we can map your currency to the wire convention correctly. The backend currently multiplies the player-facing amount by 100 regardless, so a JPY-configured operator without that mapping will see ¥150 land on the wire as 15000.

Currency mismatch

A session is fixed to one currency for its entire lifetime. We do not convert between currencies. We always send the session's currency on every wallet call. If the player's wallet doesn't actually hold that currency, your wallet should return CURRENCY_MISMATCH and we will end the session.

To avoid this, the casino is responsible for either:

Picking a currency the player's wallet supports before launching, or
Operating sub-wallets per currency on your side.

Field naming

All HTTP API fields (launcher API and direct-integration wallet endpoints) are lowercase, no separators — roundid, transid, sessionid, externalsessionid, playerid, gamecode, debitamount, creditamount, originaltransid, ipaddress. This matches the existing seamless-wallet conventions.

Auth

All endpoints (in both directions) use HTTP Basic Auth by default — that's a Authorization: Basic <base64(username:password)> header on every request. We issue credentials during onboarding. Rotate on request.

IP allowlists apply both ways:

Inbound (you → us) — you share your egress IPs (the public IPs your servers use when calling out to the internet) so we can let your traffic through.
Outbound (us → you) — for direct integrators only. We share our egress IPs so you can let our wallet calls through.

Concepts

On this page