Operator integration

API contract

Use the provider endpoints to read the enabled catalog, request launch URLs, and keep each operator inside its assigned title list.

Base URL: http://api:8999
API key: Configured for server requests
Operator: All enabled titles

Authentication

Headers

When PROVIDER_API_KEYS is set on the backend, provider routes require one of these headers. Local development remains open when no key is configured.

x-provider-api-key<provider-api-key>

AuthorizationBearer <provider-api-key>

x-operator-idoperator-a

Catalog

Endpoint list

GET/api/provider/v1/games

Returns the operator-scoped live catalog with feature flags, launch paths, and artwork hints.

GET/api/provider/v1/games/{symbol}

Returns one catalog title by symbol or slug after the same operator access checks.

POST/api/provider/v1/launch-url

Creates or refreshes a player game session and returns the browser launch URL.

GET/api/provider/v1/operators/{operator_id}/settings

Returns operator status, wallet mode, callback URL, and default currency without exposing the secret.

PUT/api/provider/v1/operators/{operator_id}/settings

Updates operator wallet settings and rotates the callback shared secret.

Catalog response

{
  "success": true,
  "data": {
    "total": 100,
    "operator_id": "operator-a",
    "items": [
      {
        "symbol": "vs20olympgcl",
        "slug": "fortuneofolympus",
        "title": "Fortune of Olympus",
        "features": {
          "buy_feature": true,
          "special_bet": true
        },
        "launch_path": "/games/fortuneofolympus"
      }
    ]
  }
}

Launch URL

Request and response

Send a symbol or slug with the operator id and your player id. The response URL opens the selected game in the browser.

Request

curl.exe -X POST "http://api:8999/api/provider/v1/launch-url" ^
  -H "content-type: application/json" ^
  -H "x-provider-api-key: <provider-api-key>" ^
  -d "{\"symbol\":\"vs20olympgcl\",\"operator_id\":\"operator-a\",\"external_player_id\":\"player-129001\",\"coin\":\"0.10\",\"currency\":\"USD\"}"

Response

{
  "symbol": "vs20olympgcl",
  "slug": "fortuneofolympus",
  "operator_id": "operator-a",
  "currency": "USD",
  "session_id": "session-token",
  "launch_url": "http://api:8999/gs2c/html5Game.do?symbol=vs20olympgcl&mgckey=...",
  "expires_at": "2026-04-22T04:30:00+00:00",
  "success": true,
  "data": {
    "symbol": "vs20olympgcl",
    "launch_url": "http://api:8999/gs2c/html5Game.do?symbol=vs20olympgcl&mgckey=..."
  }
}

Wallet callbacks

Signed settlement calls

Operators using callback wallet mode receive JSON calls for balance, debit, credit, and rollback. Debit and credit are fail-closed: rejected or unavailable wallet calls block the game action.

POST{wallet_base_url}/balance

Signed with the operator shared secret using HMAC-SHA256.

POST{wallet_base_url}/debit

Signed with the operator shared secret using HMAC-SHA256.

POST{wallet_base_url}/credit

Signed with the operator shared secret using HMAC-SHA256.

POST{wallet_base_url}/rollback

Signed with the operator shared secret using HMAC-SHA256.

Callback body

{
  "operator_id": "operator-a",
  "player_id": "player-129001",
  "session_id": "session-token",
  "game_symbol": "vs20olympgcl",
  "currency": "USD",
  "request_id": "request-id",
  "transaction_id": "wallet-transaction-id",
  "transaction_type": "debit",
  "action_type": "doSpin",
  "amount": "2.00"
}

Signature headers

x-pp-request-id: request-id
x-pp-timestamp: 1776817800
x-pp-signature: hmac_sha256("{timestamp}.{raw_json_body}")

Operator scope

Catalog allowlist

Set PROVIDER_OPERATOR_CATALOGS to restrict each operator to approved symbols or slugs. Catalog and launch-url routes apply the same access check.

Environment value

PROVIDER_OPERATOR_CATALOGS={"operator-a":["vs20olympgcl","doghouse"]}