Launch game¶
POST /api/operator/v1/launch-game opens a new game session for one player and returns the URL to show them.
This is the one endpoint every casino must call. Call it every time a player opens a game, including after a click on a live banner.
Request¶
POST /api/operator/v1/launch-game HTTP/1.1
Host: {PROVIDER_HOST}
Content-Type: application/json
Api-Key: YOUR_API_KEY
{
"game_id": "block-boost",
"player_id": "player-123",
"currency": "USD",
"mode": "LIVE",
"rtp": 97,
"lang": "en"
}
| Field | Type | Required | Description |
|---|---|---|---|
game_id |
string | yes | block-boost, bingo-bongo, magic-double (Magic Jump) or flip-jet. |
player_id |
string | yes | Your stable, unique player id. It is sent back in every wallet callback. Do not use personal data (e.g. e-mail): some games show a nickname derived from it to other players (see Game specifics). Keep it ≤ 128 characters. |
currency |
string | yes | ISO 4217 code in upper case, e.g. USD, EUR. Must be enabled by 19flip and allowed for your account. The value is matched exactly: usd is rejected. |
mode |
string | yes | LIVE (real money through your wallet) or DEMO (no wallet calls). Not every game supports DEMO. |
rtp |
number | no | Return-to-player percent, e.g. 97 or 96.5. Must be one of the RTPs enabled for the game. If 19flip has fixed an RTP for your account, omit it or send exactly that value. If omitted, the fixed or default RTP is used. |
demo_balance |
number | no | Starting balance of a DEMO session. Send it for every DEMO launch: games that support demo start from 0 if it is missing. Ignored in LIVE. |
lang |
string | no | UI language code, e.g. en, ru. Passed into launch_url by games that support it; default en. Keep it ≤ 8 characters. |
Unknown fields are ignored. In particular, a callback_url field in this request has no effect: your callback URL is configured on your account by 19flip.
Response¶
200 OK:
{
"success": true,
"data": {
"session_id": "3f6c2a9e-8d41-4b7a-9c55-1e2f0a7b9d10",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"launch_url": "https://block-boost.example.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&lang=en"
}
}
| Field | Type | Description |
|---|---|---|
success |
boolean | Always true on success. |
data.session_id |
string (UUID) | The game session. It appears as session_id in every wallet callback for this session. Store it with the player and game if you want to reconcile. |
data.token |
string | The session token that is already embedded in launch_url. You do not need to use it separately. |
data.launch_url |
string | Open this URL for the player (redirect or iframe). |
Session and URL lifetime¶
- Every call creates a new session. There is no "resume session" call; launch again instead.
- Open
launch_urlright away and do not cache it. For Bingo Bongo the token in the URL is single-use and valid for 5 minutes. For Block Boost and Mister Twister it is valid for 24 hours. - A session never expires for money purposes: wins and rollbacks for a session can arrive long after the player closed the game. See Wallet callbacks.
What 19flip applies at launch¶
The session is created with the settings in force at launch time and keeps them for its whole life, even if your settings change later:
| Setting | Effect |
|---|---|
| RTP | Your fixed RTP for the game if 19flip set one; otherwise the requested rtp; otherwise the game's default. |
| Bet ladder | The list of bet amounts the game offers, per game and currency, filtered by your minimum and maximum bet. |
| Minimum / maximum bet | Bets outside these limits are rejected by 19flip and never reach your wallet. The maximum applies to the whole amount debited in one round: in games where a round can cost more than the bet (an ante or a bonus buy), 19flip passes the limit to the game, and the game disables those options while their price is above it. Exception: a Flip Jet Golden Flight purchase is checked against the base bet, so its price (20×, 50× or 100× the base bet) may exceed the maximum. |
| Maximum win | Per-round win cap, passed to games that support it: Magic Jump and Flip Jet apply it, the other games do not; see Game specifics. |
| Visual players | Flip Jet only, off by default: 19flip can turn on, for your account, a range of simulated players (for example 15–20) that add to the "playing" counter and place bets in the "All bets" list. They exist only on screen: no wallet calls, not in your reports, not in the daily top. Seen only by your players. |
| Golden Flight | Flip Jet only, off by default: a bonus buy of a personal flight for 20×, 50× or 100× the bet, RTP 97 %. 19flip turns it on for your account only on your request, optionally with a pause between a player's purchases. Check that bonus buy is allowed under your licence first. See Game specifics. Added in 2.73.0. |
| Game title | Whether the game shows its name (wordmark) in the top-left corner. Shown by default; 19flip can hide it for your account per game on request. Supported by Flip Jet; the other games always show their name. |
Checks and errors¶
The checks run in this order. The first failing one is returned. Error body format is described in Errors.
| Condition | HTTP | code |
detail example |
|---|---|---|---|
Api-Key missing |
401 | AUTH_ERROR |
Api key not provided |
| Key unknown (or previous key after its grace period) | 401 | AUTH_ERROR |
Operator not found |
| Caller IP not in your allowlist | 403 | IP_NOT_ALLOWED |
IP 203.0.113.7 is not allowed for this operator |
| Account suspended | 403 | OPERATOR_SUSPENDED |
Operator is suspended |
Body invalid (missing field, wrong type, mode not LIVE/DEMO) |
400 | REQUEST_ERROR |
see example below |
Unknown game_id |
400 | REQUEST_ERROR |
Game roulette not found |
| Game under maintenance | 403 | GAME_UNAVAILABLE |
Game block-boost is under maintenance |
| Game disabled | 403 | GAME_UNAVAILABLE |
Game block-boost is disabled |
| Game not connected on this 19flip installation | 403 | GAME_UNAVAILABLE |
Game block-boost integration is not configured |
| Game switched off for your account | 403 | GAME_UNAVAILABLE |
Game block-boost is not available for this operator |
| Currency unknown or disabled | 400 | REQUEST_ERROR |
Currency not supported |
| Currency not in your allowed list | 400 | REQUEST_ERROR |
Currency GBP is not allowed for this operator |
Player blocked by 19flip (LIVE only; DEMO is still allowed) |
403 | PLAYER_BLOCKED |
Player is blocked |
rtp differs from the RTP fixed for your account |
400 | REQUEST_ERROR |
RTP 99 is not allowed for this operator (fixed at 97) |
rtp not enabled for the game |
400 | REQUEST_ERROR |
RTP 95 is not allowed for this game |
The game refused to open the session (for example DEMO in Bingo Bongo) or could not be reached |
502 | EXTERNAL_SERVICE_ERROR |
Game API error: Failed to request: 400 {...} |
| Anything unexpected | 500 | UNKNOWN_ERROR |
– |
Validation error example (player_id missing):
{
"success": false,
"code": "REQUEST_ERROR",
"traceback": "q7ZkP2xY9a",
"detail": "[{'type': 'missing', 'loc': ('body', 'player_id'), 'msg': 'Field required', 'input': {'game_id': 'block-boost', 'currency': 'USD', 'mode': 'LIVE'}, 'url': 'https://errors.pydantic.dev/2.12/v/missing'}]",
"errors": [
{"loc": ["body", "player_id"], "msg": "Field required"}
]
}
Use errors for machine handling; detail is a human-readable dump and its wording may change.
Retrying a launch¶
launch-game is not idempotent: each successful call creates a new session. It moves no money, so retrying after a timeout or a 5xx is safe; the unused session is simply never opened.