{"openapi":"3.1.0","info":{"title":"Golden Casino Operator API","version":"2.0.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://goldencasino.cloud"}],"tags":[{"name":"Health","description":"Service reachability."},{"name":"Catalog","description":"Operator-scoped live game catalog."},{"name":"Launch","description":"Game launch and PP balance refresh."},{"name":"History","description":"Operator-scoped native Play'n GO history."},{"name":"Audit","description":"Provider-neutral operator session, round, transaction and reconciliation records."},{"name":"Artwork","description":"Public thumbnail/artwork delivery."},{"name":"Wallet callbacks","description":"Endpoints hosted by the operator when callback wallet mode is enabled."}],"security":[{"ProviderApiKey":[],"OperatorTimestamp":[],"OperatorNonce":[],"OperatorSignature":[]}],"components":{"securitySchemes":{"ProviderApiKey":{"type":"apiKey","in":"header","name":"x-provider-api-key","description":"Preferred header. Use the operator API key created in Provider Admin."},"OperatorTimestamp":{"type":"apiKey","in":"header","name":"x-pp-timestamp","description":"Current Unix seconds; requests outside the configured skew are rejected."},"OperatorNonce":{"type":"apiKey","in":"header","name":"x-pp-nonce","description":"Unique per API-key request. Reuse is rejected across API workers."},"OperatorSignature":{"type":"apiKey","in":"header","name":"x-pp-signature","description":"HMAC-SHA256 over the versioned canonical operator request payload."},"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":{"OperatorContract":{"type":"object","required":["operator_id","version","amount_unit","allowed_currencies","bet_limits","wallet_callbacks"],"properties":{"operator_id":{"type":"string"},"version":{"type":"string","const":"2026-09-01"},"amount_unit":{"type":"string","const":"minor"},"allowed_currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$"}},"bet_limits":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}}},"wallet_callbacks":{"type":"array","items":{"type":"string","enum":["balance","debit","credit","cancel","rollback"]}},"idempotency_key":{"type":"string","const":"transaction_id"}}},"OperatorTransaction":{"type":"object","required":["transaction_id","operator_id","session_id","round_id","player_id","game_symbol","transaction_type","amount_minor","currency","status","contract_version","request_hash"],"properties":{"transaction_id":{"type":"string"},"operator_id":{"type":"string"},"session_id":{"type":"string"},"round_id":{"type":"string"},"player_id":{"type":"string"},"game_symbol":{"type":"string"},"transaction_type":{"type":"string","enum":["balance","debit","credit","cancel","rollback"]},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"status":{"type":"string","enum":["pending","success","failed"]},"contract_version":{"type":"string","const":"2026-09-01"},"request_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"detail":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object"}}],"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","provider_id","provider","features","launch_path"],"properties":{"symbol":{"type":"string","examples":["vs20doghouse"]},"slug":{"type":"string","examples":["doghouse"]},"title":{"type":"string","examples":["The Dog House"]},"provider_id":{"type":"string","examples":["pragmatic","pg"],"description":"Stable machine-readable provider id. Use this to group games by provider."},"provider":{"type":"string","examples":["Pragmatic Play","PG Soft"],"description":"Human-readable provider display name."},"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","null"],"examples":["/games/doghouse"]},"operator_integration":{"$ref":"#/components/schemas/OperatorIntegration"},"operator_availability":{"$ref":"#/components/schemas/OperatorAvailability"},"release_readiness":{"$ref":"#/components/schemas/ReleaseReadiness"}}},"OperatorAvailability":{"type":"object","required":["enabled","assigned","configuration_ready","launch_available","blockers"],"properties":{"enabled":{"type":"boolean"},"assigned":{"type":["boolean","null"]},"configuration_ready":{"type":["boolean","null"]},"launch_available":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string","enum":["release_acceptance","disabled","transport_unavailable","unassigned","operator_configuration","operator_scope_required"]}}},"description":"Per-operator transport eligibility, not production approval. Admin views retain blocked assigned games; operator catalogs omit them."},"ReleaseReadiness":{"type":"object","required":["status","accepted","registry_version","detail","reasons","evidence","deployment_identity"],"properties":{"status":{"type":"string","enum":["accepted","blocked"]},"accepted":{"type":"boolean"},"registry_version":{"type":"string","examples":["m5b-20260921"]},"detail":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"string"}},"deployment_identity":{"type":["string","null"]}},"description":"Exact version status from the fail-closed game release registry. Accepted means eligible for integrated staging and operator assignment; production still requires the remaining platform gates."},"NativeSessionHistory":{"type":"object","required":["session_id","currency","stages","mode"],"properties":{"session_id":{"type":"string"},"currency":{"type":"string"},"stages":{"type":"array","items":{"type":"object"}},"mode":{"type":"string","enum":["operator-wallet","sandbox-only"]}}},"NativeRoundHistory":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","required":["round_id","session_id","operator_id","currency","mode","intent","status","stages","ledger","wallet"],"properties":{"round_id":{"type":"string"},"session_id":{"type":"string"},"operator_id":{"type":"string"},"currency":{"type":"string"},"mode":{"type":"string"},"intent":{"type":"object"},"status":{"type":"string"},"stages":{"type":"array","items":{"type":"object"}},"ledger":{"type":"array","items":{"type":"object"}},"wallet":{"type":"array","items":{"type":"object"}}}}}},"OperatorIntegration":{"type":"object","required":["mode","wallet_callback","balance_refresh"],"properties":{"mode":{"type":"string","enum":["operator-wallet","demo-only","sandbox-only"]},"wallet_callback":{"type":"boolean"},"balance_refresh":{"type":"boolean"}},"description":"Transport support only, not certification of replay data, RTP or production readiness."},"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"]},"provider_id":{"type":["string","null"],"description":"Canonical provider filter applied to this response, or null when unfiltered.","examples":["pragmatic","pg"]}}}}},"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","minLength":1,"maxLength":64,"description":"Stable operator-prefixed player ID without surrounding whitespace. PP/PG/native Play'n GO reject cross-operator reuse with 409; Crash isolates by operator and currency.","examples":["operator-a:player-129001"]},"coin":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}],"description":"Optional finite positive PP/PG coin value. Native Play'n GO and Crash choose actual stakes in-game.","examples":["0.10"]},"currency":{"type":"string","minLength":3,"maxLength":3,"examples":["USD"],"description":"Slots accept three-letter codes subject to wallet/client acceptance. Aviator: USD only. Chicken: USD/EUR/GBP. Crash must match the operator's configured default currency."},"lang":{"type":"string","description":"Optional game language code. Use tr for Turkish.","examples":["en","tr"]},"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","contract_version","amount_unit"],"properties":{"symbol":{"type":"string","examples":["vs20doghouse"]},"slug":{"type":"string","examples":["doghouse"]},"operator_id":{"type":["string","null"],"examples":["operator-a"]},"currency":{"type":"string","examples":["USD"]},"lang":{"type":"string","examples":["en","tr"]},"session_id":{"type":"string","examples":["session-token"]},"launch_url":{"type":"string","format":"uri"},"expires_at":{"type":["string","null"],"format":"date-time","description":"PP/PG: inactivity deadline extended by runtime activity, nullable if disabled. Native Play'n GO: 30-minute play-session deadline, distinct from the five-minute signed launch grant; unfinished-round relaunch may retain the original expired session deadline. Crash: five-minute signed login grant; authenticated PostgreSQL session authorization lasts one hour unless revoked. Retry launch to resume; expiry never authorizes an extra debit or refund."},"contract_version":{"type":"string","const":"2026-09-01"},"amount_unit":{"type":"string","const":"minor"},"provider_session_id":{"type":["string","null"]},"test_launch":{"type":"boolean"},"operator_integration":{"$ref":"#/components/schemas/OperatorIntegration"}}},"LaunchUrlResponse":{"allOf":[{"$ref":"#/components/schemas/LaunchUrlData"},{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/LaunchUrlData"}}}]},"BalanceRefreshRequest":{"type":"object","required":["external_player_id"],"properties":{"external_player_id":{"type":"string","minLength":1,"maxLength":64,"description":"Globally unique operator-prefixed player ID, sent unchanged in callbacks. Cross-operator reuse returns 409.","examples":["operator-a:player-129001"]},"operator_id":{"type":"string","description":"Only for provider master keys. Operator API keys resolve scope automatically.","examples":["operator-a"]},"currency":{"type":"string","minLength":3,"maxLength":3,"examples":["USD"]},"game_symbol":{"type":"string","examples":["vs20doghouse"]},"session_id":{"type":"string","examples":["session-token"]},"request_id":{"type":"string","examples":["operator-request-123"]},"reason":{"type":"string","examples":["deposit","manual_adjustment"]}}},"BalanceRefreshResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"operator_id":{"type":"string","examples":["operator-a"]},"external_player_id":{"type":"string","examples":["operator-a:player-129001"]},"request_id":{"type":"string"},"reason":{"type":"string"},"sessions_found":{"type":"integer"},"sessions_notified":{"type":"integer"},"subscribers_notified":{"type":"integer"},"sessions":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"game_symbol":{"type":"string"},"currency":{"type":"string"},"active_subscribers":{"type":"integer"},"notified":{"type":"boolean"}}}},"data":{"type":"object"}}},"WalletCallbackRequest":{"type":"object","required":["operator_id","contract_version","player_id","session_id","game_symbol","currency","request_id","transaction_id","round_id","transaction_type","action_type","amount","amount_minor"],"properties":{"contract_version":{"type":"string","const":"2026-09-01"},"operator_id":{"type":"string","examples":["operator-a"]},"player_id":{"type":"string","examples":["operator-a: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."},"round_id":{"type":"string","description":"Stable provider round identity."},"transaction_type":{"type":"string","enum":["balance","debit","credit","cancel","rollback"]},"action_type":{"type":"string","examples":["doSpin","balance"]},"amount":{"type":"number","format":"decimal","examples":[2]},"amount_minor":{"type":"integer","format":"int64","examples":[200],"description":"Canonical integer minor-unit amount."},"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."},{"name":"provider_id","in":"query","required":false,"schema":{"type":"string","examples":["pragmatic","pg","playngo","spribe"]},"description":"Canonical IDs: pragmatic, pg, playngo, spribe. Unknown/unavailable providers return an empty list. PG, native Play'n GO and Crash operator modes are explicitly gated and default-off. Only enabled titles assigned to the authenticated operator are available. Crash is a lobby label, not a provider ID."}],"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","provider_id":null,"items":[{"symbol":"vs20doghouse","slug":"doghouse","title":"The Dog House","provider_id":"pragmatic","provider":"Pragmatic Play","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://goldencasino.cloud/api/provider/v1/game-art/vs20doghouse?title=The+Dog+House&slug=doghouse"},"thumbnail_url":"https://goldencasino.cloud/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":{"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"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":{"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","provider_id":"pragmatic","provider":"Pragmatic Play","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://goldencasino.cloud/api/provider/v1/game-art/vs20doghouse?title=The+Dog+House&slug=doghouse"},"thumbnail_url":"https://goldencasino.cloud/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":{"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"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":{"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":{"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"}},{"name":"provider_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"},"description":"Selects the operator's artwork format preference, not authorization."},{"name":"thumbnail_format","in":"query","required":false,"schema":{"type":"string","enum":["vertical","horizontal"]}}],"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 resumes a session. Unfinished rounds retain the original coin for PP/PG and their original wager and currency for native Play'n GO. PP/PG expires_at describes inactivity; native Play'n GO has a separate five-minute signed browser grant and 30-minute session. Request a fresh launch URL after a grant expires, without changing an unfinished wager. Open the returned URL unchanged in the browser. Disabled or demo-only provider modes reject operator-wallet launches.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchUrlRequest"},"examples":{"launch":{"value":{"symbol":"vs20doghouse","external_player_id":"operator-a:player-129001","coin":"0.10","currency":"USD","lang":"en","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","lang":"en","session_id":"session-token","contract_version":"2026-09-01","amount_unit":"minor","launch_url":"https://goldencasino.cloud/gs2c/html5Game.do?symbol=vs20doghouse&lang=en&mgckey=...","expires_at":"2026-06-16T16:30:00+00:00","data":{"symbol":"vs20doghouse","slug":"doghouse","operator_id":"operator-a","currency":"USD","lang":"en","session_id":"session-token","contract_version":"2026-09-01","amount_unit":"minor","launch_url":"https://goldencasino.cloud/gs2c/html5Game.do?symbol=vs20doghouse&lang=en&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":{"detail":"Operator is not active"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or game not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Game not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"409":{"description":"Player scope conflict, unfinished-round currency conflict or unsupported provider integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"422":{"description":"Request body validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"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":{"detail":"Operator is not active"}}}}}},"502":{"description":"Provider runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"503":{"description":"Provider runtime not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/provider/v1/player-balance-refresh":{"post":{"tags":["Launch"],"summary":"Refresh active game session balance","description":"Signals matching active game pages to run the native PP balance refresh. The endpoint does not accept or set balance values; the displayed balance still comes from the signed wallet balance callback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceRefreshRequest"},"examples":{"refresh":{"value":{"external_player_id":"operator-a:player-129001","currency":"USD","reason":"deposit","request_id":"operator-request-123"}}}}}},"responses":{"200":{"description":"Refresh signal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceRefreshResponse"},"examples":{"refresh":{"value":{"success":true,"operator_id":"operator-a","external_player_id":"operator-a:player-129001","request_id":"operator-request-123","reason":"deposit","sessions_found":1,"sessions_notified":1,"subscribers_notified":1,"sessions":[{"session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","active_subscribers":1,"notified":true}],"data":{"operator_id":"operator-a","external_player_id":"operator-a:player-129001","request_id":"operator-request-123","reason":"deposit","sessions_found":1,"sessions_notified":1,"subscribers_notified":1,"sessions":[{"session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","active_subscribers":1,"notified":true}]}}}}}}},"400":{"description":"Invalid refresh request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Operator inactive or wrong operator key scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Operator or game not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"409":{"description":"Provider does not support live balance refresh","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"422":{"description":"Request body validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/provider/v1/playngo/history":{"get":{"tags":["History"],"summary":"Read native Play'n GO session history","description":"Requires an enabled native service and the owning operator's key. Provider keys must supply operator_id. This is not an admin recovery operation.","parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session history without a success/data wrapper","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeSessionHistory"}}}},"400":{"description":"Missing operator scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Another operator's session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Session, service or round not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"422":{"description":"Missing or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/provider/v1/playngo/history/{round_id}":{"get":{"tags":["History"],"summary":"Read a native Play'n GO round","description":"Requires an enabled native service and the owning operator's key. Provider keys must supply operator_id. This is not an admin recovery operation.","parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"round_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recorded round detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeRoundHistory"}}}},"400":{"description":"Missing operator scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Another operator's session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Session, service or round not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"422":{"description":"Missing or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/contract":{"get":{"tags":["Audit"],"summary":"Read the active operator contract and limits","parameters":[],"responses":{"200":{"description":"Operator-scoped result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/OperatorContract"}}}}}},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/sessions/{session_id}":{"get":{"tags":["Audit"],"summary":"Read one owned session","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/transactions":{"get":{"tags":["Audit"],"summary":"Search owned wallet transactions","parameters":[],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/transactions/{transaction_id}":{"get":{"tags":["Audit"],"summary":"Read one owned wallet transaction","parameters":[{"name":"transaction_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operator-scoped result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/OperatorTransaction"}}}}}},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/rounds":{"get":{"tags":["Audit"],"summary":"Search owned game rounds","parameters":[],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/rounds/{round_id}":{"get":{"tags":["Audit"],"summary":"Read one owned round and its transactions","parameters":[{"name":"round_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/reconciliation":{"get":{"tags":["Audit"],"summary":"Compare wallet and game totals by currency","parameters":[],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}}}}},"/api/operator/v1/reconciliation.csv":{"get":{"tags":["Audit"],"summary":"Export reconciliation totals as CSV","parameters":[],"responses":{"200":{"description":"Operator-scoped result"},"401":{"description":"Missing or invalid signed operator credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"403":{"description":"Attempted cross-operator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"detail":"Operator is not active"}}}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"error":{"value":{"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-nonce","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":{"contract_version":"2026-09-01","operator_id":"operator-a","player_id":"operator-a:player-129001","session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","request_id":"7d8a3996269f4cf3bb9f5aa6f65de3c1","transaction_id":"session-token:doSpin:0:1:debit","round_id":"round-01K5JQ7E4F1F5Y6Y2N1R4W9C0A","transaction_type":"balance","action_type":"balance","amount":0,"amount_minor":0}}}}}},"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-nonce","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":{"contract_version":"2026-09-01","operator_id":"operator-a","player_id":"operator-a:player-129001","session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","request_id":"7d8a3996269f4cf3bb9f5aa6f65de3c1","transaction_id":"session-token:doSpin:0:1:debit","round_id":"round-01K5JQ7E4F1F5Y6Y2N1R4W9C0A","transaction_type":"debit","action_type":"doSpin","amount":2,"amount_minor":200}}}}}},"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-nonce","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":{"contract_version":"2026-09-01","operator_id":"operator-a","player_id":"operator-a:player-129001","session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","request_id":"7d8a3996269f4cf3bb9f5aa6f65de3c1","transaction_id":"session-token:doSpin:0:1:debit","round_id":"round-01K5JQ7E4F1F5Y6Y2N1R4W9C0A","transaction_type":"credit","action_type":"doSpin","amount":2,"amount_minor":200}}}}}},"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"}}}}}}}}},"walletCancel":{"post":{"tags":["Wallet callbacks"],"summary":"Receive cancel 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-nonce","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":{"contract_version":"2026-09-01","operator_id":"operator-a","player_id":"operator-a:player-129001","session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","request_id":"7d8a3996269f4cf3bb9f5aa6f65de3c1","transaction_id":"session-token:doSpin:0:1:debit","round_id":"round-01K5JQ7E4F1F5Y6Y2N1R4W9C0A","transaction_type":"cancel","action_type":"doSpin","amount":0,"amount_minor":0}}}}}},"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-nonce","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":{"contract_version":"2026-09-01","operator_id":"operator-a","player_id":"operator-a:player-129001","session_id":"session-token","game_symbol":"vs20doghouse","currency":"USD","request_id":"7d8a3996269f4cf3bb9f5aa6f65de3c1","transaction_id":"session-token:doSpin:0:1:debit","round_id":"round-01K5JQ7E4F1F5Y6Y2N1R4W9C0A","transaction_type":"rollback","action_type":"doSpin","amount":2,"amount_minor":200,"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"}}}}}}}}}}}