Reference
Schemas, error codes, glossary
Glossary
Bingo and casino terms
| Term | Definition |
|---|---|
| Aggregator | A platform that sits between casinos and game providers, handling wallet integration on the casino's behalf |
| Brand | A sub-identity within an operator (one operator may run multiple brands across different markets) |
| Autospin | A slot setting that places spins for the player automatically. Such bets carry "autoplay": true on the debit |
| Campaign | A free cards offer we set up with you (game, currency, dates, card count, stake). Every free card grant belongs to one |
| Card (bingo) | One numbered grid a player has bought for a round |
| Free cards / free bet | A grant of free bingo cards to one player, paid by your promotion. See Free cards |
| Game code | The identifier of a specific game (e.g., live-bingo) |
| Host stream | Live video of a human host calling balls; embedded inside the iframe |
| Jurisdiction | The regulatory territory governing a player's session, e.g. MGA (Malta Gaming Authority), UKGC (UK Gambling Commission), AGCO (Ontario), Spelinspektionen (Sweden), ADM (Italy) |
| KYC (Know Your Customer) | Identity-verification checks the casino performs on its players |
| Lucky line | A side bet that pays out if the player matches numbers in a specific pattern |
| Operator | Your casino, identified to us by operator |
| Replay URL | A short-lived URL serving a recorded view of a past round |
| RNG (Random Number Generator) | The certified random source we use to draw bingo balls and slot reel positions |
| Room | A shared live game multiple players join at the same time |
| Round | One bingo game from card purchase to result payout, inside one room |
| RTP (Return To Player) | The long-run percentage of stakes returned to players as wins |
| Seamless wallet API | A wallet model where the game provider calls the casino's wallet in real time per transaction, rather than transferring a balance up-front |
| Settlement | The moment a round's outcome is finalised and money is paid to winners |
| Side bet | An optional extra bet placed alongside the main wager (e.g., lucky line) |
| Slots | Slot games offered inside some bingo rooms. See Slots |
| Spin | One play of a slot game. Each spin is its own round |
| Stake / wager | Player-facing amount bet per card (bingo) or per spin (slots), before wallet wire conversion |
| Volatility | How variable wins are around the long-run RTP. Higher volatility means bigger but rarer wins |
Identifiers and integration
| Term | Definition |
|---|---|
| External session ID | The session identifier on your side. See repeat calls for how we match it |
| Session ID | The session identifier on our side, returned from /gamelauncher/play |
| Round ID | Unique per player per round; not shared between players in the same room. An opaque string: usually a UUID, slots:<uuid> for a slot spin |
| Transaction ID | UUID, unique per wallet call; idempotency key. Retries reuse it |
| Launch code | A short-lived code (10 minutes) embedded in the launch URL; exchanged for a player token when the iframe starts |
| Launch URL | The URL the casino loads in an iframe to start the player's session |
| Mode | DEMO or REAL. Stored with the session; doesn't change game behaviour today |
| Channel | Free-form marker such as web, mobile-web, native. Stored with the session |
Tech terms
| Term | Definition |
|---|---|
| Basic Auth | HTTP authentication scheme; credentials sent as Authorization: Basic <base64(username:password)> |
| BCP 47 | Standard for language tags (e.g., en, en-GB, pt-BR) |
| CSP (Content Security Policy) | Browser security policy listing which hosts a page may load resources from |
| Egress IP | The public IP a server uses when calling out to the internet. We share ours so direct integrators can allowlist our wallet calls |
| Idempotency | Property whereby calling an operation twice with the same key produces the same result, not two effects |
| iframe sandbox | The sandbox attribute on <iframe>, which restricts what an embedded page can do; relaxed via allow-* tokens |
| ISO 3166-1 alpha-2 | The two-letter country code standard (US, GB, MT, JP) |
| ISO 4217 | The international currency-code standard (USD, EUR, GBP) |
| MDX | Markdown with embedded JSX components; the format these docs are written in |
| postMessage | Browser API for cross-origin communication between a parent page and an embedded iframe |
Status / error codes
There are two surfaces with different conventions. Don't confuse them.
Launcher API errors (we return — integer codes)
{ "errorcode": 101, "errormessage": "bad request" }errorcode | HTTP status | Meaning |
|---|---|---|
101 | 400 | Bad request — missing or malformed field, or the game can't be launched |
101 | 500 | Server-side internal failure on /gamelauncher/play |
201 | 401 | Access denied — bad or missing Basic Auth |
206 | 404 | Round not found, or not finished yet (replay only) |
500 | 500 | Internal server error on /gamelauncher/replay — safe to retry |
Classify by HTTP status, not just errorcode. The errormessage values are
listed on the Launcher API and
Free cards pages. /freebet/give and
/freebet/cancel use the same envelope.
Wallet errors (direct integrators return to us — string codes)
{ "errorcode": "NOT_SUFFICIENT_FUNDS", "errormessage": "balance below stake" }Codes we currently treat specially:
errorcode | What we do |
|---|---|
NOT_SUFFICIENT_FUNDS | Reject the bet, show the player "Insufficient balance." |
BET_LIMIT_REACHED | Reject the bet, show the player "You have reached your betting limit." |
GAMING_LIMIT_REACHED | Same as BET_LIMIT_REACHED |
SESSION_NOT_FOUND | Show the player "Your session has expired. Please reconnect." |
Any other errorcode you return is logged and treated as a generic business
error. You may return codes like PLAYER_BLOCKED, PLAYER_NOT_FOUND,
CURRENCY_MISMATCH, ROUND_ALREADY_CLOSED for
clarity in your own logs; today they aren't specially handled, but we
expect to add behaviour as the integration matures.
Note: these codes flow only from the casino to us. We never send any of these codes back. Errors we return use the integer envelope above.
iframe lifecycle events
The iframe does not currently emit any postMessage events to its parent
window. There is no published event contract today. See
Lifecycle signals for the full
explanation.
Allowed values reference
These are values for fields you send to us in /gamelauncher/play:
| Field | Allowed values |
|---|---|
mode | DEMO, REAL |
channel | web, mobile-web, native |
language | en (others on request) |
Currency notes
We accept any currency code your operator is configured for: ISO 4217 codes,
or sweepstakes codes such as SC and GC. By default, wallet amounts are sent as integer cents (see
Money). Custom integrations can use a different
amount convention when agreed during onboarding. Display aliases — showing a
custom symbol or abbreviation in the player's UI rather than the raw currency
code — are configured per operator on request.
Changelog
Breaking changes are announced ahead of time and versioned per integrator.
2026-09-29
- Slots (rolling out). Some bingo rooms offer slot games inside the same
iframe. Each spin is its own round:
roundidslots:<uuid>, onedebit, onecredit(also for no win), optional"autoplay": trueon the debit, and latereverse/creditcalls from our background job. See Slots. - Free cards need a campaign.
/freebet/giveis only accepted inside a campaign we set up with you, andnumbets/freebetamountmust match it. Free cards are switched on per partner. Moved to their own page: Free cards. - Round IDs are opaque strings. Not every
roundidis a UUID. - Wallet error codes.
BET_NOT_ALLOWEDis no longer handled specially. UseBET_LIMIT_REACHEDorGAMING_LIMIT_REACHEDfor betting limits. - Corrections to how we handle repeat
/gamelauncher/playcalls, launch code and replay URL lifetimes,mode: DEMO, optional launch fields,CURRENCY_MISMATCH, error responses withouterrorcode, IP allowlisting, and CSP. Added the HMAC signing option for wallet calls, per-game hosts, and the replay dashboard.