Getting started/Quickstart

Quickstart

Four steps from a Test key to going live: get your key, connect the callbacks, run the test suite, go live. In the code samples, BOSS_API_URL is the API address shown for the selected environment on the Integration & API page of the portal, and BOSS_SECRET is your signing secret.

1. Get your key

Your Test API key is created automatically when your account opens. Sign in to the portal (its address is sent to you when your account opens; first an access code sent to your email, then the Boss Hub sign-in), choose Test in the top bar and open Developers › Integration & API. The secret is shown only once, on first view; if you lose it, rotate it.

Item	Example	Where it is used
Operator ID	op_meridyen	X-Operator-Id header
Site code	site_mrd01	site_id in the request body if you have several sites
API key	pk_test_••••8f2a	Optional X-Api-Key header
Signing secret	••••••••	X-Signature calculation, see Authentication & signing

2. Connect the callbacks

Enter your address in the Callback base URL field of the Endpoints & wallet card in the portal, e.g. https://staging-api.meridyen.example/bossgaming. Boss Hub appends five paths to it. Check the address with Test connection. Your callbacks come from the Boss Hub egress IPs; the addresses are on the IP allowlist card.

Path	Job	Page
/authenticate	Verifies the player token; returns the player and balance	authenticate
/balance	Returns the current balance	balance
/bet	Debits the bet from the balance	bet
/win	Credits the winnings to the balance	win
/rollback	Reverses a bet or a win	rollback

Three rules: Reply within 3 s, always with HTTP 200 (an error too: status: ERROR + code). When a transaction_id repeats with the same body, return the first result as is; with a different body, answer DUPLICATE_TRANSACTION. Answer OK to an unknown rollback and record it.

Open a game

Once the callbacks are ready, open a game session in the Test environment to try the flow end to end. Take game_id from the game list (GET /v1/games) and use a currency your site supports. The returned launch_url is single-use and valid for 60 s by default. All fields: Game launch.

BODY='{"game_id":"10-burning-heart","site_id":"site_mrd01","player_id":"u_88213","token":"tok_8f2a6c41","currency":"TRY","language":"tr"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.POST./v1/game/launch.$BODY" | openssl dgst -sha256 -hmac "$BOSS_SECRET" -hex | awk '{print $NF}')

curl -X POST "$BOSS_API_URL/v1/game/launch" \
  -H "Content-Type: application/json" \
  -H "X-Operator-Id: op_meridyen" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "X-Request-Id: launch-$TS-$RANDOM" \
  -d "$BODY"

200Session opened

{
  "launch_url": "https://api.example.com/s/7Hq…",
  "session_id": "ses_01HF3K7M",
  "expires_in": 60,
  "limits": {
    "currency": "TRY",
    "min_bet": 1.00,
    "max_bet": 500.00,
    "default_bet": 5.00,
    "source": { "min_bet": "provider", "max_bet": "provider" }
  }
}

3. Run the test suite

On the Integration test suite card of the portal, first enter the Test data (test player, valid and expired token, blocked and limited player), then press Run again. The suite runs 42 scenarios, including timeouts, retries and insufficient balance, against your real Test wallet. The result arrives as a portal notification and by email. The list: Test suite scenarios.

4. Go live

The latest test run must be 42/42 PASS; a WARN blocks too.
Choose Live in the top bar and add at least one address to the IP allowlist; Live requests are rejected while the list is empty.
Press Request production; Boss Hub checks your company documents and approves the request.
After approval, create your Live key (pk_live_), enter your Live callback address, set your site to Live and switch BOSS_API_URL to the API address shown with Live selected in the portal. Details: Going live.

Per provider: A provider’s Go live button opens once the latest test run has fully passed; on Live, only games of providers taken live can be opened. See Environments & IP allowlist.

← PreviousOverview Next →Authentication & signing