# Casino Provider Operator API Version: 1.1.0 Base URL: `https://casinoproviders.net` Public operator-facing contract for catalog lookup, game launch, artwork delivery, and callback wallet settlement. Do not integrate against `/api/runtime/*` or `/gs2c/*` server-to-server; those routes are used by the launched game in the player browser. ## Operator integration flow Operators integrate through provider API endpoints only. Runtime routes under /gs2c and /api/runtime are used by the launched game in the player browser and should not be called server-to-server. - Use catalog APIs to read the operator-scoped game list. - Use launch-url to create short-lived player sessions. - Open launch_url in the player browser on desktop or mobile. - Use callback wallet endpoints for production balance and settlement. ## Use the operator API key in request headers The preferred header is x-provider-api-key. Bearer auth and x-api-key are accepted for compatibility. DB operator keys automatically resolve operator scope, so operators should not send another operator_id. ### Preferred auth header ```http x-provider-api-key: ppop_operator-a_REPLACE_ME ``` ### Bearer alternative ```http Authorization: Bearer ppop_operator-a_REPLACE_ME ``` ## Read the operator-scoped live catalog Catalog and launch use the same allowlist. A game outside the operator catalog is hidden from catalog responses and denied on launch. - `GET /api/provider/v1/games`: Returns the operator-scoped live catalog with feature flags, launch paths, and artwork URLs. - `GET /api/provider/v1/games/{symbol}`: Returns one catalog title by symbol or slug after the same operator access checks. ### List games ```bash curl -H "x-provider-api-key: " \ "https://casinoproviders.net/api/provider/v1/games" ``` ### Catalog response ```json { "success": true, "data": { "total": 1, "operator_id": "operator-a", "items": [ { "symbol": "vs20doghouse", "slug": "doghouse", "title": "The Dog House", "family": "line-free-spins", "rtp": 96.51, "lines": 20, "asset_version": "v2", "asset_symbol": "vs20doghouse", "game_service_version": "v3", "loader_mode": "generic", "launch_status": "stable", "live_catalog_enabled": true, "certified_browsers": [ "chrome" ], "features": { "bonus": true, "collect": true, "free_spins": true, "buy_feature": true, "special_bet": false }, "special_bet_profile": null, "thumbnail": { "symbol": "vs20doghouse", "slug": "doghouse", "title": "The Dog House", "url": "https://casinoproviders.net/api/provider/v1/game-art/vs20doghouse?title=The+Dog+House&slug=doghouse" }, "thumbnail_url": "https://casinoproviders.net/api/provider/v1/game-art/vs20doghouse?title=The+Dog+House&slug=doghouse", "launch_path": "/games/doghouse" } ] } } ``` ## Create a short-lived browser launch URL Create the launch URL from the operator server. Then open launch_url in the player's browser. The URL contains a short-lived session token and should not be logged publicly. - `POST /api/provider/v1/launch-url`: Creates or refreshes a player game session and returns the browser launch URL. - `symbol or slug`: One game identifier is required. - `external_player_id`: Stable player identifier from the operator platform. - `coin`: Optional default coin value. - `currency`: Optional ISO-style currency code; defaults to operator currency then USD. - `return_url`: Optional lobby URL used by the game close/return flow. - `device`: Optional desktop, mobile, or tablet hint; tablet normalizes to mobile. ### Launch request ```bash curl -X POST "https://casinoproviders.net/api/provider/v1/launch-url" \ -H "content-type: application/json" \ -H "x-provider-api-key: " \ -d '{"symbol":"vs20doghouse","external_player_id":"player-129001","coin":"0.10","currency":"USD","return_url":"https://operator.example.com/lobby","device":"desktop"}' ``` ### Launch response ```json { "success": true, "symbol": "vs20doghouse", "slug": "doghouse", "operator_id": "operator-a", "currency": "USD", "session_id": "session-token", "launch_url": "https://casinoproviders.net/gs2c/html5Game.do?symbol=vs20doghouse&mgckey=...", "expires_at": "2026-06-16T16:30:00+00:00", "data": { "symbol": "vs20doghouse", "slug": "doghouse", "operator_id": "operator-a", "currency": "USD", "session_id": "session-token", "launch_url": "https://casinoproviders.net/gs2c/html5Game.do?symbol=vs20doghouse&mgckey=...", "expires_at": "2026-06-16T16:30:00+00:00" } } ``` ## Use catalog artwork URLs for game thumbnails Catalog responses include thumbnail and thumbnail_url fields. The artwork endpoint is public and returns uploaded WebP, PNG, JPEG, or an SVG fallback. - `GET /api/provider/v1/game-art/{symbol}`: Returns public game artwork used by catalog thumbnail URLs. ### Fetch artwork ```bash curl "https://casinoproviders.net/api/provider/v1/game-art/vs20doghouse?title=The+Dog+House&slug=doghouse" ``` ## Expose signed balance, debit, credit, and rollback endpoints Callback wallet mode calls endpoints under the operator wallet_base_url. PP_Platform signs the exact raw JSON body with HMAC-SHA256. - `POST {wallet_base_url}/balance`: Operator-hosted callback endpoint signed with HMAC-SHA256. - `POST {wallet_base_url}/debit`: Operator-hosted callback endpoint signed with HMAC-SHA256. - `POST {wallet_base_url}/credit`: Operator-hosted callback endpoint signed with HMAC-SHA256. - `POST {wallet_base_url}/rollback`: Operator-hosted callback endpoint signed with HMAC-SHA256. - Treat transaction_id as the idempotency key. - Return the original result for duplicate successful transaction IDs. - Fail closed on invalid signature, stale timestamp, insufficient funds, or unknown player. - Rollback callbacks include original_transaction_id. - If debit succeeds and a later settlement step fails, PP_Platform attempts a best-effort rollback. ### Callback headers ```http content-type: application/json x-pp-request-id: x-pp-timestamp: x-pp-signature: ``` ### Signature payload ```text HMAC_SHA256(wallet_secret, "{timestamp}.{raw_json_body}") ``` ### Callback request ```json { "operator_id": "operator-a", "player_id": "player-129001", "session_id": "session-token", "game_symbol": "vs20doghouse", "currency": "USD", "request_id": "7d8a3996269f4cf3bb9f5aa6f65de3c1", "transaction_id": "session-token:doSpin:0:1:debit", "transaction_type": "debit", "action_type": "doSpin", "amount": "2.00" } ``` ### Success response ```json { "success": true, "balance": "997.90", "currency": "USD", "transaction_id": "session-token:doSpin:0:1:debit" } ``` ### Reject response ```json { "success": false, "error": "insufficient_funds", "message": "Insufficient funds" } ``` ## Handle JSON errors by HTTP status Provider API errors are returned as JSON. Operators should log request IDs and response detail fields during integration testing. - `400`: Missing required launch field or invalid request. - `401`: Missing or invalid API key. - `403`: Inactive operator or game not enabled for this operator. - `404`: Game not found. - `500`: Production/staging environment is missing valid HTTPS GAME_BASE_URL or another server configuration is invalid. ### Error response ```json { "success": false, "detail": "Operator is not active" } ``` ## Go-live checklist Complete these checks before sending production traffic through a new operator integration. - [ ] Health endpoint returns 200. - [ ] Public GAME_BASE_URL uses HTTPS. - [ ] Operator status is active. - [ ] Operator catalog contains the expected games. - [ ] Operator API key works for catalog and launch. - [ ] Browser can open launch_url on desktop and mobile. - [ ] Callback wallet signature verification passes. - [ ] Balance, debit, credit, and rollback callbacks pass diagnostics. - [ ] Operator confirms idempotency behavior for duplicate transaction_id. - [ ] Operator confirms game close/return flow with return_url. ## Downloads - OpenAPI JSON: https://docs.casinoproviders.net/openapi.json - Postman collection: https://docs.casinoproviders.net/postman.json - PDF guide: https://docs.casinoproviders.net/downloads/operator-api-guide.pdf