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.

For embedded games, the Operator frontend can also receive Iframe Events. The game.closeRequested event lets the Operator close the game and choose its own redirect when the player selects Leave. This browser channel is independent of the launch and wallet APIs and needs no additional backend endpoint.

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.
[ ] If integrating the game's Leave action, register an iframe event listener before loading the game, validate the sending origin and iframe, and handle game.closeRequested on the Operator frontend.

Refer to the Wallet API for the detailed protocol.