{"openapi":"3.1.0","info":{"title":"Casino Provider Operator API","version":"1.1.0","description":"Public operator-facing contract for catalog lookup, game launch, artwork, and callback wallet integration. Internal admin and runtime spin endpoints are intentionally excluded."},"servers":[{"url":"https://casinoproviders.net"}],"tags":[{"name":"Health","description":"Service reachability."},{"name":"Catalog","description":"Operator-scoped live game catalog."},{"name":"Launch","description":"Short-lived game launch URL creation."},{"name":"Artwork","description":"Public thumbnail/artwork delivery."},{"name":"Wallet callbacks","description":"Endpoints hosted by the operator when callback wallet mode is enabled."}],"security":[{"ProviderApiKey":[]},{"LegacyApiKey":[]},{"BearerApiKey":[]}],"components":{"securitySchemes":{"ProviderApiKey":{"type":"apiKey","in":"header","name":"x-provider-api-key","description":"Preferred header. Use the operator API key created in Provider Admin."},"LegacyApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Accepted compatibility header for the same operator API key."},"BearerApiKey":{"type":"http","scheme":"bearer","description":"Alternative bearer form for the same operator API key."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"detail":{"type":"string","examples":["Operator is not active"]},"error":{"type":"string"},"message":{"type":"string"}}},"FeatureFlags":{"type":"object","required":["bonus","collect","free_spins","buy_feature","special_bet"],"properties":{"bonus":{"type":"boolean"},"collect":{"type":"boolean"},"free_spins":{"type":"boolean"},"buy_feature":{"type":"boolean"},"special_bet":{"type":"boolean"}}},"SpecialBetProfile":{"type":"object","properties":{"symbol":{"type":"string"},"buttons":{"type":"integer"},"bls":{"type":"array","items":{"type":"integer"}},"default_bl":{"type":"integer"},"service_version":{"type":"string"},"cver":{"type":"string"}}},"Thumbnail":{"type":"object","properties":{"symbol":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Game":{"type":"object","required":["symbol","slug","title","features","launch_path"],"properties":{"symbol":{"type":"string","examples":["vs20doghouse"]},"slug":{"type":"string","examples":["doghouse"]},"title":{"type":"string","examples":["The Dog House"]},"family":{"type":"string","examples":["line-free-spins"]},"rtp":{"oneOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"lines":{"type":"integer","examples":[20]},"asset_version":{"type":"string","examples":["v2"]},"asset_symbol":{"type":"string","examples":["vs20doghouse"]},"asset_source":{"type":"string","examples":["local"]},"has_local_assets":{"type":"boolean"},"game_service_version":{"type":"string","examples":["v3"]},"loader_mode":{"type":"string","examples":["generic"]},"provider_tagline":{"type":"string"},"shell_strategy":{"type":"string"},"launch_status":{"type":"string","examples":["stable"]},"live_catalog_enabled":{"type":"boolean"},"certified_browsers":{"type":"array","items":{"type":"string"}},"features":{"$ref":"#/components/schemas/FeatureFlags"},"special_bet_profile":{"oneOf":[{"$ref":"#/components/schemas/SpecialBetProfile"},{"type":"null"}]},"thumbnail":{"$ref":"#/components/schemas/Thumbnail"},"thumbnail_url":{"type":"string","format":"uri"},"launch_path":{"type":"string","examples":["/games/doghouse"]}}},"CatalogResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Game"}},"total":{"type":"integer"},"operator_id":{"type":["string","null"]}}}}},"GameResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Game"}}},"LaunchUrlRequest":{"type":"object","required":["external_player_id"],"anyOf":[{"required":["symbol"]},{"required":["slug"]}],"properties":{"symbol":{"type":"string","examples":["vs20doghouse"]},"slug":{"type":"string","examples":["doghouse"]},"operator_id":{"type":"string","description":"Only required for provider master keys. Operator API keys resolve scope automatically.","examples":["operator-a"]},"external_player_id":{"type":"string","description":"Stable player identifier from the operator platform.","examples":["player-129001"]},"coin":{"type":"string","description":"Optional default coin value for the session.","examples":["0.10"]},"currency":{"type":"string","minLength":3,"maxLength":3,"examples":["USD"]},"return_url":{"type":"string","format":"uri","examples":["https://operator.example.com/lobby"]},"device":{"type":"string","enum":["desktop","mobile","tablet"],"description":"Optional launch hint. tablet is normalized to mobile.","examples":["desktop"]}}},"LaunchUrlData":{"type":"object","required":["symbol","slug","currency","session_id","launch_url","expires_at"],"properties":{"symbol":{"type":"string","examples":["vs20doghouse"]},"slug":{"type":"string","examples":["doghouse"]},"operator_id":{"type":["string","null"],"examples":["operator-a"]},"currency":{"type":"string","examples":["USD"]},"session_id":{"type":"string","examples":["session-token"]},"launch_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}},"LaunchUrlResponse":{"allOf":[{"$ref":"#/components/schemas/LaunchUrlData"},{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/LaunchUrlData"}}}]},"WalletCallbackRequest":{"type":"object","required":["operator_id","player_id","session_id","game_symbol","currency","request_id","transaction_id","transaction_type","action_type","amount"],"properties":{"operator_id":{"type":"string","examples":["operator-a"]},"player_id":{"type":"string","examples":["player-129001"]},"session_id":{"type":"string","examples":["session-token"]},"game_symbol":{"type":"string","examples":["vs20doghouse"]},"currency":{"type":"string","examples":["USD"]},"request_id":{"type":"string"},"transaction_id":{"type":"string","description":"Stable idempotency key. Return the original result when this repeats."},"transaction_type":{"type":"string","enum":["balance","debit","credit","rollback"]},"action_type":{"type":"string","examples":["doSpin","balance"]},"amount":{"type":"string","examples":["2.00"]},"original_transaction_id":{"type":"string","description":"Present only on rollback callbacks."}}},"WalletSuccessResponse":{"type":"object","required":["success","balance"],"properties":{"success":{"type":"boolean","const":true},"balance":{"type":"string","examples":["997.90"]},"currency":{"type":"string","examples":["USD"]},"transaction_id":{"type":"string"}}},"WalletErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","examples":["insufficient_funds"]},"message":{"type":"string","examples":["Insufficient funds"]}}}}},"paths":{"/health":{"get":{"tags":["Health"],"security":[],"summary":"Check service health","responses":{"200":{"description":"Service is reachable"}}}},"/api/provider/v1/games":{"get":{"tags":["Catalog"],"summary":"List operator-scoped live games","description":"DB operator API keys automatically resolve operator scope. Provider master keys may pass operator_id or x-operator-id when testing a specific operator catalog.","parameters":[{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional for provider master keys only."}],"responses":{"200":{"description":"Live catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"},"examples":{"catalog":{"value":{"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"}]}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"500":{"description":"Strict environment is missing a valid HTTPS GAME_BASE_URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}}}}},"/api/provider/v1/games/{symbol}":{"get":{"tags":["Catalog"],"summary":"Get one operator-scoped game","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Game symbol or slug."}],"responses":{"200":{"description":"Game detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameResponse"},"examples":{"game":{"value":{"success":true,"data":{"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"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"404":{"description":"Game not found or not in operator catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"500":{"description":"Strict environment is missing a valid HTTPS GAME_BASE_URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}}}}},"/api/provider/v1/game-art/{symbol}":{"get":{"tags":["Artwork"],"security":[],"summary":"Fetch game thumbnail/artwork","description":"Catalog responses include this URL. If no uploaded thumbnail exists, the API returns an SVG fallback.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"}},{"name":"title","in":"query","required":false,"schema":{"type":"string"}},{"name":"slug","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Image bytes","content":{"image/webp":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/api/provider/v1/launch-url":{"post":{"tags":["Launch"],"summary":"Create a browser launch URL","description":"Creates or refreshes a short-lived game session. The returned launch_url is opened in the player browser. Operators must not call /api/runtime or /gs2c routes server-to-server.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchUrlRequest"},"examples":{"launch":{"value":{"symbol":"vs20doghouse","external_player_id":"player-129001","coin":"0.10","currency":"USD","return_url":"https://operator.example.com/lobby","device":"desktop"}}}}}},"responses":{"200":{"description":"Launch URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchUrlResponse"},"examples":{"launch":{"value":{"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"}}}}}}},"400":{"description":"Invalid launch request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or game not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"404":{"description":"Game not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}},"500":{"description":"Strict environment is missing a valid HTTPS GAME_BASE_URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"success":false,"detail":"Operator is not active"}}}}}}}}}},"webhooks":{"walletBalance":{"post":{"tags":["Wallet callbacks"],"summary":"Receive balance wallet callback","description":"This endpoint is hosted by the operator under wallet_base_url. PP_Platform signs the exact raw JSON body with HMAC-SHA256.","parameters":[{"name":"x-pp-request-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCallbackRequest"},"examples":{"callback":{"value":{"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":"balance","action_type":"balance","amount":"0.00"}}}}}},"responses":{"200":{"description":"Callback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSuccessResponse"},"examples":{"success":{"value":{"success":true,"balance":"997.90","currency":"USD","transaction_id":"session-token:doSpin:0:1:debit"}}}}}},"400":{"description":"Rejected wallet transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"rejected":{"value":{"success":false,"error":"insufficient_funds","message":"Insufficient funds"}}}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"invalidSignature":{"value":{"success":false,"error":"invalid_signature"}}}}}}}}},"walletDebit":{"post":{"tags":["Wallet callbacks"],"summary":"Receive debit wallet callback","description":"This endpoint is hosted by the operator under wallet_base_url. PP_Platform signs the exact raw JSON body with HMAC-SHA256.","parameters":[{"name":"x-pp-request-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCallbackRequest"},"examples":{"callback":{"value":{"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"}}}}}},"responses":{"200":{"description":"Callback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSuccessResponse"},"examples":{"success":{"value":{"success":true,"balance":"997.90","currency":"USD","transaction_id":"session-token:doSpin:0:1:debit"}}}}}},"400":{"description":"Rejected wallet transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"rejected":{"value":{"success":false,"error":"insufficient_funds","message":"Insufficient funds"}}}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"invalidSignature":{"value":{"success":false,"error":"invalid_signature"}}}}}}}}},"walletCredit":{"post":{"tags":["Wallet callbacks"],"summary":"Receive credit wallet callback","description":"This endpoint is hosted by the operator under wallet_base_url. PP_Platform signs the exact raw JSON body with HMAC-SHA256.","parameters":[{"name":"x-pp-request-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCallbackRequest"},"examples":{"callback":{"value":{"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":"credit","action_type":"doSpin","amount":"2.00"}}}}}},"responses":{"200":{"description":"Callback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSuccessResponse"},"examples":{"success":{"value":{"success":true,"balance":"997.90","currency":"USD","transaction_id":"session-token:doSpin:0:1:debit"}}}}}},"400":{"description":"Rejected wallet transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"rejected":{"value":{"success":false,"error":"insufficient_funds","message":"Insufficient funds"}}}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"invalidSignature":{"value":{"success":false,"error":"invalid_signature"}}}}}}}}},"walletRollback":{"post":{"tags":["Wallet callbacks"],"summary":"Receive rollback wallet callback","description":"This endpoint is hosted by the operator under wallet_base_url. PP_Platform signs the exact raw JSON body with HMAC-SHA256.","parameters":[{"name":"x-pp-request-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-pp-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCallbackRequest"},"examples":{"callback":{"value":{"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":"rollback","action_type":"doSpin","amount":"2.00","original_transaction_id":"session-token:doSpin:0:1:debit"}}}}}},"responses":{"200":{"description":"Callback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSuccessResponse"},"examples":{"success":{"value":{"success":true,"balance":"997.90","currency":"USD","transaction_id":"session-token:doSpin:0:1:debit"}}}}}},"400":{"description":"Rejected wallet transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"rejected":{"value":{"success":false,"error":"insufficient_funds","message":"Insufficient funds"}}}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletErrorResponse"},"examples":{"invalidSignature":{"value":{"success":false,"error":"invalid_signature"}}}}}}}}}}}