Skip to content

Quickstart

The whole casino integration on one page: what you get from 19flip, the one endpoint you must call, the five endpoints you implement, the optional live banners, and the rules that keep money correct. Each step links to the detailed page. If you only read one page, read this one and then Wallet callbacks.

The model

  • 19flip never holds player money. Your wallet is the only source of truth for balances.
  • You call one required endpoint: POST /api/operator/v1/launch-game. It returns a launch_url that you open for the player.
  • Optionally, you put live banners in your lobby: a two-line HTML snippet that shows the current Bingo Bongo draw and hands you the click.
  • 19flip calls five endpoints on your side, all POST with a JSON body, under the callback_url you give us:
Your endpoint Purpose
{callback_url}/balance Return the player's balance
{callback_url}/bet/debit Take a bet from the player's balance
{callback_url}/win/credit Add a win to the player's balance
{callback_url}/bet/rollback Return a previously debited bet
{callback_url}/win/rollback Take back a previously credited win

There is no single callback URL with an action field. Each operation has its own path.

Step 1. Exchange credentials

You receive from 19flip You give to 19flip
Provider host, e.g. https://{PROVIDER_HOST} callback_url – the base URL of your wallet endpoints, e.g. https://casino.example.com/api/providers/19flip (no trailing path, no query string)
api_key – identifies you The IP addresses/CIDR ranges your backend calls us from (optional allowlist)
secret_key – verifies our callbacks The currencies you need

Both keys are secrets. Store them server-side only.

Step 2. Implement the wallet endpoints

For every callback:

  1. Read the raw body bytes.
  2. Check X-Signature == hex(sha256(raw_body + secret_key)). Reject with 401 if it does not match. See Authentication.
  3. Check that Authorization: Bearer <key> or X-API-Key equals your api_key.
  4. For money endpoints, look up idempotency_key. If you have seen it, return the stored response and do nothing else. See Idempotency & retries.
  5. Apply the operation and answer with a flat JSON object (no success/data envelope):
{
  "transaction_id": "5b0e1c52-3f7e-4d7c-9a8e-0f5d2a61c9e4",
  "balance_before": 100.0,
  "balance_after": 98.5,
  "status": "SUCCESS"
}

For /balance the answer is:

{
  "balance": 100.0,
  "currency": "USD"
}
  1. If the player cannot afford a bet, answer HTTP 402. See Errors.

Full request/response definitions: Wallet callbacks.

Step 3. Launch a game

curl -X POST "https://{PROVIDER_HOST}/api/operator/v1/launch-game" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -d '{
    "game_id": "block-boost",
    "player_id": "player-123",
    "currency": "USD",
    "mode": "LIVE",
    "lang": "en"
  }'

{
  "success": true,
  "data": {
    "session_id": "3f6c2a9e-8d41-4b7a-9c55-1e2f0a7b9d10",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "launch_url": "https://block-boost.example.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&lang=en"
  }
}

Open launch_url for the player (redirect or iframe). Call launch-game again every time the player opens a game; do not reuse a launch_url. Details: Launch game.

Optional: live banners

Call GET /api/operator/v1/banners with your Api-Key, then paste the returned embed_html into your lobby. Handle the 19flip:banner-open event by launching the game as in Step 3. The banner key in the snippet is public; your api_key stays on the server. Details: Live banners.

Step 4. Test

Run the self-test checklist and ask 19flip to run a connection test against your callback_url. The connection test sends /balance with "session_id": "healthcheck"; answer it with 200.

Rules you must not skip

  • Verify the signature against the raw bytes you received. Do not parse and re-serialize the JSON before hashing.
  • Deduplicate by idempotency_key and return the same response for a repeat. 19flip retries on timeouts and 5xx, and a retry can arrive while you are still processing the first attempt.
  • Accept wins and rollbacks at any time, for any session you have ever launched – including after the player has left, after a suspension and hours after the round. Some games pay out asynchronously.
  • Signal a declined bet with a 4xx status (402 for insufficient funds), not with 200 and "status": "FAILED". Some games treat every 2xx as money moved.
  • Answer within 10 seconds. Slower answers are treated as timeouts and retried.