Integration Overview

Integrating with Game Provider has two parts:

Game Launch — your backend calls the Game Launch API to open a session and receives a launch_url you embed in the player's browser. One endpoint covers every game in the catalog (classic and server-driven).
Wallet Callbacks — you expose a small set of endpoints on your backend that Game Provider calls synchronously to authorize the player, debit bets, credit wins, return balance, and deliver rollbacks for server-driven games.

Architecture

Standard server-to-server integration.

Player's browser — loads the game served by Game Provider via the launch_url.
Game Provider platform — runs the game, drives the economy, and signs every callback with HMAC-SHA256.
Operator (you) — owns the player wallet, validates signatures, and processes transactions idempotently.

What the Operator Must Implement

Four endpoints, same for classic iframe games and server-driven games:

Endpoint	Purpose	Who sends what
`POST /auth`	Validate session + return player info	Game Provider → Operator
`POST /withdraw`	Debit a bet (`BET` or `FREE_BET`)	Game Provider → Operator
`POST /deposit`	Credit a win (`WIN`, `FREE_BET_WIN`), refund a rollback (`ROLL_BACK`), or accept a round-close notification (`CLOSE_ROUND`)	Game Provider → Operator
`POST /balance`	Return current player balance	Game Provider → Operator

For server-driven titles the /deposit endpoint carries two extra actions:

ROLL_BACK — refund of a voided bet, keyed by withdraw_provider_tx_id.
CLOSE_ROUND — a pure notification, once per (round, operator), carrying aggregated cashout-multipliers and bet-amounts for your operator's players in that round. No money moves. See Wallet API — Close Round.

See Wallet API for full request/response schemas.

Classic Iframe Game Flow

sequenceDiagram
    participant P as Player (Browser)
    participant O as Operator (Your Backend)
    participant GP as Game Provider

    P->>O: Click "Play Game"
    O->>GP: GET /api/v1/launch/{game} (userToken, currency, ...)
    GP-->>O: { launch_url, session_token }
    O-->>P: Redirect / embed launch_url
    P->>GP: Load game iframe
    GP->>O: POST /auth  (signed)
    O-->>GP: 200 { user_id, balance, currency, maxbet, ... }
    Note over P, GP: Player places a bet
    GP->>O: POST /withdraw action=BET  (signed)
    O-->>GP: 200 { new_balance }
    Note over P, GP: Round resolves
    GP->>O: POST /deposit action=WIN  (signed)
    O-->>GP: 200 { new_balance }
    GP->>O: POST /balance  (signed, periodic)
    O-->>GP: 200 { currency, amount }

Server-Driven Game Flow (e.g. Aviadrone)

Same four callbacks — with the addition that a voided bet is delivered as a /deposit with action: "ROLL_BACK".

sequenceDiagram
    participant P as Player (Browser)
    participant O as Operator (Your Backend)
    participant GP as Game Provider

    P->>O: Click "Play Aviadrone"
    O->>GP: GET /api/v1/launch/aviadrone
    GP-->>O: { launch_url, session_token }
    O-->>P: Embed launch_url
    GP->>O: POST /auth (signed)
    O-->>GP: 200 { user_id, balance, ... }
    GP->>O: POST /withdraw action=BET  (signed)
    O-->>GP: 200 { new_balance }
    alt Round settles normally
        GP->>O: POST /deposit action=WIN  (signed)
        O-->>GP: 200 { new_balance }
    else Round is voided
        GP->>O: POST /deposit action=ROLL_BACK<br/>(withdraw_provider_tx_id = original bet)
        O-->>GP: 200 { new_balance }
    end
    Note over P, GP: After every per-bet callback for this round has been ack'd
    GP->>O: POST /deposit action=CLOSE_ROUND<br/>(amount=0, aggregated per-round attributes)
    O-->>GP: 200

Integration Checklist

[ ] Obtain public key + secret key from onboarding (one pair per environment).
[ ] Expose the 4 callback endpoints at a single base URL and share it with Game Provider.
[ ] Validate X-Signature (HMAC-SHA256, Base64) on every callback — see Authentication & Security.
[ ] Dedupe by provider_tx_id on withdraw / deposit (including rollbacks) — see Idempotency.
[ ] Return proper HTTP status codes: 200 success, 400/401/402/404 terminal, 5xx retryable — see Error Handling.
[ ] Store money in millis (integer), never floats.
[ ] Handle ROLL_BACK on /deposit for server-driven games.
[ ] Handle CLOSE_ROUND on /deposit for server-driven games (ack 200, parse aviadroneCashOutCoefficients + aviadroneBets attributes, run your post-round hooks idempotently) — see Wallet API — Close Round.

Refer to the Wallet API for the detailed protocol.