openapi: 3.0.3 info: title: PlayGo API version: 0.1.0 description: | Optional observability metadata on requests: X-Client-Display-Mode may be standalone, browser or unknown. It only enriches coarse request logs; absent, duplicate or invalid values remain unknown and never affect admission or responses. Display mode is client-reported, not an authorization signal. User-Agent and available Sec-CH-UA / Sec-CH-UA-Platform / Sec-CH-UA-Mobile headers are normalized server-side; raw headers are not stored in device logs. servers: - url: http://localhost:8080 security: - browserSession: [] paths: "/api/v1/admin/integrations/{domain}/{provider_code}/test-plan": get: operationId: getAdminIntegrationTestPlan tags: [admin] summary: Read versioned capability list without provider IO parameters: - {name: domain, in: path, required: true, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} responses: '200': {description: Nonsecret capability plan, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticPlan'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/{domain}/{provider_code}/credential-checks": post: operationId: postAdminIntegrationCredentialCheck tags: [admin] summary: Run current unsaved draft diagnostics without saving or activating configuration parameters: - {name: domain, in: path, required: true, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-integration-test requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticDraft'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '409': {description: Read the original run after a completed or restarted submission, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticReplay'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} '202': {description: Accepted read-only diagnostic run; no writes in S1, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticRun'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/{domain}/{provider_code}/full-tests": post: operationId: postAdminIntegrationFullTest tags: [admin] summary: Run current unsaved draft diagnostics without saving or activating configuration parameters: - {name: domain, in: path, required: true, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-integration-test requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticDraft'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '409': {description: Read the original run after a completed or restarted submission, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticReplay'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} '202': {description: Accepted read-only diagnostic run; no writes in S1, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticRun'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/game/{provider_code}/live-tests": post: operationId: postAdminIntegrationLiveTest tags: [admin] summary: Test saved active API configuration with an existing tester and at most one credit description: Requires API On and an active non-simulation tester. Does not save configuration, change API access or add wallet funds. The original request key replays its durable run. Unknown money is left to normal reconciliation. parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-integration-test requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationLiveTestRequest'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '202': {description: Durable live test receipt, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticRun'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integration-test-runs/{run_id}": get: operationId: getAdminIntegrationDiagnosticRun tags: [admin] summary: Read private sanitized run progress without provider IO parameters: - {name: domain, in: query, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: run_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': {description: Durable diagnostic progress, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationDiagnosticRun'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integration-test-runs/{run_id}/report": get: operationId: getAdminIntegrationDiagnosticReport tags: [admin] summary: Read private sanitized issue report without provider IO parameters: - {name: domain, in: query, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: run_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': {description: Private downloadable report, content: {text/plain: {schema: {type: string}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integration-summaries": get: operationId: getAdminIntegrationSummaries tags: [admin] summary: Read every platform game connection, including unconfigured and read-only legacy profiles description: Super-admin only. Returns credential presence and masked identifiers, never passwords, keys, raw identities, encrypted revisions or provider responses. Reads only this deployment's configuration and scoped vault. Makes no provider calls. responses: '200': {description: Non-secret platform game connection facts, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationConnectionSummaries'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-providers": get: operationId: getAdminGameProviders tags: [admin] summary: Read every game provider definition at its current revision (super admin only) description: Super-admin only, where the Connect site setting is on (ADR 0061). Every game_providers row joined to its current definition revision (ADR 0062); the catalog, provisioning, Connect and the runtime read these rows. Holds no credentials and makes no provider calls. responses: '200': {description: Game provider definitions ordered by code, content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderDefinitions'}}}} default: {$ref: '#/components/responses/DefaultError'} post: operationId: postAdminGameProvider tags: [admin] summary: Create a custom game provider as a draft (super admin only) description: Super-admin only, where the Connect site setting is on (ADR 0061), behind the custom provider kill switch; never under emulation (ADR 0062). Creates a draft with no family and no credentials. The endpoint must be an HTTPS DNS name on a public address and an allowlisted port (443, 8033, 8443, 8580, 8781). The provider is served to nobody until a live test passes and it is activated. The same Idempotency-Key and body replays the original result; the same key with another body is a conflict. Makes no provider calls. parameters: - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-game-provider requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderCreateRequest'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '201': {description: The draft provider, content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderDefinition'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-providers/{provider_code}": patch: operationId: patchAdminGameProvider tags: [admin] summary: Write a new definition revision of a custom game provider (super admin only) description: Super-admin only, custom providers only, compare-and-set on version. Choosing the family (from the custom-eligible families, at that family's fixed scales) moves a draft to verifying, where only testers can get accounts or move money. Changing the endpoint, family, scales or game id of a live provider, or changing a suspended provider, returns it to verifying. Credentials stay in Connect (PUT /api/v1/admin/integrations/game/{provider_code}). Makes no provider calls. parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-game-provider requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderChangeRequest'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': {description: The provider at its new revision, content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderDefinition'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-providers/{provider_code}/activation": post: operationId: postAdminGameProviderActivation tags: [admin] summary: Make a verifying custom game provider live (super admin only) description: Requires one finished full live test (POST /api/v1/admin/integrations/game/{provider_code}/live-tests) of this provider, under 24 hours old, run on the current definition and credential revisions, with every step passing and its agent balance check matching the credited amount. Writes a revision that records the run and makes the provider live and served. Makes no provider calls. parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-game-provider requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderActivationRequest'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': {description: The live provider, content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderDefinition'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-providers/{provider_code}/suspension": post: operationId: postAdminGameProviderSuspension tags: [admin] summary: Suspend a custom game provider (super admin only) description: Takes a live or verifying custom provider out of the catalog and gates its account and money writes off. Nothing is deleted. A later change returns it to verifying. Makes no provider calls. parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-game-provider requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderSuspensionRequest'}}} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': {description: The suspended provider, content: {application/json: {schema: {$ref: '#/components/schemas/GameProviderDefinition'}}}} '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integration-kinds": get: operationId: getAdminIntegrationKinds tags: [admin] summary: Read per-brand connection field schemas (super admin only) parameters: - {name: domain, in: query, schema: {$ref: '#/components/schemas/IntegrationDomain'}} responses: '200': {description: Supported game connection kinds, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationKinds'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations": get: operationId: getAdminIntegrations tags: [admin] summary: Read write-only connection field status; never return credential values parameters: - {name: domain, in: query, schema: {$ref: '#/components/schemas/IntegrationDomain'}} responses: '200': {description: Safe game connection summaries, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationSnapshots'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/{domain}/{provider_code}/secrets/{field_name}/compare": post: operationId: postAdminIntegrationSecretCompare tags: [admin] summary: Compare one saved secret without revealing or changing it description: Super-admin only. Rate-limited per actor. Never logs or persists the candidate; never activates credentials or contacts the provider. security: [{csrfToken: []}] parameters: - {name: domain, in: path, required: true, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {name: field_name, in: path, required: true, schema: {type: string, maxLength: 64, pattern: '^[a-z][a-z0-9_]{0,63}$'}} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [value] properties: value: {type: string, minLength: 1, maxLength: 2000, writeOnly: true} responses: '200': description: Only the exact comparison result content: application/json: schema: {type: object, additionalProperties: false, required: [match], properties: {match: {type: boolean}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} '429': {$ref: '#/components/responses/RateLimitedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/{domain}/{provider_code}": put: operationId: putAdminIntegration tags: [admin] summary: Save the current private draft without testing or enabling API security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-integration-save parameters: - {name: domain, in: path, required: true, schema: {$ref: '#/components/schemas/IntegrationDomain'}} - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected_revision, fields, catalog_version, reason] properties: fields: {type: object, writeOnly: true, maxProperties: 16, additionalProperties: {type: string, maxLength: 2000, writeOnly: true}} catalog_version: {type: string} clear_fields: {type: array, maxItems: 16, items: {type: string}} expected_revision: {type: integer, format: int64, minimum: 0} reason: {type: string, minLength: 3, maxLength: 500} responses: '400': {description: Safe field errors without submitted values, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationFieldErrors'}}}} '200': {description: Committed connection summary, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationSnapshot'}}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/payment/{provider_code}/activate": post: operationId: postAdminPaymentIntegrationActivation tags: [admin] summary: Activate the latest saved payment revision after a passing connection test description: Super-admin only, where the Connect site setting is on (ADR 0061). expected_revision must be the latest saved revision and have a passing saved-revision connection test completed within 24 hours. Audited. Save never activates. security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-payment-activation parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationActivationRequest'}}} responses: '200': {description: Committed connection summary, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationSnapshot'}}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/integrations/payment/{provider_code}/deactivate": post: operationId: postAdminPaymentIntegrationDeactivation tags: [admin] summary: Deactivate the active payment revision description: Super-admin only, where the Connect site setting is on (ADR 0061). expected_revision must be the active revision. Audited. The vendor becomes unavailable; deployment configuration is never used instead. security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-payment-activation parameters: - {name: provider_code, in: path, required: true, schema: {$ref: '#/components/schemas/ProviderCode'}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationActivationRequest'}}} responses: '200': {description: Committed connection summary, content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationSnapshot'}}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/store-players/{player_id}/link-options": get: operationId: getAdminStorePlayerLinkOptions tags: [admin] summary: Exact real site-player provider-slot witness for a local store binding parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: user_id, in: query, required: true, schema: {type: string, format: uuid}} responses: '200': {description: Real selected site player and exact nullable slot, content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLinkOptions"}}}} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/link-preview": post: operationId: postAdminStorePlayerLinkPreview tags: [admin] summary: Review local binding of a confirmed native store identity; no provider or money IO security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-store-link-preview parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLinkPreviewRequest"}}} responses: '200': {description: Immutable five-minute link review; observations grant no wallet entitlement, content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLinkPreview"}}}} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/link": post: operationId: postAdminStorePlayerLink tags: [admin] summary: Atomically bind a real site account and reseal its credential, retaining store history security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-store-link parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: {type: object, additionalProperties: false, required: [preview_id], properties: {preview_id: {type: string, format: uuid}}} responses: '200': {description: Binding and credential promoted; no wallet credit or opening allowance created, content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLinkResult"}}}} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-transfers/{transfer_id}/reconcile": post: operationId: postAdminStoreAgentReconcile tags: [admin] summary: Read exact native original-order evidence; never redispatch a mutation security: [{csrfToken: []}] parameters: - {name: transfer_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [] properties: reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Original request; unresolved when native evidence is absent or insufficient content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreAgentTransfer"}}} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/history": get: operationId: getAdminStorePlayerHistory tags: [admin] summary: Bounded local safe store-player audit history without native reads parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 50, default: 50}} - {name: cursor, in: query, schema: {type: string, maxLength: 4096}} responses: "200": description: Local audit page; provider history availability is independent of local events content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePlayerHistory"}}} default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/store-players/{player_id}/transfers/preview": post: operationId: postAdminStoreAgentTransferPreview tags: [admin] summary: Audited external agent credit and store game credits; never a site wallet movement security: [{csrfToken: []}] parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected, direction, credits] properties: expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} direction: {"$ref": "#/components/schemas/GameStoreAgentDirection"} credits: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Durable original request and exact external-credit effect content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreAgentPreview"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/transfers": post: operationId: postAdminStoreAgentTransfer tags: [admin] summary: Audited external agent credit and store game credits; never a site wallet movement security: [{csrfToken: []}] parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [preview_id] properties: preview_id: {type: string, format: uuid} responses: '200': description: Durable original request and exact external-credit effect content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreAgentTransfer"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-transfers/{transfer_id}/resolution": post: operationId: postAdminStoreAgentResolution tags: [admin] summary: Audited external agent credit and store game credits; never a site wallet movement security: [{csrfToken: []}] parameters: - {name: transfer_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected_state, outcome, evidence_reference, confirmed_same_order, confirmed_same_player, confirmed_amount, confirmed_outcome] properties: expected_state: {type: string, enum: [unknown]} outcome: {type: string, enum: [succeeded, rejected]} evidence_reference: {type: string, minLength: 3, maxLength: 256} confirmed_same_order: {type: boolean} confirmed_same_player: {type: boolean} confirmed_amount: {type: boolean} confirmed_outcome: {type: boolean} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Durable original request and exact external-credit effect content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreAgentTransfer"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-transfers/{transfer_id}": get: operationId: getAdminStoreAgentTransfer tags: [admin] summary: Read the original external store transfer; never retry a provider mutation parameters: - {name: transfer_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': description: Original request and outcome content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreAgentTransfer"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/password-reset": post: operationId: postAdminStorePlayerPasswordReset tags: [admin] summary: Reset once through a verified native password workflow; unknown requests never redispatch security: [{csrfToken: []}] parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected] properties: expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} current_password: {type: string, writeOnly: true, maxLength: 255} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Original durable reset status; no credential material content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePasswordReset"}}} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/password-access": post: operationId: postAdminStorePlayerPasswordAccess tags: [admin] summary: Audited one-use disclosure of the exact recorded store credential security: [{csrfToken: []}] parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected, purpose] properties: expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} purpose: {type: string, enum: [reveal, copy]} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Private no-store response; replay receipt contains identifiers only and each access re-authorizes content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePasswordAccess"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/panel-password": post: operationId: postAdminStorePlayerPanelPassword tags: [admin] summary: Record the exact current panel password in the encrypted store vault security: [{csrfToken: []}] parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected, password, panel_reference, confirmed_same_store_account, confirmed_current_login] properties: expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} password: {type: string, writeOnly: true, minLength: 1, maxLength: 255} panel_reference: {type: string, minLength: 1, maxLength: 128} resolve_unknown_command_id: {type: string, format: uuid, description: Exact original unknown reset resolved by this panel attestation; never redispatches it} confirmed_same_store_account: {type: boolean} confirmed_current_login: {type: boolean} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Audited saved credential; no provider verification is implied content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePasswordSaved"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/store-players/{player_id}/management": get: operationId: getAdminStorePlayerManagement tags: [admin] summary: Local nonsecret store-player identity, credential summary and observations parameters: - {name: player_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': description: Read-only management snapshot; no native calls content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePlayerManagement"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-stores/{store_id}/account-commands": get: operationId: getAdminGameStoreAccountCommands tags: [admin] summary: List held native account commands for staff recovery without provider IO parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: cursor, in: query, schema: {type: string, format: uuid}} responses: '200': {description: Up to 50 original commands and continuation, content: {application/json: {schema: {$ref: '#/components/schemas/GameStoreAccountCommands'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-stores/{store_id}/account-commands/{command_id}": get: operationId: getAdminGameStoreAccountCommand tags: [admin] summary: Read the original provider account command without native mutation parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: command_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': {description: Original command and next step, content: {application/json: {schema: {$ref: '#/components/schemas/GameStoreAccountCommand'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-stores/{store_id}/account-commands/{command_id}/resolve": post: operationId: postAdminGameStoreCreateResolution x-idempotency-required: true x-idempotency-scope: admin-store-create-resolution tags: [admin] summary: Record panel evidence and release a held creation name without adopting an account security: [{csrfToken: []}] parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: command_id, in: path, required: true, schema: {type: string, format: uuid}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/GameStoreCreateResolutionRequest'} responses: '200': {description: Original command resolved by panel evidence, content: {application/json: {schema: {$ref: '#/components/schemas/GameStoreAccountCommand'}}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-stores/{store_id}/player-lookup": post: operationId: postAdminGameStorePlayerLookup tags: [admin] summary: Read-only native lookup with an audited encrypted password when required security: [{csrfToken: []}] parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected, identifier] properties: expected: {"$ref": "#/components/schemas/GameStoreExpected"} identifier: {type: string, minLength: 1, maxLength: 128} target: type: object additionalProperties: false required: [player_id, player_revision, credential_id] properties: player_id: {type: string, format: uuid} player_revision: {type: integer, format: int64, minimum: 1} credential_id: {type: string, format: uuid, nullable: true} password: {type: string, writeOnly: true, maxLength: 255} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '200': description: Original lookup receipt; unknown is not not-found and may be retried with the same key content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLookup"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-stores/{store_id}/linked-players": get: operationId: getAdminGameStoreLinkedPlayers tags: [admin] summary: Already-linked site accounts; this is not a registered store roster parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: cursor, in: query, schema: {type: string, maxLength: 4096}} - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 50, default: 50}} - {name: q, in: query, schema: {type: string, maxLength: 128}} responses: '200': description: Local linked accounts only; never a complete native roster content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreLinkedAccounts"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-stores": get: operationId: getAdminGameStores tags: [admin] summary: Configured game stores and local observations; no native fan-out responses: '200': description: Configured store identities content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreList"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-stores/{store_id}/players": get: operationId: getAdminGameStorePlayers tags: [admin] summary: Authorized cached registered players, pinned to a complete generation parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: cursor, in: query, schema: {type: string, maxLength: 4096}} - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 50, default: 50}} - {name: q, in: query, schema: {type: string, maxLength: 128}} - {name: link, in: query, schema: {type: string, enum: [all, linked, unlinked], default: all}} responses: '200': description: Complete dated cache or explicitly not-yet-observed inventory content: {application/json: {schema: {"$ref": "#/components/schemas/GameStorePlayers"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminGameStorePlayerCreate tags: [admin] summary: Create one provider-only player, with no site account or wallet security: [{csrfToken: []}] x-idempotency-required: true x-idempotency-scope: admin-store-player-create parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {$ref: '#/components/parameters/IdempotencyKeyParam'} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/GameStorePlayerCreateRequest'} responses: '200': {description: Durable original creation result, content: {application/json: {schema: {$ref: '#/components/schemas/GameStoreAccountCommand'}}}} '426': {$ref: '#/components/responses/ClientOutdatedError'} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/game-stores/{store_id}/roster-refresh": post: operationId: postAdminGameStoreRosterRefresh tags: [admin] summary: Audit and coalesce a bounded store roster refresh security: [{csrfToken: []}] parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {"$ref": "#/components/parameters/IdempotencyKeyParam"} - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expected] properties: expected: {"$ref": "#/components/schemas/GameStoreExpected"} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} responses: '202': description: Accepted audited job; native reads run outside this request content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreRefresh"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-stores/{store_id}/roster-refresh/{request_id}": get: operationId: getAdminGameStoreRosterRefresh tags: [admin] summary: Authorized local refresh progress and failure reason parameters: - {name: store_id, in: path, required: true, schema: {type: string, format: uuid}} - {name: request_id, in: path, required: true, schema: {type: string, format: uuid}} responses: '200': description: Current refresh job, never a native read content: {application/json: {schema: {"$ref": "#/components/schemas/GameStoreRefresh"}}} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/providers/{provider_code}/api-access": get: operationId: getAdminProviderAPIAccess tags: [admin] summary: Read provider API access, its last audited change and draining work parameters: - name: provider_code in: path required: true schema: {"$ref": "#/components/schemas/ProviderCode"} responses: '200': description: Current database-authoritative API access content: {application/json: {schema: {"$ref": "#/components/schemas/ProviderAPIAccess"}}} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} patch: operationId: patchAdminProviderAPIAccess tags: [admin] summary: Superadmin changes provider API access with an audited expected-version CAS security: [{csrfToken: []}] parameters: - name: provider_code in: path required: true schema: {"$ref": "#/components/schemas/ProviderCode"} - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: type: object required: [expected_version, mode, reason] properties: expected_version: {type: integer, format: int64, minimum: 0} mode: {"$ref": "#/components/schemas/ProviderAPIAccessMode"} reason: {type: string, maxLength: 500, description: Why access is changing; whitespace-only reasons are refused.} auto_on_after_seconds: {type: integer, format: int64, nullable: true, minimum: 60, maximum: 604800, description: Optional server-relative Off timer. Omitted or null keeps Off until a manual On. Only valid with mode off. A same-mode Off save updates or cancels the timer using the expected-version CAS.} responses: '200': description: Saved current state; On preserves individual capability restrictions content: {application/json: {schema: {"$ref": "#/components/schemas/ProviderAPIAccess"}}} '400': description: Field-specific validation messages content: {application/json: {schema: {"$ref": "#/components/schemas/ProviderAPIAccessValidationError"}}} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': description: Another save won; review the latest state content: {application/json: {schema: {"$ref": "#/components/schemas/ProviderAPIAccessConflict"}}} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/emulation-grants": post: operationId: createAdminEmulationGrant tags: [admin] summary: Create a session-bound view-only player grant security: [{csrfToken: []}] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/EmulationGrantCreate"} responses: '200': description: Created view grant; never changes the admin session. content: application/json: schema: {"$ref": "#/components/schemas/EmulationGrant"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/emulation-grants/{grant_id}": get: operationId: getAdminEmulationGrant tags: [admin] summary: Read your grant using the original admin session parameters: - name: grant_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Grant including current mode and expiry. content: application/json: schema: {"$ref": "#/components/schemas/EmulationGrant"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/emulation-grants/{grant_id}/full-access": post: operationId: enableAdminEmulationFullAccess tags: [admin] summary: Super admin confirms or renews fifteen minutes of full player access security: [{csrfToken: []}] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: grant_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/EmulationFullAccess"} responses: '200': description: Full access enabled or renewed after confirmation. content: application/json: schema: {"$ref": "#/components/schemas/EmulationGrant"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/emulation-grants/{grant_id}/end": post: operationId: endAdminEmulationGrant tags: [admin] summary: End your emulation without changing either user's sessions security: [{csrfToken: []}] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: grant_id in: path required: true schema: {type: string, format: uuid} responses: '204': {description: Grant ended; repeated end is harmless.} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-reviews": get: operationId: listAdminGameCashoutReviews tags: [admin] summary: List cash-outs awaiting wallet review description: Newest review first by created_at descending, with transfer_id ascending as a stable tie-break. Defaults to pending and restoring reviews. parameters: - name: state in: query schema: {"$ref": "#/components/schemas/CashoutReviewState"} - name: limit in: query schema: {type: integer, format: int32, minimum: 1, maximum: 100, default: 50} - name: offset in: query schema: {type: integer, format: int32, minimum: 0, default: 0} responses: '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewList"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-reviews/{transfer_id}": get: operationId: getAdminGameCashoutReview tags: [admin] summary: Immutable game cash-out quote and review decision description: Recent activity is available from the linked player's existing admin story endpoint. parameters: - name: transfer_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-reviews/{transfer_id}/approve": post: operationId: approveAdminGameCashoutReview tags: [admin] summary: Approve game cash-out review security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: transfer_id in: path required: true schema: {type: string, format: uuid} - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewDecisionRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-reviews/{transfer_id}/reject": post: operationId: rejectAdminGameCashoutReview tags: [admin] summary: Reject game cash-out review security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: transfer_id in: path required: true schema: {type: string, format: uuid} - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewDecisionRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-review-settings": get: operationId: getAdminGameCashoutReviewSettings tags: [admin] summary: Superadmin read game cash-out review setting responses: '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewSettings"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminGameCashoutReviewSettings tags: [admin] summary: Superadmin change audited game cash-out review setting security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewSettingsRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewSettings"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/game-cashout-review-settings/history": get: operationId: listAdminGameCashoutReviewSettingsHistory tags: [admin] summary: Superadmin read immutable review setting history responses: '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutReviewSettingsHistory"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payout-policy": get: operationId: getAdminPayoutPolicy tags: [admin] summary: Superadmin getAdminPayoutPolicy responses: '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/PayoutPolicy"} '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" put: operationId: putAdminPayoutPolicy tags: [admin] summary: Superadmin putAdminPayoutPolicy security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UpdatePayoutPolicyRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/PayoutPolicy"} '400': description: Typed payout-policy field validation errors content: application/json: schema: {"$ref": "#/components/schemas/PayoutPolicyValidationError"} '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-accounts/{provider_account_id}/refresh-balance": post: operationId: postAdminProviderAccountRefreshBalance tags: [admin] summary: Explicitly refresh a player's stored game balance observation description: Any admin. This is an explicit vendor read; user detail GET and prefetch never invoke it. Concurrent foreground reads coalesce per account. Explicit reads bypass automatic retry delays but retain active leases and vendor rate limits; failed reads return a typed APIError.reason. Does not move money or establish a cash-out settlement fact. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" responses: '200': description: Stored balance after explicit refresh, with its observation time content: application/json: schema: "$ref": "#/components/schemas/ProviderBalanceObservationResponse" '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/provider-account-create-options": get: operationId: getAdminPlayerProviderAccountCreateOptions tags: [admin] summary: Staff native account creation for a site player description: Active admins only. Native capability and empty slot required. Uses the existing provisioning and sealed credential owner. No orphan account or uncertain create retry. parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: Native creation options or original receipt content: application/json: schema: {"$ref": "#/components/schemas/StaffAccountCreateOptions"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/provider-account-creations": post: operationId: postAdminPlayerProviderAccountCreate tags: [admin] summary: Staff native account creation for a site player description: Active admins only. Native capability and empty slot required. Uses the existing provisioning and sealed credential owner. No orphan account or uncertain create retry. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/StaffAccountCreateRequest"} responses: '202': description: Native creation options or original receipt content: application/json: schema: {"$ref": "#/components/schemas/StaffAccountCreateResult"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/provider-account-creations/{creation_id}": get: operationId: getAdminPlayerProviderAccountCreateResult tags: [admin] summary: Staff native account creation for a site player description: Active admins only. Native capability and empty slot required. Uses the existing provisioning and sealed credential owner. No orphan account or uncertain create retry. parameters: - "$ref": "#/components/parameters/UserIdParam" - name: creation_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Native creation options or original receipt content: application/json: schema: {"$ref": "#/components/schemas/StaffAccountCreateResult"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/load-options": get: operationId: getAdminProviderAccountLoadOptions tags: [admin] summary: Read the player wallet and account availability for an admin game load description: Admin and super-admin roles only. Uses the player wallet and ordinary provider-transfer rules; never an internal or house-funded load. Private reason audit is required when submitting. parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" responses: '200': description: Player-wallet facts or normal load result content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletGameLoadOptions"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/load-preflight": post: operationId: postAdminProviderAccountLoadPreflight tags: [admin] summary: Admin-only normal player-wallet game load preview or confirmation description: Admin and super-admin roles only. Uses the player wallet and ordinary provider-transfer rules; never an internal or house-funded load. Private reason audit is required when submitting. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/LoadPreflightRequest"} responses: '200': description: Player-wallet facts or normal load result content: application/json: schema: {"$ref": "#/components/schemas/LoadPreflight"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/load": post: operationId: postAdminProviderAccountLoad tags: [admin] summary: Admin-only normal player-wallet game load preview or confirmation description: Admin and super-admin roles only. Uses the player wallet and ordinary provider-transfer rules; never an internal or house-funded load. Private reason audit is required when submitting. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletGameLoadRequest"} responses: '201': description: Player-wallet facts or normal load result content: application/json: schema: {"$ref": "#/components/schemas/ProviderTransferResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/unload-preflight": post: operationId: postAdminProviderAccountUnloadPreflight tags: [admin] summary: Staff player-wallet unload-preflight description: Active staff admins with the staff-wallet permission flag. Ordinary player payout policy only; no override. Fixed staff_unload audit reason. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" responses: '200': description: Ordinary staff unload result content: application/json: schema: {"$ref": "#/components/schemas/CashoutPreview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/unload": post: operationId: postAdminProviderAccountUnload tags: [admin] summary: Staff player-wallet unload description: Active staff admins with the staff-wallet permission flag. Ordinary player payout policy only; no override. Fixed staff_unload audit reason. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/StaffWalletUnloadRequest"} responses: '201': description: Ordinary staff unload result content: application/json: schema: {"$ref": "#/components/schemas/ProviderTransferResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/cashout-preview": post: operationId: postAdminCashoutPreview tags: [admin] summary: Superadmin postAdminCashoutPreview security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" requestBody: required: false content: application/json: schema: {"$ref": "#/components/schemas/CashoutPreviewRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: success content: application/json: schema: {"$ref": "#/components/schemas/CashoutPreview"} '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-accounts/{provider_account_id}/cashout-override": post: operationId: postAdminCashoutOverride tags: [admin] summary: Superadmin postAdminCashoutOverride security: - csrfToken: [] x-idempotency-required: true x-idempotency-scope: admin-cashout-override parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CashoutOverrideRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: success content: application/json: schema: {"$ref": "#/components/schemas/ProviderTransferResponse"} '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/reward-campaigns": get: operationId: getAdminRewardCampaigns tags: [rewards] summary: List reward campaigns for operators responses: '200': description: Campaigns content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignsResponse"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminRewardCampaigns tags: [rewards] summary: Create a disabled reward campaign security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CreateRewardCampaignRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Created campaign content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/reward-campaigns/{campaign_id}/enabled": post: operationId: postAdminRewardCampaignEnabled tags: [rewards] summary: Enable or disable a reward campaign security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: campaign_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignEnabledRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Updated campaign content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/reward-campaigns": get: operationId: getRewardCampaigns tags: [rewards] summary: List announced and claimable campaigns for the player responses: '200': description: Campaigns content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignsResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/reward-campaigns/{campaign_id}/claim": post: operationId: postRewardCampaignClaim tags: [rewards] summary: Claim a campaign reward or enroll in a percentage campaign security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: campaign_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Reward claimed content: application/json: schema: {"$ref": "#/components/schemas/RewardCampaignResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/reward-campaigns/{campaign_id}/dismiss-popup": post: operationId: postRewardCampaignDismissPopup tags: [rewards] summary: Never show this campaign login popup again for this player security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: campaign_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': {description: Popup preference saved} default: {"$ref": "#/components/responses/DefaultError"} "/livez": get: operationId: getLiveness security: [] tags: - system summary: Liveness check responses: '200': description: process is alive content: application/json: schema: "$ref": "#/components/schemas/HealthResponse" default: "$ref": "#/components/responses/DefaultError" "/readyz": get: operationId: getReadiness security: [] tags: - system summary: Readiness check responses: '200': description: process dependencies are ready content: application/json: schema: "$ref": "#/components/schemas/HealthResponse" '503': description: dependency or schema check failed content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: "$ref": "#/components/responses/DefaultError" "/version": get: operationId: getVersion security: [] tags: - system summary: Build version responses: '200': description: build metadata content: application/json: schema: "$ref": "#/components/schemas/VersionResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/visitors/sessions": post: operationId: postVisitorSession security: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" tags: [insights] summary: Observe a coarse browser visit description: >- Best-effort browser telemetry including anonymous sessions. Uses same-origin/Fetch-Metadata admission, without browser CSRF or guest auth-session bootstrap. Optional existing authenticated identity is server-verified read-only. Normal client-build admission remains. Server cookies own visitor and session identity; no body user identity or conversion events are accepted. A 202 means queued, not durably stored. Untrusted acquisition values are normalized and cardinality capped. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/VisitorSessionObservation'} responses: '202': {description: observation queued or coalesced} '400': {$ref: '#/components/responses/BadRequestError'} '403': {$ref: '#/components/responses/ForbiddenError'} '426': {$ref: '#/components/responses/ClientOutdatedError'} '429': {description: observation buffer full, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/admin/insights/visitors": get: operationId: getAdminVisitorInsights security: [{browserSession: []}] tags: [insights] summary: Aggregate visitor cohorts for active admins description: >- Distinct visitors across each whole window, never sums of daily distincts. Funnels attribute authoritative signup, first unreversed settled credited deposit, and first completed game load to the earliest observed visit in the window. Later steps must occur before the window end. Returning means an earlier retained visit, not an inferred person. Predeployment and undelivered JavaScript are unmeasured; dropped counts cover only observations reaching this process. parameters: - name: period in: query required: true schema: {$ref: '#/components/schemas/VisitorPeriod'} responses: '200': {description: aggregate observed browser cohorts, content: {application/json: {schema: {$ref: '#/components/schemas/VisitorInsights'}}}} default: {$ref: '#/components/responses/DefaultError'} "/api/v1/client-diagnostics": post: x-client-build-exemption: public-intake operationId: postClientDiagnostics security: [] tags: - system summary: Report bounded stuck-tab recovery diagnostics description: >- Public append-only telemetry; no database writes. Exact POST bypasses client-build and CSRF gates so old tabs can use sendBeacon. Same-origin intake with optional verified session attribution. Body player_id is ignored. 8192-byte body limit, 20 requests/IP/minute and 200 globally/minute. Server sanitizes URLs and cache names; all browser facts are untrusted. requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ClientDiagnosticRequest" responses: '202': description: diagnostic accepted '400': "$ref": "#/components/responses/BadRequestError" '403': "$ref": "#/components/responses/ForbiddenError" '413': description: diagnostic body exceeds 8192 bytes content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '429': description: diagnostic budget exhausted headers: Retry-After: schema: type: integer minimum: 1 maximum: 60 content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/health": get: x-client-build-exemption: public-health operationId: getAPIHealth security: [] tags: - system summary: API health check responses: '200': description: API health check content: application/json: schema: "$ref": "#/components/schemas/HealthResponse" '503': description: dependency or schema check failed content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/acquisition/landing-touches": post: x-client-build-exemption: public-intake operationId: postAcquisitionLandingTouches security: [] tags: - acquisition summary: Capture a privacy-safe anonymous landing touch description: >- Stores normalized campaign fields only when tracking consent is present. Referrers are reduced to their host, landing URLs to their path, and ad click identifiers to a server-keyed HMAC before persistence. Reusing an idempotency key with a different canonical payload returns a conflict. x-idempotency-required: true x-idempotency-scope: acquisition-landing-touch parameters: - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AcquisitionLandingTouchRequest" responses: '200': description: landing touch captured or replayed content: application/json: schema: "$ref": "#/components/schemas/AcquisitionLandingTouchResponse" '400': "$ref": "#/components/responses/BadRequestError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/profile/me": get: operationId: getProfileMe tags: - profile summary: Current browser profile state and CSRF token responses: '200': description: current profile state for this browser session content: application/json: schema: "$ref": "#/components/schemas/ProfileMeResponse" '503': description: browser auth/profile endpoints disabled content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" "/api/v1/profile/onboarding": get: operationId: getProfileOnboarding tags: - profile summary: Current user's onboarding walkthrough state responses: '200': description: onboarding state for the current user content: application/json: schema: "$ref": "#/components/schemas/OnboardingState" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" put: operationId: putProfileOnboarding tags: - profile summary: Record that the current user has been shown the onboarding walkthrough description: >- Idempotent and monotonic. The stored version only ever moves forward, so a client running an older build cannot re-arm the walkthrough for a user who already acknowledged a newer version, and re-sending the same version preserves the original timestamp. security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AcknowledgeOnboardingRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated onboarding state content: application/json: schema: "$ref": "#/components/schemas/OnboardingState" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/profile/dev-settings": get: operationId: getProfileDevSettings tags: - profile summary: Current user's tester status responses: '200': description: dev settings for the current user content: application/json: schema: "$ref": "#/components/schemas/DevSettings" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/online-players": get: operationId: getAdminOnlinePlayers tags: [admin] summary: List recently active real players description: >- Distinct active real players with a validated authenticated request in the last five minutes, sampled at most once per minute. Excludes staff, testers, simulation players and internal accounts. In-game means a real player with a successful game launch or load in the last fifteen minutes; it does not prove an external vendor window is still open. Newest activity first. Uses stored facts only and never calls providers or marks items read. responses: '200': description: Presence snapshot content: application/json: schema: {"$ref": "#/components/schemas/AdminOnlinePlayersResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/testers": get: operationId: getAdminTesters tags: - admin summary: List the tester allowlist responses: '200': description: tester allowlist content: application/json: schema: "$ref": "#/components/schemas/AdminTestersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postAdminTesters tags: - admin summary: Add a user to the tester allowlist by email security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AddTesterRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: tester added content: application/json: schema: "$ref": "#/components/schemas/AdminTester" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/testers/{user_id}": delete: operationId: deleteAdminTester tags: - admin summary: Remove a user from the tester allowlist description: Dedicated drive test accounts retain tester identity permanently. Disable their drive access through drive account controls. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': description: tester removed '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" /api/v1/auth/login: post: operationId: postAuthLogin tags: - auth summary: Login with email and password security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/LoginRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: user authenticated content: application/json: schema: "$ref": "#/components/schemas/AuthUserResponse" '400': description: invalid input content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '401': description: invalid credentials content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '403': description: invalid CSRF token content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '503': description: browser auth endpoints disabled content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/auth/logout": post: operationId: postAuthLogout tags: - auth summary: Logout current browser session security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: session destroyed content: application/json: schema: "$ref": "#/components/schemas/LogoutResponse" '403': description: invalid CSRF token content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '503': description: browser auth endpoints disabled content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/auth/request-login: post: operationId: postAuthRequestLogin tags: [auth] summary: Request a passwordless email login (sends a magic link and a code) description: >- The response carries dev_code (the login code) in exactly two cases, never in staging or prod: env local with the local reveal hook on, or the CFG_AUTH_REVEAL_TEST_CODES flag on (dev only, refused at startup in staging and prod) and the email under an RFC 2606 reserved test TLD (.test, .example, .invalid, .localhost). Mail to those TLDs is never sent. Otherwise dev_code is absent. security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RequestLoginRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: login email enqueued (generic, non-enumerating response) content: application/json: schema: $ref: "#/components/schemas/PasswordlessLoginRequestedResponse" "400": description: invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: invalid CSRF token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: browser auth endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/auth/resend-login: post: operationId: postAuthResendLogin tags: [auth] summary: Resend the passwordless login email (rate limited) description: >- The response carries dev_code (the login code) in exactly two cases, never in staging or prod: env local with the local reveal hook on, or the CFG_AUTH_REVEAL_TEST_CODES flag on (dev only, refused at startup in staging and prod) and the email under an RFC 2606 reserved test TLD (.test, .example, .invalid, .localhost). Mail to those TLDs is never sent. Otherwise dev_code is absent. security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RequestLoginRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: login email resent or deferred (generic, non-enumerating) content: application/json: schema: $ref: "#/components/schemas/PasswordlessLoginRequestedResponse" "400": description: invalid input or resend rate limited content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: invalid CSRF token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: browser auth endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/auth/verify-code: post: operationId: postAuthVerifyCode tags: [auth] summary: Verify a passwordless login code and start a browser session security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VerifyCodeRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: code verified and user authenticated content: application/json: schema: $ref: "#/components/schemas/VerifyCodeResponse" "400": description: invalid or expired code content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: invalid CSRF token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: browser auth endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/auth/verify-magic-link: post: operationId: postAuthVerifyMagicLink tags: [auth] summary: Verify a passwordless magic-link token and start a browser session security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VerifyMagicLinkRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: token verified and user authenticated content: application/json: schema: $ref: "#/components/schemas/VerifyCodeResponse" "400": description: invalid or expired token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: invalid CSRF token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: browser auth endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/profile/signup-preferences: post: operationId: postProfileSignupPreferences tags: [profile] summary: Save optional post-signup username and password atomically description: >- Omitted or empty fields are unchanged. A username is normalized to lowercase letters and digits, then must contain 3..11 characters. Existing game accounts are unchanged. Same-key retries replay without overwriting newer preferences; a changed request with the same key conflicts. x-idempotency-required: true security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/IdempotencyKeyParam" - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/SignupPreferencesRequest"} responses: '200': description: Preferences saved or replayed content: application/json: schema: {"$ref": "#/components/schemas/SignupPreferencesResponse"} '400': description: Field validation failed content: application/json: schema: {"$ref": "#/components/schemas/SignupPreferencesValidationError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} /api/v1/profile/set-password: post: operationId: postProfileSetPassword tags: [profile] summary: Set a password for the authenticated user (optional fallback) security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SetPasswordRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: password set content: application/json: schema: $ref: "#/components/schemas/SetPasswordResponse" "400": description: invalid password content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: not authenticated content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: invalid CSRF token content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: browser auth endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/profile: patch: operationId: patchProfile tags: [profile] summary: Update the authenticated user's editable profile fields description: >- Partial update of the editable consumer profile fields (display name, phone, birthday, address). Only the fields present in the request body are changed; omitted fields (including ones sent as null) are left untouched. To clear an optional contact field (phone, birthday, address) send it as an empty string. Email is intentionally not editable here: it is the login identity in the passwordless auth model and a change requires a separate verified email-change flow. security: - csrfToken: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateProfileRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: profile updated content: application/json: schema: $ref: "#/components/schemas/AuthUserResponse" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "403": $ref: "#/components/responses/ForbiddenError" "503": description: browser auth/profile endpoints disabled content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/DefaultError" /api/v1/wallet: get: operationId: getWallet tags: - wallet summary: Current user's wallet snapshot responses: '200': description: wallet snapshot content: application/json: schema: "$ref": "#/components/schemas/WalletSnapshotResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/wallet/transactions": get: operationId: getWalletTransactions tags: - wallet summary: Current user's wallet transaction history parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: wallet transactions content: application/json: schema: "$ref": "#/components/schemas/WalletTransactionsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/providers": get: operationId: getProviders tags: - providers summary: List game providers responses: '200': description: providers content: application/json: schema: "$ref": "#/components/schemas/ProvidersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-accounts": get: operationId: getProviderAccounts tags: - providers summary: List current user's provider accounts description: >- Returns stored account balances and their observation times after a refresh with at most three workers shared across requests and a 500 ms wait budget. Slow, unavailable, or superseded provider reads retain the stored balance and its original balance_observed_at timestamp. A busy refresh capacity serves stored observations immediately. responses: '200': description: provider accounts content: application/json: schema: "$ref": "#/components/schemas/ProviderAccountsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-accounts/{provider_account_id}/first-unload-review/cancel": post: operationId: postProviderAccountFirstUnloadReviewCancel x-idempotency-required: true x-idempotency-scope: provider-first-unload-review-cancel x-playgo-command: idempotency: required: true scope: provider-first-unload-review-cancel tags: - providers summary: Cancel a pending first-unload review security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: first-unload review canceled content: application/json: schema: "$ref": "#/components/schemas/FirstUnloadReviewCommandResponse" '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games": get: operationId: getGames tags: - games summary: List active games description: Active games this site has connected. A provider appears only when its definition is live, its catalog visibility allows this site, and this site has connected its client (ADR 0062); public or allowlisted games without a connected client are not listed. responses: '200': description: games content: application/json: schema: "$ref": "#/components/schemas/GamesResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}": get: operationId: getGamesGameId tags: - games summary: Get one game parameters: - "$ref": "#/components/parameters/GameIdParam" responses: '200': description: game content: application/json: schema: "$ref": "#/components/schemas/GameResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/launch": post: operationId: postGamesGameIdLaunch x-idempotency-required: true x-idempotency-scope: game-launch x-playgo-command: idempotency: required: true scope: game-launch tags: - games summary: Launch a game in a new tab description: Provider launch requires Idempotency-Key; providers receive it as their launch idempotency reference while PlayGo still returns a fresh browser launch URL when providers support that behavior. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/LaunchGameRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: launch result content: application/json: schema: "$ref": "#/components/schemas/LaunchGameResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/add": post: operationId: postGamesGameIdAdd x-idempotency-required: true x-idempotency-scope: game-add x-playgo-command: idempotency: required: true scope: game-add tags: - games summary: Add a game to the current user's library and start account setup security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: game add accepted content: application/json: schema: "$ref": "#/components/schemas/AddGameResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/add-existing": post: operationId: postGamesGameIdAddExisting x-idempotency-required: true x-idempotency-scope: provider-account-link x-playgo-command: idempotency: required: true scope: provider-account-link tags: - games summary: Add a game by linking a provider account the player already has description: Verifies the existing provider account with read-only provider calls and links it to the current player. The link moves no money; the account's first unload is always reviewed by an admin. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AddExistingGameAccountRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: existing provider account linked content: application/json: schema: "$ref": "#/components/schemas/AddGameResponse" '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/favorite": post: operationId: postGamesGameIdFavorite tags: - games summary: Set current user's game favorite state description: Keeps up to three favorite games. Pinning a fourth removes the oldest pin atomically. Repeating an existing pin preserves its age. Refresh the catalog using the returned resource effects to see all affected games. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SetGameFavoriteRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated game content: application/json: schema: "$ref": "#/components/schemas/GameCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/refresh-balance": post: operationId: postGamesGameIdRefreshBalance tags: - games summary: Refresh current user's provider balance for a game card description: Performs a fresh foreground read with a configurable provider budget. Automatic-read retry delays do not block this explicit request; active leases, credential holds and vendor rate limits still apply. Proven account-not-found issues return 409 conflict with message 'This game account needs support, contact us'. Unknown provider failures return 503 with a typed APIError.reason and a clear provider-specific message; operator account status and stored balance remain separate from read health. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated game content: application/json: schema: "$ref": "#/components/schemas/GameCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '503': description: Provider observation unavailable; typed read reason, safe provider-specific message, no money outcome. content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/retry-setup": post: operationId: postGamesGameIdRetrySetup tags: - games summary: Retry a failed/stuck provider-account setup for a game card security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated game content: application/json: schema: "$ref": "#/components/schemas/GameCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/credential": get: operationId: getGamesGameIdCredential tags: - games summary: Reveal the current player's active provider login for a game parameters: - "$ref": "#/components/parameters/GameIdParam" - name: credential_id in: query required: false description: Reveal only if this exact reset-result credential is still active; a replacement returns 409. schema: {type: string, format: uuid} responses: '200': description: active provider login credential headers: Cache-Control: schema: type: string content: application/json: schema: "$ref": "#/components/schemas/GameCredentialResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/games/{game_id}/password-recovery": get: operationId: getGamePasswordRecovery tags: [providers] summary: Read the owned player's nonsecret recovery snapshot description: Owner-player only, no emulation. Read-only; excludes staff audit, reasons and setup history. Makes no provider call and initializes no metadata. parameters: - "$ref": "#/components/parameters/GameIdParam" responses: '200': description: Owner's nonsecret recovery snapshot headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/PasswordRecoverySnapshot"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/games/{game_id}/reset-password": post: operationId: postGamesGameIdResetPassword tags: - games summary: Reset current user's provider password for a game card description: Native provider reset. Providers that require the current password disable this action on credentials_rejected until same-account reconnect verifies and saves the current password. Providers with agent-only reset do not require the old password. If the current password is unknown, use the game app forgot-password option or contact support. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/GameIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/GamePasswordResetRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated game content: application/json: schema: "$ref": "#/components/schemas/GamePasswordResetResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-transfers": get: operationId: getProviderTransfers tags: - transfers summary: List current user's provider transfers parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: state in: query required: false schema: "$ref": "#/components/schemas/ProviderTransferState" responses: '200': description: provider transfers content: application/json: schema: "$ref": "#/components/schemas/ProviderTransfersResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-methods": get: operationId: getPaymentMethods tags: - payments summary: Current user's saved payment methods for a provider parameters: - name: provider_code in: query required: true schema: "$ref": "#/components/schemas/PaymentDepositProviderCode" responses: '200': description: saved payment methods content: application/json: schema: "$ref": "#/components/schemas/PaymentMethodsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-methods/{payment_method_id}": delete: operationId: deletePaymentMethodsPaymentMethodId x-idempotency-required: true x-idempotency-scope: payment-method-remove x-playgo-command: idempotency: required: true scope: payment-method-remove tags: - payments summary: Remove a saved payment method from future use security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_method_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/IdempotencyKeyParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: payment method removal state content: application/json: schema: "$ref": "#/components/schemas/PaymentMethodResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits/options": get: operationId: getPaymentDepositsOptions tags: - payments summary: Current user's payment deposit amount and method options responses: '200': description: payment deposit options content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositOptionsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits/quote": post: operationId: postPaymentDepositsQuote tags: [payments] summary: Quote the wallet credit for an available custom or preset deposit amount description: Read-only quote using current provider options and deposit policy. No payment or reservation is created. security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositQuoteRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Backend-computed paid and credited amounts in USD cents content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositQuoteResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits/nowpayments/minimum": post: operationId: postPaymentDepositsNowpaymentsMinimum tags: - payments summary: Current NOWPayments deposit minimum for the selected crypto asset security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositMinimumRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Current crypto deposit minimum in USD cents content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositMinimumResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits": get: operationId: getPaymentDeposits tags: - payments summary: Current user's payment deposit history parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: state in: query required: false schema: "$ref": "#/components/schemas/PaymentDepositState" responses: '200': description: payment deposits content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postPaymentDeposits x-idempotency-required: true x-idempotency-scope: payment-deposit-create x-playgo-command: idempotency: required: true scope: payment-deposit-create tags: - payments summary: Create a hosted checkout or direct saved-method payment deposit security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreatePaymentDepositRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: payment deposit created content: application/json: schema: "$ref": "#/components/schemas/CreatePaymentDepositResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits/{payment_id}": get: operationId: getPaymentDepositsPaymentId tags: - payments summary: Current user's payment deposit detail parameters: - name: payment_id in: path required: true schema: type: string format: uuid responses: '200': description: payment deposit detail content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-deposits/{payment_id}/refresh": post: operationId: postPaymentDepositsPaymentIdRefresh tags: - payments summary: Refresh a pending deposit from the payment provider security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_id in: path required: true schema: type: string format: uuid responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: refreshed payment deposit detail content: application/json: schema: "$ref": "#/components/schemas/PaymentDepositResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals/options": get: operationId: getPaymentWithdrawalsOptions tags: - payments summary: Current user's payment withdrawal amount and method options responses: '200': description: payment withdrawal options content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalOptionsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals": get: operationId: getPaymentWithdrawals tags: - payments summary: Current user's payment withdrawal history parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: state in: query required: false schema: "$ref": "#/components/schemas/PaymentWithdrawalState" responses: '200': description: payment withdrawals content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postPaymentWithdrawals x-idempotency-required: true x-idempotency-scope: payment-withdrawal-create x-playgo-command: idempotency: required: true scope: payment-withdrawal-create tags: - payments summary: Create a payment withdrawal request security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreatePaymentWithdrawalRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: payment withdrawal created content: application/json: schema: "$ref": "#/components/schemas/CreatePaymentWithdrawalResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals/quote": post: operationId: postPaymentWithdrawalsQuote tags: - payments summary: Preview the current fee and net payout for a withdrawal method security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalQuoteRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: current withdrawal quote content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalQuoteResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals/minimum": post: operationId: postPaymentWithdrawalsMinimum tags: - payments summary: Resolve the current provider-enforced minimum for a withdrawal method security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalMinimumRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: current withdrawal minimum content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalMinimumResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '503': "$ref": "#/components/responses/DefaultError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals/{payment_id}": get: operationId: getPaymentWithdrawalsPaymentId tags: - payments summary: Current user's payment withdrawal detail parameters: - name: payment_id in: path required: true schema: type: string format: uuid responses: '200': description: payment withdrawal detail content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/payment-withdrawals/{payment_id}/cancel": post: operationId: postPaymentWithdrawalsPaymentIdCancel x-idempotency-required: true x-idempotency-scope: payment-withdrawal-cancel tags: - payments summary: Cancel the current user's withdrawal while it awaits approval security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: type: string format: uuid responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: payment withdrawal canceled content: application/json: schema: "$ref": "#/components/schemas/PaymentWithdrawalResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/notifications": get: operationId: getNotifications tags: [notifications] summary: List the current player's in-app notifications parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: player notifications content: application/json: schema: {"$ref": "#/components/schemas/PlayerNotificationsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/notifications/read-all": post: operationId: postNotificationsReadAll tags: [notifications] summary: Mark all current-player notifications as read description: >- Marks unread notifications belonging to the signed-in player and created no later than the statement's database time. Naturally idempotent: existing read timestamps are unchanged, and repeating with no new arrivals marks zero. No idempotency key is required for this monotonic, non-financial update. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: notifications marked read content: application/json: schema: {"$ref": "#/components/schemas/PlayerNotificationsReadAllResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/notifications/{notification_id}/read": post: operationId: postNotificationsNotificationIdRead tags: [notifications] summary: Mark one current-player notification read security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: notification_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: notification marked read content: application/json: schema: {"$ref": "#/components/schemas/PlayerNotificationResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/webhooks/payments/thesolar/deposit": post: operationId: postWebhooksPaymentsThesolarDeposit tags: - webhooks summary: TheSolar deposit webhook receiver description: TheSolar authenticates this callback with a `hash` field in the JSON body. PlayGo verifies HMAC-SHA256 over non-hash JSON values joined with `|` in received field order using the configured deposit secret key before recording or crediting anything. security: [] x-signature-verification: thesolar-v3-pipe-hmac-sha256-body-hash requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/thesolar/withdraw": post: operationId: postWebhooksPaymentsThesolarWithdraw tags: - webhooks summary: TheSolar withdrawal webhook receiver description: TheSolar authenticates this callback with a `hash` field in the JSON body. PlayGo verifies HMAC-SHA256 over non-hash JSON values joined with `|` in received field order using the configured withdrawal secret key before recording anything. security: [] x-signature-verification: thesolar-v3-pipe-hmac-sha256-body-hash requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/xxpay/deposit": post: operationId: postWebhooksPaymentsXxpayDeposit tags: - webhooks summary: XXPay deposit notification receiver description: Verifies the signed form notification and a signed merchant-scoped order lookup before accepting settlement. Successful receipt returns exactly lowercase success. Temporary verification failures request provider retries. security: [] x-signature-verification: xxpay-sorted-merchant-signature-and-order-lookup requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: type: string responses: '200': description: notification accepted content: text/plain: schema: type: string enum: [success] '400': description: notification rejected content: text/plain: schema: type: string enum: [fail] default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/dollarpay/deposit": post: operationId: postWebhooksPaymentsDollarpayDeposit tags: - webhooks summary: DollarPay deposit webhook receiver description: DollarPay documents POST-form callbacks. URL-encoded and multipart forms and scalar JSON callbacks are accepted. PlayGo verifies the uppercase MD5 signature over sorted callback parameters plus the configured merchant key before recording or crediting anything. Successful receipt returns the literal text `SUCCESS`. security: [] x-signature-verification: dollarpay-sorted-md5-form-sign requestBody: required: true description: Bounded original callback bytes (at most 1 MiB). The adapter accepts flat scalar JSON, URL-encoded forms, and multipart forms, including omitted, plain-text, octet-stream or mismatched Content-Type headers. Body format is determined from the bytes. Duplicate fields, files, nested JSON and trailing JSON are rejected. Every original scalar participates in signature verification. content: '*/*': schema: type: string format: binary minLength: 1 maxLength: 1048576 responses: '200': description: webhook accepted content: text/plain: schema: type: string enum: - SUCCESS '400': description: webhook rejected content: text/plain: schema: type: string enum: - FAIL default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/dollarpay/withdraw": post: operationId: postWebhooksPaymentsDollarpayWithdraw tags: - webhooks summary: DollarPay withdrawal webhook receiver description: DollarPay documents POST-form callbacks. URL-encoded and multipart forms and scalar JSON callbacks are accepted. PlayGo verifies the uppercase MD5 signature over sorted callback parameters plus the configured merchant key before recording anything. Successful receipt returns the literal text `SUCCESS`. security: [] x-signature-verification: dollarpay-sorted-md5-form-sign requestBody: required: true description: Bounded original callback bytes (at most 1 MiB). The adapter accepts flat scalar JSON, URL-encoded forms, and multipart forms, including omitted, plain-text, octet-stream or mismatched Content-Type headers. Body format is determined from the bytes. Duplicate fields, files, nested JSON and trailing JSON are rejected. Every original scalar participates in signature verification. content: '*/*': schema: type: string format: binary minLength: 1 maxLength: 1048576 responses: '200': description: webhook accepted content: text/plain: schema: type: string enum: - SUCCESS '400': description: webhook rejected content: text/plain: schema: type: string enum: - FAIL default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/finix/deposit": post: operationId: postWebhooksPaymentsFinixDeposit tags: - webhooks summary: Finix deposit webhook receiver description: Finix posts JSON webhook events. PlayGo verifies configured Finix webhook authentication and/or the Finix-Signature HMAC-SHA256 header before recording or crediting anything. security: [] x-signature-verification: finix-signature-hmac-sha256-or-configured-bearer responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/finix/withdraw": post: operationId: postWebhooksPaymentsFinixWithdraw tags: - webhooks summary: Finix withdrawal webhook receiver description: Finix withdrawal webhooks are unsupported until a payout-link contract is implemented. security: [] responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/nowpayments/deposit": post: operationId: postWebhooksPaymentsNowpaymentsDeposit tags: - webhooks summary: NOWPayments deposit webhook receiver description: NOWPayments posts JSON IPN callbacks. PlayGo verifies the `x-nowpayments-sig` HMAC-SHA512 signature over recursively sorted JSON using the configured IPN secret before recording or crediting anything. security: [] x-signature-verification: nowpayments-sorted-json-hmac-sha512-header requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/nowpayments/withdraw": post: operationId: postWebhooksPaymentsNowpaymentsWithdraw tags: - webhooks summary: NOWPayments withdrawal webhook receiver description: NOWPayments posts payout IPN callbacks. PlayGo verifies the `x-nowpayments-sig` HMAC-SHA512 signature over recursively sorted JSON using the configured IPN secret before changing withdrawal state. security: [] x-signature-verification: nowpayments-sorted-json-hmac-sha512-header requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/rocketramp/deposit": post: operationId: postWebhooksPaymentsRocketrampDeposit tags: - webhooks summary: RocketRamp deposit webhook receiver description: Vantack posts the RocketRamp `embed_transfer` event as JSON. PlayGo verifies `X-Webhook-Signature`, the base64 HMAC-SHA256 of `X-Webhook-Timestamp` + "." + the exact raw body under the saved webhook signing secret, before recording or crediting anything. Missing or invalid signature headers are refused by the adapter with 401, not by schema validation, so every refusal is logged the same way. security: [] x-signature-verification: vantack-hmac-sha256-timestamp-v1 parameters: - name: X-Webhook-Timestamp in: header required: false description: Unix seconds the delivery was signed at. schema: {type: string, maxLength: 20} - name: X-Webhook-Signature in: header required: false description: Base64 HMAC-SHA256 signature. schema: {type: string, maxLength: 128} - name: X-Webhook-Signature-Version in: header required: false description: Signature scheme version; only v1 is accepted. schema: {type: string, maxLength: 8} - name: X-Event-Id in: header required: false description: Vantack delivery identifier, recorded for support only. schema: {type: string, maxLength: 128} requestBody: required: true description: Bounded original callback bytes (at most 1 MiB). The signature covers these exact bytes, so the body is passed to the adapter unparsed. content: '*/*': schema: type: string format: binary minLength: 1 maxLength: 1048576 responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '401': description: signature missing, malformed, outside the five-minute-ahead / 24-hour-old window, or not matching the saved signing secret; nothing is recorded or credited content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/mockpay/deposit": post: operationId: postWebhooksPaymentsMockpayDeposit tags: - webhooks summary: MockPay deposit webhook receiver description: MockPay dev checkout posts this callback over HTTP so local and dev deployments exercise webhook routing, middleware, raw-body capture, and payment state transitions. security: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/webhooks/payments/mockpay/withdraw": post: operationId: postWebhooksPaymentsMockpayWithdraw tags: - webhooks summary: MockPay withdrawal webhook receiver description: MockPay withdrawal callbacks are unsupported unless a dev withdrawal provider is implemented. security: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: webhook accepted content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" '400': description: webhook rejected content: application/json: schema: "$ref": "#/components/schemas/PaymentWebhookAckResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-transfers/mixed-load-observations": post: operationId: postMixedLoadDialogObservation tags: [transfers] summary: Record a player observation about a mixed-load dialog description: Best-effort observation. The browser discards a failed observation without prompting for reload or retrying. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/MixedLoadDialogObservation"} responses: '204': description: Observation accepted '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/provider-transfers/load-preflight": post: operationId: postProviderTransfersLoadPreflight tags: [transfers] summary: Read guided freeplay resolution facts without moving money description: Proven account-not-found issues return 409 conflict with message 'This game account needs support, contact us' before any money reservation. Unknown provider failures return 503. Automatic and preflight reads share bounded per-account backoff; local no-HTTP deferral does not create a cooldown. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/LoadPreflightRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Preflight facts and an expiring confirmation token content: application/json: schema: {"$ref": "#/components/schemas/LoadPreflight"} default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-accounts/{provider_account_id}/bonus-only/cashout-preview": post: operationId: postProviderAccountBonusOnlyCashoutPreview tags: [transfers] summary: Read fresh Bonus-only cash-out terms without reserving a load or ending a cycle security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {$ref: "#/components/schemas/BonusOnlyCashoutPreviewRequest"} responses: '200': description: Fresh cycle progress with a bound confirmation token only when eligible content: application/json: schema: {$ref: "#/components/schemas/BonusOnlyTerminalPreview"} '400': {$ref: "#/components/responses/BadRequestError"} '401': {$ref: "#/components/responses/UnauthorizedError"} '403': {$ref: "#/components/responses/ForbiddenError"} '409': {$ref: "#/components/responses/ConflictError"} '426': {$ref: "#/components/responses/ClientOutdatedError"} default: {$ref: "#/components/responses/DefaultError"} "/api/v1/provider-accounts/{provider_account_id}/bonus-only/close-loss": post: operationId: postProviderAccountBonusOnlyCloseLoss tags: [transfers] summary: End a Bonus-only cycle after a freshly verified zero game balance description: "Explicit player or admin action. Players may close only their own account; admins may close the selected player account. Checks cycle ownership/version, unresolved operations and a fresh zero observation. Records closure with no provider debit, payout or refund. Does not close a merely stale or unknown balance." x-idempotency-required: true x-idempotency-scope: provider-bonus-only-close-loss x-playgo-command: idempotency: required: true scope: provider-bonus-only-close-loss security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {$ref: "#/components/schemas/BonusOnlyCloseLossRequest"} responses: '200': description: Closed cycle with no money movement content: application/json: schema: {$ref: "#/components/schemas/BonusOnlyCloseLossResponse"} '400': {$ref: "#/components/responses/BadRequestError"} '401': {$ref: "#/components/responses/UnauthorizedError"} '403': {$ref: "#/components/responses/ForbiddenError"} '409': {$ref: "#/components/responses/ConflictError"} '426': {$ref: "#/components/responses/ClientOutdatedError"} default: {$ref: "#/components/responses/DefaultError"} "/api/v1/provider-transfers/clear-balance": post: operationId: postProviderTransfersClearBalance x-idempotency-required: true x-idempotency-scope: provider-transfer-unload x-playgo-command: idempotency: required: true scope: provider-transfer-unload tags: [transfers] summary: Give up an ineligible game cycle for zero without loading description: "Clears an ineligible freeplay cycle, including imported mixed cycles treated as freeplay. ADR 0059: also gives up a below-minimum paid cash or Bonus-only cycle when the preview token carries a cycle_conflict whose give_up.allowed is true, and is refused whenever cash-out is eligible. Requires the purpose-bound preview token and unchanged fresh balance/cycle/policy; pays zero and forfeits the whole game balance. A give-up never waits for staff review and never starts the Bonus interval." security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ClearBalanceRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Audited zero-payout cashout; unknown outcomes require reconciliation content: application/json: schema: {"$ref": "#/components/schemas/ProviderTransferResponse"} default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-transfers/load": post: operationId: postProviderTransfersLoad x-idempotency-required: true x-idempotency-scope: provider-transfer-load x-playgo-command: idempotency: required: true scope: provider-transfer-load tags: - transfers summary: Load PlayGo wallet value to provider credits security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateProviderTransferRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: transfer created content: application/json: schema: "$ref": "#/components/schemas/ProviderTransferResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': description: In-flight transfer or unresolved freeplay; reason identifies the guided flow content: application/json: schema: {"$ref": "#/components/schemas/ProviderLoadConflict"} default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-transfers/unload": post: operationId: postProviderTransfersUnload x-idempotency-required: true x-idempotency-scope: provider-transfer-unload x-playgo-command: idempotency: required: true scope: provider-transfer-unload tags: - transfers summary: Unload provider credits to PlayGo wallet value description: Full fresh-balance withdrawal with verified-zero settlement. A linked account's first withdrawal automatically accepts existing credits at full value; post-link freeplay follows normal winnings policy. Active non-linked accounts with no recorded cycle loads or freeplay principal accept the full fresh cash value; while review_unrecorded_credits is on (the default) that cash-out waits for staff review in pending_review, otherwise it settles automatically; issued cashout_breakdown exposes its mode and accepted_credits_cents. Existing open first-unload reviews still block transfers. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateProviderTransferRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: transfer created content: application/json: schema: "$ref": "#/components/schemas/ProviderTransferResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-transfers/{transfer_id}": get: operationId: getProviderTransfersTransferId tags: - transfers summary: Read provider transfer status parameters: - "$ref": "#/components/parameters/TransferIdParam" responses: '200': description: provider transfer content: application/json: schema: "$ref": "#/components/schemas/ProviderTransferResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/game-credit-move-settings": get: operationId: getAdminGameCreditMoveSettings tags: [admin] summary: Read game credit move policy and recent audit history responses: '200': description: current policy content: application/json: schema: "$ref": "#/components/schemas/GameCreditMoveSettingsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" put: operationId: putAdminGameCreditMoveSettings tags: [admin] summary: Super-admin audited compare-and-set policy update security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdateGameCreditMoveSettingsRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated policy and history content: application/json: schema: "$ref": "#/components/schemas/GameCreditMoveSettingsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-credit-moves/options": get: operationId: getProviderCreditMoveOptions tags: - transfers summary: Eligible recent load and verified destination game accounts parameters: - in: query name: source_account_id required: true schema: type: string format: uuid responses: '200': description: move options, empty when no load or destination qualifies content: application/json: schema: "$ref": "#/components/schemas/ProviderCreditMoveOptionsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-credit-moves": post: operationId: postProviderCreditMoves x-idempotency-required: true x-idempotency-scope: provider-credit-move x-playgo-command: idempotency: required: true scope: provider-credit-move tags: - transfers summary: Move the latest eligible load between a player's game accounts description: Positive freeplay or mixed balances on either game must first be resolved through guided cashout or Clear Balance. Refusals return conflict with reason freeplay_resolution_required. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateProviderCreditMoveRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: move created or idempotently replayed content: application/json: schema: "$ref": "#/components/schemas/ProviderCreditMoveResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/provider-credit-moves/{move_id}": get: operationId: getProviderCreditMove tags: - transfers summary: Read a player's game-credit move status parameters: - in: path name: move_id required: true schema: type: string format: uuid responses: '200': description: move status content: application/json: schema: "$ref": "#/components/schemas/ProviderCreditMoveResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/contact-links": get: x-client-build-exemption: public-intake security: [] operationId: getSupportContactLinks tags: [support] summary: Read this site's support contact shortcuts description: Empty fields disable their shortcut. This does not create a WhatsApp or email conversation inside the app. responses: '200': description: Public contact settings and signup free-play offer; contains no account data. headers: Cache-Control: {schema: {type: string}, description: Public cache lifetime of 30 seconds.} content: application/json: schema: "$ref": "#/components/schemas/SupportContactLinks" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/contact-links": patch: operationId: patchAdminSupportContactLinks tags: [admin, support] summary: Superadmin updates this site's support contact shortcuts security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdateSupportContactLinksRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: saved contact links content: application/json: schema: "$ref": "#/components/schemas/SupportContactLinks" '400': description: Invalid support contact destination content: application/json: schema: {"$ref": "#/components/schemas/SupportContactLinksValidationError"} '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/attachments": post: operationId: postSupportAttachments security: - csrfToken: [] tags: [support] summary: Reserve a private screenshot upload for the current player requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportAttachmentUploadRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Private upload reservation; maximum 8 MB PNG or JPEG content: application/json: schema: "$ref": "#/components/schemas/SupportAttachmentUploadResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}/attachments": post: operationId: postAdminSupportConversationsConversationIdAttachments tags: [admin, support] summary: Reserve a private screenshot upload for an admin reply security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/SupportAttachmentUploadRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Private upload reservation; maximum 8 MB PNG or JPEG content: application/json: schema: {"$ref": "#/components/schemas/SupportAttachmentUploadResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/support/attachments/{attachment_id}": get: x-client-build-exemption: private-stream operationId: getSupportAttachment tags: [support] summary: Read a screenshot as its conversation owner or an administrator parameters: - name: attachment_id in: path required: true schema: type: string format: uuid responses: '200': description: Private screenshot; unavailable after one year content: application/octet-stream: schema: type: string format: binary '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/conversation": get: operationId: getSupportConversation tags: - support summary: Get or create the current player's support conversation responses: '200': description: support conversation content: application/json: schema: "$ref": "#/components/schemas/SupportConversationResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/messages": get: operationId: getSupportMessages tags: - support summary: List current player's support messages by cursor parameters: - name: typing_version in: query description: Last opposite-side typing version seen; wakes the existing long poll when it changes. schema: {type: string, format: uuid} - name: before_seq in: query required: false schema: type: integer format: int64 minimum: 1 - name: after_seq in: query required: false schema: type: integer format: int64 minimum: 0 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - name: wait_for_updates in: query required: false description: Active-surface long-poll intent. When true, after_seq is required and the backend may hold the request until newer messages exist or the server-owned long-poll timeout expires. The backend controls whether long polling is enabled and how long it waits. schema: type: boolean default: false responses: '200': description: support messages content: application/json: schema: "$ref": "#/components/schemas/SupportMessagesResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postSupportMessages x-idempotency-required: true x-idempotency-scope: support-player-message-send tags: - support summary: Send a player support message security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportSendMessageRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: support message sent content: application/json: schema: "$ref": "#/components/schemas/SupportMessageCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" '429': "$ref": "#/components/responses/RateLimitedError" '503': "$ref": "#/components/responses/SupportMessageProcessingError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/typing": post: operationId: postSupportTyping tags: [support] summary: Signal player typing without marking read or writing history description: Ephemeral for six seconds, accepted at most once per three seconds per conversation side. Repeated signals are successful no-ops. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '204': {description: Typing signal accepted or throttled} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/support/conversations/{conversation_id}/typing": post: operationId: postAdminSupportTyping tags: [admin, support] summary: Signal staff typing without marking read or writing history description: All staff share one conversation-side throttle. Same ephemeral lifetime as player typing. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} responses: '204': {description: Typing signal accepted or throttled} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/support/read": post: operationId: postSupportRead tags: - support summary: Mark current player's support conversation read through a sequence security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportMarkReadRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated support conversation content: application/json: schema: "$ref": "#/components/schemas/SupportConversationResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/pengu/conversations": get: operationId: getAdminPenguConversations tags: [admin, pengu] summary: List the current admin's Pengu conversations parameters: - name: before_updated_at in: query schema: {type: string, format: date-time} - name: before_id in: query schema: {type: string, format: uuid} - name: page_size in: query schema: {type: integer, minimum: 1, maximum: 100, default: 25} - name: status in: query schema: {"$ref": "#/components/schemas/AdminPenguConversationStatus"} - name: folder_id in: query schema: {type: string, format: uuid} responses: '200': description: Pengu conversation page content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminPenguConversations tags: [admin, pengu] summary: Create a Pengu conversation security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguCreateConversationRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Pengu conversation created content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/conversations/{conversation_id}": get: operationId: getAdminPenguConversationsConversationId tags: [admin, pengu] summary: Get a Pengu conversation and its durable message timeline parameters: - name: conversation_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Pengu conversation detail content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationDetailResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} delete: operationId: deleteAdminPenguConversationsConversationId tags: [admin, pengu] summary: Delete a Pengu conversation and its durable data description: Rejects deletion while the conversation has a queued or running turn. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': {description: Pengu conversation deleted} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/conversations/{conversation_id}/move": post: operationId: postAdminPenguConversationsConversationIdMove tags: [admin, pengu] summary: Move a Pengu conversation into a folder or back to the root security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguMoveConversationRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu conversation moved content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/conversations/{conversation_id}/archive": post: operationId: postAdminPenguConversationsConversationIdArchive tags: [admin, pengu] summary: Archive an active Pengu conversation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu conversation archived content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/conversations/{conversation_id}/unarchive": post: operationId: postAdminPenguConversationsConversationIdUnarchive tags: [admin, pengu] summary: Restore an archived Pengu conversation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu conversation restored content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguConversationResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/folders": get: operationId: getAdminPenguFolders tags: [admin, pengu] summary: List the current admin's Pengu folders responses: '200': description: Pengu folders content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguFoldersResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminPenguFolders tags: [admin, pengu] summary: Create a Pengu folder security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguCreateFolderRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: Pengu folder created content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguFolderResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/folders/{folder_id}": patch: operationId: patchAdminPenguFoldersFolderId tags: [admin, pengu] summary: Rename a Pengu folder security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: folder_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguRenameFolderRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu folder renamed content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguFolderResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} delete: operationId: deleteAdminPenguFoldersFolderId tags: [admin, pengu] summary: Delete an empty Pengu folder description: Rejects deletion while the folder contains conversations or child folders. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: folder_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': {description: Pengu folder deleted} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/folders/{folder_id}/move": post: operationId: postAdminPenguFoldersFolderIdMove tags: [admin, pengu] summary: Move a Pengu folder under another folder or back to the root security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: folder_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguMoveFolderRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu folder moved content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguFolderResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/conversations/{conversation_id}/turns": post: operationId: postAdminPenguConversationsConversationIdTurns tags: [admin, pengu] summary: Enqueue one durable Pengu assistant turn security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: conversation_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguCreateTurnRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '202': description: Pengu turn queued content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguRunResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '503': description: Pengu is disabled or no verified-free model is available content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/runs/{run_id}": get: operationId: getAdminPenguRunsRunId tags: [admin, pengu] summary: Poll a durable Pengu run parameters: - name: run_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Pengu run state content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguRunResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/pengu/runs/{run_id}/cancel": post: operationId: postAdminPenguRunsRunIdCancel tags: [admin, pengu] summary: Cancel a queued or running Pengu turn security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: run_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Pengu run cancelled content: application/json: schema: {"$ref": "#/components/schemas/AdminPenguRunResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/support/conversations": post: operationId: postAdminSupportConversations tags: [admin, support] summary: Find or create a player's support conversation description: Naturally idempotent by player. Does not send a message, reopen a resolved conversation, or take over another admin's claim. security: - csrfToken: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [user_id] properties: user_id: type: string format: uuid parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Existing or newly created conversation content: application/json: schema: "$ref": "#/components/schemas/AdminSupportConversationResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" get: operationId: getAdminSupportConversations tags: - admin - support summary: Admin support conversation inbox parameters: - name: status in: query required: false schema: "$ref": "#/components/schemas/SupportConversationStatus" - name: unread in: query required: false schema: type: boolean - name: cursor in: query required: false schema: type: string minLength: 1 - name: per_page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: admin support inbox content: application/json: schema: "$ref": "#/components/schemas/AdminSupportConversationsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}": get: operationId: getAdminSupportConversationsConversationId tags: - admin - support summary: Admin support conversation detail parameters: - "$ref": "#/components/parameters/SupportConversationIdParam" responses: '200': description: admin support conversation detail content: application/json: schema: "$ref": "#/components/schemas/AdminSupportConversationResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}/messages": get: operationId: getAdminSupportConversationsConversationIdMessages tags: - admin - support summary: Admin list support conversation messages description: Messages come oldest first. Read the newest page with no cursor, older pages with before_seq, newer ones with after_seq, or the window around one message with around_seq (a search match). An around_seq window holds the message itself, up to limit/2 newer messages and the rest older; has_more then says older messages exist and has_more_after says newer ones exist. At most one of before_seq, after_seq and around_seq may be given, and wait_for_updates needs after_seq. parameters: - name: typing_version in: query description: Last opposite-side typing version seen; wakes the existing long poll when it changes. schema: {type: string, format: uuid} - "$ref": "#/components/parameters/SupportConversationIdParam" - name: before_seq in: query required: false schema: type: integer format: int64 minimum: 1 - name: after_seq in: query required: false schema: type: integer format: int64 minimum: 0 - name: around_seq in: query required: false schema: type: integer format: int64 minimum: 1 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - name: wait_for_updates in: query required: false description: Active-surface long-poll intent. When true, after_seq is required and the backend may hold the request until newer messages exist or the server-owned long-poll timeout expires. The backend controls whether long polling is enabled and how long it waits. schema: type: boolean default: false responses: '200': description: support messages content: application/json: schema: "$ref": "#/components/schemas/SupportMessagesResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postAdminSupportConversationsConversationIdMessages x-idempotency-required: true x-idempotency-scope: support-admin-message-send tags: - admin - support summary: Admin reply as Support security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportSendMessageRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: support message sent content: application/json: schema: "$ref": "#/components/schemas/SupportMessageCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" '429': "$ref": "#/components/responses/RateLimitedError" '503': "$ref": "#/components/responses/SupportMessageProcessingError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/search": get: operationId: getAdminSupportSearch tags: [admin, support] summary: Search every support chat description: Searches all conversations' message text and their players' display names, emails and active aliases. Matching ignores case and Latin accents. A message matches when every query word starts a word of it, when it contains the whole query (queries of three or more characters) or, for a single word of four or more characters, when it has a word close to it (typos). A player matches when a name, email or alias contains the whole query; that conversation is one hit. Hits come newest first (the message time, or the conversation's last activity for a player hit) and page with an opaque cursor. Snippets are plain text with typed highlight ranges, never markup. Any admin may search; players get 403. A query shorter than two characters after trimming is a 400. parameters: - name: q in: query required: true schema: {type: string, minLength: 2, maxLength: 100} - name: cursor in: query required: false schema: {type: string, minLength: 1} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 50, default: 20} responses: '200': description: search hits content: application/json: schema: {"$ref": "#/components/schemas/AdminSupportSearchResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/support/conversations/{conversation_id}/search": get: operationId: getAdminSupportConversationSearch tags: [admin, support] summary: Search one support chat description: The messages of one conversation that match the query, by the same rules as the global search, newest first, with snippets and typed highlight ranges. total counts every match in the conversation. To show a match, load its window with the messages endpoint's around_seq. Any admin may search; players get 403. parameters: - "$ref": "#/components/parameters/SupportConversationIdParam" - name: q in: query required: true schema: {type: string, minLength: 2, maxLength: 100} - name: cursor in: query required: false schema: {type: string, minLength: 1} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 200, default: 50} responses: '200': description: matching messages content: application/json: schema: {"$ref": "#/components/schemas/AdminSupportConversationSearchResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/support/conversations/{conversation_id}/read": post: operationId: postAdminSupportConversationsConversationIdRead tags: - admin - support summary: Mark support conversation read for the admin inbox security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportMarkReadRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated support conversation content: application/json: schema: "$ref": "#/components/schemas/AdminSupportConversationResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}/resolve": post: operationId: postAdminSupportConversationsConversationIdResolve x-idempotency-required: true x-idempotency-scope: support-conversation-resolve tags: - admin - support summary: Resolve a support conversation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportTransitionRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: resolved support conversation content: application/json: schema: "$ref": "#/components/schemas/SupportConversationCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}/reopen": post: operationId: postAdminSupportConversationsConversationIdReopen x-idempotency-required: true x-idempotency-scope: support-conversation-reopen tags: - admin - support summary: Reopen a resolved support conversation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportTransitionRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: reopened support conversation content: application/json: schema: "$ref": "#/components/schemas/SupportConversationCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/support/conversations/{conversation_id}/claim": post: operationId: postAdminSupportConversationsConversationIdClaim tags: - admin - support summary: Claim (advisory lock) a support conversation for the current admin description: 'Records an advisory, time-limited claim so other admins see the conversation is being handled. The claim is a lightweight lease: it is not idempotency-keyed and does not bump the conversation version. Granted when the conversation is unclaimed, the claim has expired, the caller already holds it, or takeover is true; otherwise the existing claim is left untouched. Always returns the current conversation; the `claim` block and `actions.send_message` describe the outcome.' security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SupportConversationIdParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SupportClaimRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: current support conversation with claim state content: application/json: schema: "$ref": "#/components/schemas/AdminSupportConversationResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/ledger/accounts": get: operationId: getAdminLedgerAccounts tags: - admin summary: Admin ledger account list parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: ledger accounts content: application/json: schema: "$ref": "#/components/schemas/AdminLedgerAccountsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/ledger/transactions": get: operationId: getAdminLedgerTransactions tags: - admin summary: Admin ledger transaction list parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: ledger transactions content: application/json: schema: "$ref": "#/components/schemas/AdminLedgerTransactionsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/admins": post: operationId: postAdminAdmins tags: - admin summary: Super admin creates an admin account security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAdminAccountRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: admin account created content: application/json: schema: "$ref": "#/components/schemas/AdminAccountResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/admins/{admin_id}": patch: operationId: patchAdminAdminsAdminId tags: - admin summary: Super admin changes admin account role or status security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: admin_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdateAdminAccountRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: admin account updated content: application/json: schema: "$ref": "#/components/schemas/AdminAccountResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/admins/{admin_id}/reset-password": post: operationId: postAdminAdminsAdminIdResetPassword tags: - admin summary: Super admin resets an admin password description: >- Sets the password chosen by the super admin, revokes every target admin session, and records a secret-free actor/target audit event. x-idempotency-required: true x-idempotency-scope: admin-password-reset security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: admin_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminPasswordResetRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: admin password reset content: application/json: schema: "$ref": "#/components/schemas/AdminPasswordResetResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/players/export": post: operationId: postAdminPlayersExport tags: [admin] summary: Super-admin audited streaming player CSV description: Exports all matching players, not only the current page. UTF-8 BOM, spreadsheet-safe cells, no secrets. Payout tags are player-owned destinations saved on payout requests, never house tags. Last seen is the last recorded player activity; absent values are blank. security: [{browserSession: [], csrfToken: []}] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminPlayerExportRequest" responses: '200': description: Streamed CSV download; export initiation and final row count/outcome are audited. headers: Content-Disposition: schema: {type: string} content: text/csv: schema: {type: string, format: binary} '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '426': "$ref": "#/components/responses/ClientOutdatedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/users": get: operationId: getAdminUsers tags: - admin summary: Admin user directory parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: q in: query required: false schema: type: string minLength: 1 maxLength: 256 - name: role in: query required: false schema: "$ref": "#/components/schemas/UserRole" - name: status in: query required: false schema: "$ref": "#/components/schemas/UserStatus" - name: deposit_recency in: query required: false description: Server-side filter on the newest successful wallet deposit (players only). never means none at all; inactive_Nd means at least one and the newest is N or more rolling 24-hour days old. Applied before pagination. schema: "$ref": "#/components/schemas/AdminRechargeRecencyFilter" - name: game_load_recency in: query required: false description: Server-side filter on the newest completed wallet-to-game load (players only), with the same semantics as deposit_recency. A load is a recharge signal, not gameplay. schema: "$ref": "#/components/schemas/AdminRechargeRecencyFilter" responses: '200': description: admin users content: application/json: schema: "$ref": "#/components/schemas/AdminUsersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/users/{user_id}": get: operationId: getAdminUsersUserId tags: - admin summary: Admin user detail parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: admin user detail content: application/json: schema: "$ref": "#/components/schemas/AdminUserDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/users/{user_id}/deposit-methods": parameters: - "$ref": "#/components/parameters/UserIdParam" get: operationId: getAdminPlayerDepositMethods tags: [admin, payments] summary: Read the deposit method visibility for one player responses: '200': description: Current player visibility, configured methods and latest change content: application/json: schema: "$ref": "#/components/schemas/PlayerDepositMethodVisibility" default: "$ref": "#/components/responses/DefaultError" put: operationId: putAdminPlayerDepositMethods tags: [admin, payments] summary: Replace one player's hidden deposit methods using the expected revision security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdatePlayerDepositMethodVisibility" responses: '200': description: Saved visibility and latest change content: application/json: schema: "$ref": "#/components/schemas/PlayerDepositMethodVisibility" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/users/{user_id}/reset-password": post: operationId: postAdminUsersUserIdResetPassword tags: - admin summary: Super admin resets a player password description: >- Sets a super-admin-chosen password for a player, revokes all target sessions, and records a secret-free actor/target audit event. x-idempotency-required: true x-idempotency-scope: admin-player-password-reset security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminPasswordResetRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: player password reset content: application/json: schema: "$ref": "#/components/schemas/AdminPasswordResetResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/business-analytics/overview": get: operationId: getAdminBusinessAnalyticsOverview tags: - admin - business-analytics summary: Super-admin business and finance reporting overview description: >- Authoritative operational reporting from payment, provider-transfer, ledger, wallet-balance, and reward-balance records; product analytics events are never used. Windowed metrics use the half-open interval [from,to). Successful deposits and withdrawals are recognized at their linked wallet_credit and withdrawal_settle ledger transaction timestamps, respectively. Outcome cohorts use record creation time and current state. Calendar buckets use the fixed America/New_York reporting timezone and are returned with zero-filled gaps. Day reports allow at most 366 intersecting local-calendar buckets and month reports allow at most 60. When from is omitted, the response covers 30 local day buckets or 12 local month buckets ending at to; when to is omitted it defaults to the request-time generated_at. Internal provider-health system accounts and tester accounts are always excluded. Cash flow is a wallet-settlement proxy, not bank cash flow: processor bank settlement, chargebacks, refunds, and deposit fees are not persisted. parameters: - "$ref": "#/components/parameters/AdminReportingFromParam" - "$ref": "#/components/parameters/AdminReportingToParam" - "$ref": "#/components/parameters/AdminReportingGranularityParam" - "$ref": "#/components/parameters/AdminReportingIncludeInternalParam" responses: '200': description: business and finance reporting overview content: application/json: schema: "$ref": "#/components/schemas/AdminBusinessAnalyticsOverviewResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/recharge-cohorts": get: operationId: getAdminRechargeCohorts tags: - admin summary: Recharge recency cohort counts (any admin) description: >- Point-in-time counts of ACTIVE external players by the age of their last successful wallet deposit and last completed game load. Only counts are returned: nothing financial and no player identity, and nothing the Players directory does not already show every admin. This is deliberately separate from the super-admin-only player statistics overview. These are recharge signals, never gameplay activity. responses: '200': description: recharge cohorts content: application/json: schema: "$ref": "#/components/schemas/AdminRechargeCohorts" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/player-stats/overview": get: operationId: getAdminPlayerStatsOverview tags: - admin - player-stats summary: Super-admin player statistics overview description: >- PII-free player reporting from authoritative user, settlement, provider-transfer, game-launch idempotency, and Player360 risk records; product analytics events are never used. Windowed metrics use the half-open interval [from,to). Depositors and withdrawing players are recognized at linked ledger settlement timestamps; business-active players have a settled deposit, settled withdrawal, or completed provider transfer; game-active players have a successfully completed game_launch idempotency record. Calendar buckets use the fixed America/New_York reporting timezone and are returned with zero-filled gaps. Day reports allow at most 366 intersecting local-calendar buckets and month reports allow at most 60. When from is omitted, the response covers 30 local day buckets or 12 local month buckets ending at to; when to is omitted it defaults to request-time generated_at. Internal provider-health system accounts and tester accounts are always excluded. Account status is measured for accounts created before to; risk levels are a current generated_at snapshot using the Player360 v1 velocity, failure, reconciliation, and keyed-correlation rules. parameters: - "$ref": "#/components/parameters/AdminReportingFromParam" - "$ref": "#/components/parameters/AdminReportingToParam" - "$ref": "#/components/parameters/AdminReportingGranularityParam" - "$ref": "#/components/parameters/AdminReportingIncludeInternalParam" responses: '200': description: player statistics overview content: application/json: schema: "$ref": "#/components/schemas/AdminPlayerStatsOverviewResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/growth/overview": get: operationId: getAdminGrowthOverview tags: - admin - growth summary: Super-admin acquisition and lifecycle overview description: >- Reports authoritative registration, first successful provider game load or launch, settled deposit, completed game cashout, and withdrawal lifecycle facts. Tester, system, and bot exclusions use the response's versioned rule set. parameters: - "$ref": "#/components/parameters/GrowthFromParam" - "$ref": "#/components/parameters/GrowthToParam" - "$ref": "#/components/parameters/GrowthTimezoneParam" responses: '200': description: acquisition and lifecycle overview content: application/json: schema: "$ref": "#/components/schemas/GrowthOverviewResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/growth/acquisition": get: operationId: getAdminGrowthAcquisition tags: - admin - growth summary: Super-admin acquisition channel report description: >- Groups registrations by immutable last-non-direct attribution, falling back to first-touch attribution. Referral attribution remains separate. parameters: - "$ref": "#/components/parameters/GrowthFromParam" - "$ref": "#/components/parameters/GrowthToParam" - "$ref": "#/components/parameters/GrowthTimezoneParam" responses: '200': description: acquisition channel report content: application/json: schema: "$ref": "#/components/schemas/GrowthAcquisitionResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/growth/funnel": get: operationId: getAdminGrowthFunnel tags: - admin - growth summary: Super-admin ordered same-user lifecycle funnel description: >- Counts only ordered same-user progression from registration to activation, settled deposit, and completed game cashout. parameters: - "$ref": "#/components/parameters/GrowthFromParam" - "$ref": "#/components/parameters/GrowthToParam" - "$ref": "#/components/parameters/GrowthTimezoneParam" responses: '200': description: ordered lifecycle funnel content: application/json: schema: "$ref": "#/components/schemas/GrowthFunnelResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/growth/retention": get: operationId: getAdminGrowthRetention tags: - admin - growth summary: Super-admin exact and rolling retention cohorts description: >- Returns D1, D7, and D30 exact-day and rolling retention for local-date registration cohorts. Immature windows are explicit and have null users and rates. Active means a successful meaningful authenticated lifecycle action, never a pageview or login. parameters: - "$ref": "#/components/parameters/GrowthFromParam" - "$ref": "#/components/parameters/GrowthToParam" - "$ref": "#/components/parameters/GrowthAsOfParam" - "$ref": "#/components/parameters/GrowthTimezoneParam" responses: '200': description: exact and rolling retention cohorts content: application/json: schema: "$ref": "#/components/schemas/GrowthRetentionResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-withdrawals/{payment_id}/provenance": get: operationId: getAdminPaymentWithdrawalProvenance tags: - admin - payments - provenance summary: Super-admin withdrawal funding provenance description: >- Reconciles a withdrawal reservation to immutable withdrawable-credit lots. Provider cashout sources prove only the provider/platform unless a stronger source record explicitly exists; they do not assert an individual slot game. parameters: - name: payment_id in: path required: true schema: type: string format: uuid responses: '200': description: withdrawal provenance and reconciliation context content: application/json: schema: "$ref": "#/components/schemas/WithdrawalProvenanceResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/players/{user_id}/withdrawal-provenance/summary": get: operationId: getAdminPlayerWithdrawalProvenanceSummary tags: - admin - players - provenance summary: Super-admin player withdrawal-provenance summary parameters: - name: user_id in: path required: true schema: type: string format: uuid responses: '200': description: player withdrawable-credit reconciliation summary content: application/json: schema: "$ref": "#/components/schemas/PlayerWithdrawalProvenanceSummaryResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/risk-policy": get: operationId: getAdminRiskPolicy tags: [admin] summary: Read audited risk policy and recent revisions responses: '200': description: Risk policy content: application/json: schema: {"$ref": "#/components/schemas/AdminRiskPolicyResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminRiskPolicy tags: [admin] summary: Change risk policy with optimistic version and audited reason security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminRiskPolicyUpdate"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Saved risk policy content: application/json: schema: {"$ref": "#/components/schemas/AdminRiskPolicyResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/risk-reviews": get: operationId: getAdminRiskReviews tags: [admin] summary: Superadmin evidence-backed risk review queue parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: view in: query schema: "$ref": "#/components/schemas/AdminRiskReviewView" - name: state in: query schema: "$ref": "#/components/schemas/AdminRiskReviewStateFilter" responses: '200': description: Reviews and global outstanding count independent of pagination content: application/json: schema: "$ref": "#/components/schemas/AdminRiskReviewsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/risk-reviews/{review_id}": get: operationId: getAdminRiskReview tags: [admin] parameters: - name: review_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Review with durable decision history content: application/json: schema: "$ref": "#/components/schemas/AdminRiskReviewDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postAdminRiskReview security: - csrfToken: [] tags: [admin] summary: Note, acknowledge without action, or snooze the stored evidence snapshot from the last background refresh description: The decision applies to the stored evidence snapshot from the last background refresh, identified by expected_fingerprint. A refresh that stored newer evidence makes the decision conflict (409). parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: review_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminRiskReviewCommand" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Updated review; no financial settlement or automatic moderation content: application/json: schema: "$ref": "#/components/schemas/AdminRiskReviewDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/users/{user_id}/pending-actions": get: operationId: getAdminPlayerPendingActions tags: [admin] summary: Ranked pending actions for this player, including resolved chats description: Read-only, no provider calls. Deduplicated owner records, money owed first. Counts are independent of chat unread state. All current pending items remain available through paging. parameters: - name: user_id in: path required: true schema: {type: string, format: uuid} - name: limit in: query schema: {type: integer, minimum: 1, maximum: 100, default: 3} - name: offset in: query schema: {type: integer, minimum: 0, default: 0} responses: '200': description: Player pending actions and exact total content: application/json: schema: {"$ref": "#/components/schemas/AdminPlayerPendingActions"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/recheck": post: operationId: postAdminPaymentDepositRecheck x-idempotency-required: false tags: [admin] summary: Recheck an unresolved deposit with its provider description: >- Super admin only. Performs one read-only provider status lookup, including deposits older than the automatic polling window, then applies only the provider's proven outcome through the existing reconciliation owner. May settle a verified paid deposit once. Missing, pending or unknown provider results remain unresolved. Never creates a checkout or resubmits a payment. Repeated checks use the same immutable deposit identity. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Provider checked; inspect the returned current state content: application/json: schema: {"$ref": "#/components/schemas/AdminDepositRecheckResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '503': description: Provider status unavailable; keep the outcome unresolved content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-transfers/{transfer_id}/recover": post: operationId: postAdminProviderTransferRecover x-idempotency-required: false tags: [admin] summary: Recover a stalled transfer for evidence-backed verification description: >- Super admin only. Atomically moves a requested, wallet_debited or provider_requesting transfer older than ten minutes with no queued/running job into unknown_requires_reconcile. Review-owned transfers and live request leases are refused. No provider write, settlement or refund occurs. The transfer identity makes recovery idempotent while unknown; proceed through the existing financial-case preview and evidence-backed resolution afterward. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: transfer_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Transfer now requires evidence-backed verification content: application/json: schema: {"$ref": "#/components/schemas/AdminTransferRecoveryResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-account-provisionings/{provisioning_id}/retry": post: operationId: postAdminProviderSetupRetry tags: [admin] summary: Audited retry of a definitively failed player game setup description: Active admin only. Atomically records the reason and queues the existing setup job. Unknown or in-flight creation is refused. Same-key same-body replay never queues another job. No external call or money movement occurs here. x-idempotency-required: true x-idempotency-scope: admin-provider-setup-retry security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: provisioning_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminProviderSetupRetryRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Original retry receipt, plus read refresh effects content: application/json: schema: {"$ref": "#/components/schemas/AdminProviderSetupRetryResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/users/{user_id}/moderation": get: operationId: getAdminPlayerModeration tags: [admin] summary: Current player status and backend-owned moderation eligibility parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: Player moderation actions content: application/json: schema: "$ref": "#/components/schemas/AdminPlayerModerationResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" patch: operationId: patchAdminPlayerModeration security: - csrfToken: [] tags: [admin] summary: Superadmin-only audited player suspension, ban, or reactivation description: Changes only player targets. Atomically revokes sessions and increments session version. Existing callbacks and financial recovery remain untouched. parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminPlayerModerationCommand" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Updated player status; old sessions remain revoked content: application/json: schema: "$ref": "#/components/schemas/AdminPlayerModerationResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/player-360": get: operationId: getAdminPlayer360 tags: - admin - player-360 summary: Player 360 directory (any admin) description: Server-paged player search with coarse financial and risk summaries. This read-only endpoint never changes player status. parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: q in: query required: false schema: type: string minLength: 1 maxLength: 256 responses: '200': description: player summaries content: application/json: schema: "$ref": "#/components/schemas/AdminPlayer360PlayersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/player-360/{user_id}": get: operationId: getAdminPlayer360UserId tags: - admin - player-360 summary: Player 360 snapshot (any admin) description: Read-only financial aggregates and explainable risk signals as of one timestamp. No signal causes an automatic ban or player-status mutation. parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: Player 360 snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminPlayer360DetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/player-360/{user_id}/deposits": get: operationId: getAdminPlayer360UserIdDeposits tags: - admin - player-360 summary: Paged player deposit history (any admin) description: Complete server-paged deposit history. Checkout links, KYC links, raw evidence, and provider payloads are omitted. parameters: - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: player deposits content: application/json: schema: "$ref": "#/components/schemas/AdminPlayer360DepositsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/player-360/{user_id}/ledger": get: operationId: getAdminPlayer360UserIdLedger tags: - admin - player-360 summary: Paged player wallet and ledger history (any admin) description: Complete server-paged ledger history with per-wallet-bucket changes and no raw transaction metadata. parameters: - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: player ledger history content: application/json: schema: "$ref": "#/components/schemas/AdminPlayer360LedgerResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/wallets/{user_id}": get: operationId: getAdminWalletsUserId tags: - admin summary: Admin read user wallet snapshot parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: wallet snapshot content: application/json: schema: "$ref": "#/components/schemas/WalletSnapshotResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health": get: operationId: getAdminProviderHealth tags: - admin - provider-health summary: Admin provider health list responses: '200': description: provider health content: application/json: schema: "$ref": "#/components/schemas/AdminProviderHealthResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}": get: operationId: getAdminProviderHealthProviderCode tags: - admin - provider-health summary: Admin provider health detail parameters: - "$ref": "#/components/parameters/ProviderCodeParam" responses: '200': description: provider health detail content: application/json: schema: "$ref": "#/components/schemas/AdminProviderHealthDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/read-settings": get: operationId: getAdminProviderReadSettings tags: [admin, provider-health] summary: Read the provider health read interval description: Super admin only. Uses the existing provider-health settings store. Automatic reads default to 72 hours; deployments skip a successful read within this window. PUT is compare-and-swap and requires a structured reason; stale expectations return 409. parameters: - "$ref": "#/components/parameters/ProviderCodeParam" responses: '200': description: provider read interval content: application/json: schema: "$ref": "#/components/schemas/AdminProviderReadSettings" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" put: operationId: putAdminProviderReadSettings tags: [admin, provider-health] summary: Set the provider health read interval description: Super admin only. Uses the existing provider-health settings store. Automatic reads default to 72 hours; deployments skip a successful read within this window. PUT is compare-and-swap and requires a structured reason; stale expectations return 409. parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminProviderReadSettingsRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: provider read interval content: application/json: schema: "$ref": "#/components/schemas/AdminProviderReadSettings" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/refill-settings": patch: operationId: patchAdminProviderRefillSettings tags: - admin - provider-health summary: Set the provider refill alert settings description: Super admin only. Changes alerts only; does not top up the provider or modify balances. Sets the balance threshold and the optional time limit (warn if no refill is recorded within N hours; null is off), with a structured reason. Idempotency-Key is intentionally exempt because the command is a compare-and-swap on the expected_* fields; a replay after success returns 409 and changes nothing, and a request that changes nothing is rejected. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminProviderRefillSettingsRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: saved refill settings content: application/json: schema: "$ref": "#/components/schemas/AdminProviderRefillSettings" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/refills": post: operationId: postAdminProviderRefill tags: - admin - provider-health summary: Record a provider store refill description: Records that an admin topped up the store's credits outside PlayGo (a message or a payment to the provider). It restarts the refill time limit. It moves no money and changes no balance. A retry with the same Idempotency-Key returns the original record; reusing the key for another store is a conflict. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: recorded refill (or the original record on a retry) content: application/json: schema: "$ref": "#/components/schemas/AdminProviderRefill" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/probes/read": post: operationId: postAdminProviderHealthProviderCodeProbesRead tags: - admin - provider-health summary: Run direct read provider-health probe description: Reuses a successful direct read completed in the last ten minutes without calling the provider or creating a run. Super admins may bypass the cache with force true; other admins receive 403 when forcing. Returns 409 when a read is already in progress. Each provider balance read has a five-second deadline. A timed-out read returns a completed probe with classification unknown_timeout. Its persisted run summary is provider read timed out. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/AdminProviderReadProbeRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: probe result content: application/json: schema: "$ref": "#/components/schemas/AdminProviderReadProbeResultResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/probes/launch": post: operationId: postAdminProviderHealthProviderCodeProbesLaunch tags: - admin - provider-health summary: Run direct launch provider-health probe security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/AdminProviderLaunchProbeRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: probe result content: application/json: schema: "$ref": "#/components/schemas/AdminProviderProbeResultResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/canary-accounts/{account_id}/quarantine": post: operationId: postAdminProviderHealthProviderCodeCanaryAccountsAccountIdQuarantine tags: - admin - provider-health summary: Quarantine a provider-health canary account security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" - name: account_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminProviderQuarantineCanaryRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: quarantined canary account content: application/json: schema: "$ref": "#/components/schemas/AdminProviderCanaryAccountResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/canary-accounts/bootstrap": post: operationId: postAdminProviderHealthProviderCodeCanaryAccountsBootstrap tags: - admin - provider-health summary: Bootstrap a stable canary account security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminProviderBootstrapCanaryRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: canary account content: application/json: schema: "$ref": "#/components/schemas/AdminProviderCanaryAccountResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-health/{provider_code}/acknowledge": post: operationId: postAdminProviderHealthProviderCodeAcknowledge tags: - admin - provider-health summary: Acknowledge latest provider health status security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminProviderHealthAcknowledgeRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: provider health detail content: application/json: schema: "$ref": "#/components/schemas/AdminProviderHealthDetailResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/providers": get: operationId: getAdminProviders tags: - admin summary: Admin provider list description: Game providers with their operator panel URL and how an operator verifies a transfer there, and the configured payment providers with their panel URL. Admin only; panel URLs never reach players. responses: '200': description: providers content: application/json: schema: "$ref": "#/components/schemas/AdminProvidersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/providers/{provider_code}/capabilities/{capability}": patch: operationId: patchAdminProvidersProviderCodeCapabilitiesCapability tags: - admin summary: Admin update one provider capability status description: Idempotency-Key is intentionally exempt here because the command is an explicit compare-and-swap using expected_status; duplicate submissions after success return a 409 conflict instead of applying the mutation again. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderCodeParam" - "$ref": "#/components/parameters/CapabilityParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdateProviderCapabilityRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: provider updated content: application/json: schema: "$ref": "#/components/schemas/ProviderResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/game-launch-fallbacks": get: operationId: getAdminGameLaunchFallbacks tags: - admin summary: Admin game launch fallback read model responses: '200': description: game launch fallback states content: application/json: schema: "$ref": "#/components/schemas/AdminGameLaunchFallbacksResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/game-launch-fallbacks/{game_id}": put: operationId: putAdminGameLaunchFallbacksGameId tags: - admin summary: Activate or clear one game launch fallback override security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: game_id in: path required: true schema: type: string minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PutAdminGameLaunchFallbackRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: game launch fallback updated content: application/json: schema: "$ref": "#/components/schemas/AdminGameLaunchFallbackResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-panel-links": get: operationId: getAdminProviderPanelLinks tags: - admin summary: Every game and payment provider's back-office link description: Any admin. Each row is the effective link plus where it comes from, so an admin can see what the setup file says and who last changed it. responses: '200': description: provider panel links content: application/json: schema: "$ref": "#/components/schemas/AdminProviderPanelLinksResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-panel-links/{kind}/{provider_code}": put: operationId: putAdminProviderPanelLink tags: - admin summary: Set, remove or reset one provider's back-office link description: Super admin only. Changes only the link admins open; it moves no money and touches no provider. expected_version is the version the admin read (0 if the link was never changed); a stale version returns 409 and changes nothing. A retry with the same Idempotency-Key and the same request returns the original change; the same key for a different request is a 409. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderPanelLinkKindParam" - "$ref": "#/components/parameters/ProviderPanelLinkCodeParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-provider-panel-link requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PutAdminProviderPanelLinkRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: saved link content: application/json: schema: "$ref": "#/components/schemas/AdminProviderPanelLinkResponse" '400': description: invalid request, with the typed reason content: application/json: schema: "$ref": "#/components/schemas/AdminProviderPanelLinkErrorResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-panel-links/{kind}/{provider_code}/history": get: operationId: getAdminProviderPanelLinkHistory tags: - admin summary: The last changes to one provider's back-office link description: Any admin. Newest first, at most 20. parameters: - "$ref": "#/components/parameters/ProviderPanelLinkKindParam" - "$ref": "#/components/parameters/ProviderPanelLinkCodeParam" responses: '200': description: link history content: application/json: schema: "$ref": "#/components/schemas/AdminProviderPanelLinkHistoryResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/games": get: operationId: getAdminGames tags: - admin summary: Admin game catalog list responses: '200': description: games content: application/json: schema: "$ref": "#/components/schemas/GamesResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/wallet-adjustments/preview": post: operationId: postAdminWalletAdjustmentsPreview tags: [admin] summary: Preview a multi-resource player clawback description: Computes authoritative before/after balances without mutation. Omitting items with a source payment derives the exact deposit principal and attributed rewards. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletAdjustmentPreviewRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: clawback impact and blockers content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletAdjustmentPreview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/wallet-adjustments": post: operationId: postAdminWalletAdjustments x-idempotency-required: true x-idempotency-scope: admin-wallet-adjustment tags: [admin] summary: Execute an immutable multi-resource player clawback security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminCreateWalletAdjustmentRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: clawback posted content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletAdjustmentResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': description: balance changed, funds are insufficient, source items differ, or command is in progress content: application/json: schema: {"$ref": "#/components/schemas/AdminWalletAdjustmentConflictResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/provider-accounts": get: operationId: getAdminPlayerProviderAccounts tags: [admin] summary: All provider accounts of a player, including unlinked history parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: provider account history content: application/json: schema: {"$ref": "#/components/schemas/AdminProviderAccountHistoryResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/provider-accounts/link": post: operationId: postAdminPlayerProviderAccountLink x-idempotency-required: true x-idempotency-scope: admin-provider-account-link tags: [admin] summary: Link an existing provider account to a player on their behalf security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminLinkProviderAccountRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: provider account linked content: application/json: schema: {"$ref": "#/components/schemas/AdminProviderAccountLinkResponse"} '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/players/{user_id}/aliases": get: operationId: getAdminPlayerAliases tags: [admin] summary: Active messaging aliases attached to a player parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: active aliases, oldest first content: application/json: schema: {"$ref": "#/components/schemas/PlayerAliasesResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminPlayerAlias tags: [admin] summary: Attach a messaging alias to a player description: Any admin may attach an alias; it has no money effect. The call is idempotent on the player's active alias of the same kind and case-insensitive value, which is returned with 200 instead of 201. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CreatePlayerAliasRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: the identical active alias already existed content: application/json: schema: {"$ref": "#/components/schemas/PlayerAlias"} '201': description: alias attached content: application/json: schema: {"$ref": "#/components/schemas/PlayerAlias"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/aliases/{alias_id}": delete: operationId: deleteAdminPlayerAlias tags: [admin] summary: Remove a messaging alias from a player description: Soft delete that records who removed the alias and when. Removing an alias that is already removed succeeds again. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/AliasIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': description: alias removed '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/search": get: operationId: getAdminSearch tags: [admin] summary: Find players the way operators know them description: Case-insensitive search over player accounts only (never admin accounts) by display name, email, active messaging aliases, game usernames and account identifiers, payout destination tags and payment references (deposit and withdrawal ids, provider and order references, off-app deposit references). One result per player, its best match first (exact, then prefix, then contains), then the most recent activity, which includes the player's last support message. Payout tags are returned masked only, whatever their length. Payment references match exactly or by prefix and only for queries of at least six characters. System accounts are excluded; testers are included. parameters: - name: q in: query required: true schema: {type: string, minLength: 2, maxLength: 120} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 50, default: 20} responses: '200': description: matching players content: application/json: schema: {"$ref": "#/components/schemas/AdminSearchResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/story": get: operationId: getAdminPlayerStory tags: [admin] summary: One player's history as a single chronological story description: Merges the player's deposits and their events, off-app deposits, withdrawals and their events, game transfers and their outcomes, credit moves, game-account link events, first cash-out review events, support messages and conversation events, rewards, admin reward grants, admin wallet adjustments, moderation, risk-review and financial-case decisions and admin password resets into one list, newest first, starting with the sign-up. Paging is a keyset on (occurred_at, source, id) and the first page's `as_of` is pinned in the cursor, so items that occur while an operator pages never shift or repeat rows; they appear on a fresh first page. Record rows show the record's state when the page is read, and `open` lists the records created by `as_of` that are still waiting on someone when the page is read (including support conversations with unread player messages), oldest wait first. Any admin may read it; players get 403. parameters: - name: redemptions_only in: query description: Only unload transfer receipts in completed, approved, held, restoring or rejected states; applied before pagination. Breakdowns are immutable issued facts. schema: {type: boolean} - "$ref": "#/components/parameters/UserIdParam" - name: cursor in: query required: false description: Opaque `next_cursor` of the previous page. schema: {type: string, minLength: 1, maxLength: 512} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 100, default: 50} - name: categories in: query required: false description: Only items of these categories; all categories when absent. style: form explode: false schema: type: array items: {"$ref": "#/components/schemas/AdminStoryCategory"} responses: '200': description: one page of the player's story content: application/json: schema: {"$ref": "#/components/schemas/AdminStoryPage"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/players/{user_id}/money-summary": get: operationId: getAdminPlayerMoneySummary tags: [admin] summary: One player's settled money and games at a glance description: Lets a payout reviewer check a player without searching. Counts credited deposits, completed game loads (the part paid from cash or withdrawable cash, without Bonus or Free play), completed or approved game unloads (withdrawable cash), paid and still-open payouts and the staff tips recorded on them, each for all time and for the last 7 days (`recent_since`), plus one row per game. Restorations and refused transfers move no money and are left out. Any admin may read it; players get 403. parameters: - "$ref": "#/components/parameters/UserIdParam" responses: '200': description: the player's money summary content: application/json: schema: {"$ref": "#/components/schemas/AdminPlayerMoneySummary"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/situations": get: operationId: getAdminSituations tags: [admin] summary: The Inbox, one row per real-world problem description: The admin situation feed (ADR 0019). Each row is one real-world problem composed from the existing queues and deduplicated by cause; every record it touches (financial case, reconciliation item, ops event, provider-operations risk review, unread chat) is listed in `linked` instead of becoming a row of its own. Rows use the requested server-owned sort, latest first by `since` (the default), or urgency first by severity then newest `since`, with a stable situation-key tie-break. The payouts filter includes pending game cash-out reviews. `counts` cover every filter and do not depend on the requested one. A situation exposes facts, links and backend-owned actions only, never a recommendation. Risk reviews are read as stored; reading the feed never refreshes them. Testers, system and canary accounts are excluded. Any admin may read; actions carry their own role gates. parameters: - name: filter in: query required: false schema: {"$ref": "#/components/schemas/AdminSituationFilter"} - name: sort in: query required: false schema: {"$ref": "#/components/schemas/AdminSituationSort"} - name: cursor in: query required: false description: Opaque `next_cursor` of the previous page. It pins the first page's snapshot time. schema: {type: string, minLength: 1, maxLength: 1024} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 100, default: 50} responses: '200': description: one page of situations with global counts content: application/json: schema: {"$ref": "#/components/schemas/AdminSituationPage"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/situations/read": post: operationId: postAdminSituationsRead tags: [admin] summary: Mark one or all open situations as read for signed-in staff description: Marks the same open situations included in the global unread count, including unloaded pages. A retry with the same time does not mark newer situations. This does not resolve any situation or mark chat messages handled. security: - csrfToken: [] parameters: - {"$ref": "#/components/parameters/ClientBuildHeader"} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [as_of] properties: as_of: {type: string, format: date-time, description: Latest situation time to acknowledge.} situation_key: {type: string, minLength: 1, maxLength: 200, description: Omit to acknowledge all open situations.} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': {description: Read markers saved for signed-in staff} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/situations/{situation_key}": get: operationId: getAdminSituation tags: [admin] summary: One situation as it stands now description: Looks a situation up by its stable key, for example `transfer:`, `device:` or `provider:`. A situation that no longer needs a human is 404. parameters: - name: situation_key in: path required: true schema: {type: string, minLength: 1, maxLength: 200} responses: '200': description: the situation content: application/json: schema: {"$ref": "#/components/schemas/AdminSituation"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/provider-accounts/{provider_account_id}/reconnect": post: operationId: postProviderAccountReconnect x-idempotency-required: true x-idempotency-scope: provider-account-reconnect tags: [games] summary: Verify the current game password and reconnect this same account description: Reconnect is available only when the game can verify the supplied password. A game without password proof returns a capability-unavailable refusal. Failed verification returns credentials_rejected with field=password and leaves the saved credential and balance intact. After confirmed repair, the client explicitly refreshes the game balance. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountReconnectRequest"} responses: '200': description: Confirmed credential replacement; reset password appears only on the initial response headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountCredentialRepairResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} '503': description: Provider outcome unknown; saved credentials remain unchanged content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/set-password": post: operationId: postAdminProviderAccountSetPassword x-idempotency-required: true x-idempotency-scope: admin-provider-account-set-password tags: [admin] summary: Verify and save the current password staff set in the provider panel security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountSetPasswordRequest"} responses: '200': description: Confirmed credential replacement; reset password appears only on the initial response headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountCredentialRepairResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} '503': description: Provider outcome unknown; saved credentials remain unchanged content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/reset-password": post: operationId: postAdminProviderAccountResetPassword x-idempotency-required: true x-idempotency-scope: admin-provider-account-reset-password tags: [admin] summary: Reset the game password using the supplied current password security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountResetPasswordRequest"} responses: '200': description: Confirmed credential replacement; reset password appears only on the initial response headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountCredentialRepairResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} '503': description: Provider outcome unknown; saved credentials remain unchanged content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/unlink-preview": post: operationId: postAdminProviderAccountUnlinkPreview x-idempotency-required: true x-idempotency-scope: admin-provider-account-unlink-preview summary: Own a short preview lease and verify live zero without changing money tags: [admin] security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UnlinkPreviewRequest"} responses: '200': description: Explicit ready or blocked preview with original expiry headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/UnlinkPreviewResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/unlink-preview/{preview_id}/cancel": post: operationId: postAdminProviderAccountUnlinkPreviewCancel x-idempotency-required: true x-idempotency-scope: admin-provider-account-unlink-preview-cancel summary: Cancel this actor's own preview without releasing a newer owner or undoing a consumed unlink tags: [admin] security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: preview_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: Current consumed or cancelled state headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/UnlinkPreviewCancelResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/retry-link-verification": post: operationId: postAdminProviderAccountLinkRetry x-idempotency-required: true x-idempotency-scope: admin-provider-account-link-retry tags: [admin] summary: Verify a corrected existing account in a new child of a failed attempt security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/LinkVerificationRetryRequest"} responses: '200': description: New local child linked after one read-only verification; original failed attempt retained headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/LinkVerificationRetryResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/record-panel-password": post: operationId: postAdminProviderAccountPanelPassword x-idempotency-required: true x-idempotency-scope: admin-provider-account-panel-password tags: [admin] summary: Record a staff-confirmed current panel password locally, without provider IO security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/RecordPanelPasswordRequest"} responses: '200': description: Panel-attested credential saved; password is never returned headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/AccountManagementCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/missing-passwords": get: operationId: getAdminMissingProviderPasswords tags: [admin] summary: Read the staff password recovery and backfill list parameters: - in: query name: after schema: { type: string, format: uuid } - in: query name: limit schema: { type: integer, minimum: 1, maximum: 100, default: 50 } responses: "200": description: Active game accounts without a saved login, no mutations content: application/json: schema: $ref: "#/components/schemas/MissingProviderPasswordsResponse" "401": $ref: "#/components/responses/UnauthorizedError" "403": $ref: "#/components/responses/ForbiddenError" default: $ref: "#/components/responses/DefaultError" "/api/v1/admin/provider-accounts/{provider_account_id}/password-access": post: operationId: postAdminProviderAccountPasswordAccess x-idempotency-required: true x-idempotency-scope: admin-provider-account-password-access x-playgo-command: idempotency: {required: true, scope: admin-provider-account-password-access} tags: [admin] summary: Explicit audited access to this site's saved game password description: Active staff only. Re-authorizes every use and replay against the exact current account and credential witness. Audit and replay contain identifiers only; passive account reads never decrypt a password or contact a provider. A copy grant records a copy request, not successful browser clipboard delivery. security: [{csrfToken: []}] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountPasswordAccessRequest"} responses: '200': description: Exact saved credential; do not cache or persist this response headers: Cache-Control: {required: true, schema: {type: string, enum: [no-store]}} content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountPasswordAccessResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/history": get: operationId: getAdminProviderAccountHistory tags: [admin] summary: Bounded account-scoped activity without provider IO or secret disclosure parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" - name: after in: query schema: {type: string, maxLength: 1024} - name: limit in: query schema: {type: integer, minimum: 1, maximum: 100, default: 50} responses: '200': description: Account activity newest first; cursor reads older activity content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountActivityResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/management": get: operationId: getAdminProviderAccountManagement tags: [admin] summary: Read account identity, credential provenance and management history without provider IO parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" responses: '200': description: Read-only, nonsecret management snapshot content: application/json: schema: {"$ref": "#/components/schemas/AccountManagementSnapshot"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/repair-options": get: operationId: getAdminProviderAccountRepairOptions tags: [admin] summary: Read configured account repair capabilities without contacting the provider parameters: - "$ref": "#/components/parameters/ProviderAccountIdParam" responses: '200': description: Adapter-owned verification and reset capabilities content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountRepairOptions"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/recheck": post: operationId: postAdminProviderAccountRecheck x-idempotency-required: true x-idempotency-scope: admin-provider-account-recheck tags: [admin] summary: Deliberately verify current identity and balance without changing external identity security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountRecheckRequest"} responses: '200': description: Audited verification result; unknown or changed identity keeps suppression content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountRepairResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/relink": post: operationId: postAdminProviderAccountRelink x-idempotency-required: true x-idempotency-scope: admin-provider-account-relink tags: [admin] summary: Verify and audit a replacement external identity on the same account security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountRelinkRequest"} responses: '200': description: Audited verification result; unknown or changed identity keeps suppression content: application/json: schema: {"$ref": "#/components/schemas/ProviderAccountRepairResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/provider-accounts/{provider_account_id}/unlink": post: operationId: postAdminProviderAccountUnlink x-idempotency-required: true x-idempotency-scope: admin-provider-account-unlink tags: [admin] summary: Unlink a player's provider account without deleting its history security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ProviderAccountIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminUnlinkProviderAccountRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: provider account unlinked headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/AdminProviderAccountUnlinkResponse"} '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/first-unload-reviews": get: operationId: getAdminFirstUnloadReviews tags: [admin] summary: First-unload review queue parameters: - name: state in: query required: false schema: {"$ref": "#/components/schemas/FirstUnloadReviewState"} responses: '200': description: first-unload reviews content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewListResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/first-unload-reviews/{review_id}": get: operationId: getAdminFirstUnloadReview tags: [admin] summary: First-unload review detail with evidence parameters: - "$ref": "#/components/parameters/ReviewIdParam" responses: '200': description: first-unload review content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewDetail"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/first-unload-reviews/{review_id}/approve": post: operationId: postAdminFirstUnloadReviewApprove x-idempotency-required: true x-idempotency-scope: admin-first-unload-review-approve tags: [admin] summary: Approve a first unload after assignment confirmation and a fresh balance re-read description: Requires assignment confirmation and a fresh provider balance equal to the reviewed snapshot; a changed balance returns rereview_required with the new snapshot and nothing is debited. The approved payout may be any whole-cent amount from 0 to the cash value of the whole-credit debit. The wallet is credited only after a fresh balance read verifies zero whole credits. Vendor dust remains untracked in the game account. Maker-checker - the admin who requested the review or linked the account on the player's behalf cannot approve it (409 maker_checker_conflict). security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ReviewIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminApproveFirstUnloadReviewRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: approval accepted content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewCommandResponse"} '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/first-unload-reviews/{review_id}/refresh": post: operationId: postAdminFirstUnloadReviewRefresh tags: [admin] summary: Refresh a pending first-unload balance snapshot without debiting the provider security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ReviewIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: current review snapshot content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewCommandResponse"} '400': {"$ref": "#/components/responses/ProviderAccountImportBadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ProviderAccountImportConflictError"} '503': {"$ref": "#/components/responses/ProviderAccountImportUnavailableError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/first-unload-reviews/{review_id}/reject": post: operationId: postAdminFirstUnloadReviewReject x-idempotency-required: true x-idempotency-scope: admin-first-unload-review-reject tags: [admin] summary: Reject a pending first-unload review without any provider call security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ReviewIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminRejectFirstUnloadReviewRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: review rejected content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewCommandResponse"} '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/first-unload-reviews/{review_id}/resolve": post: operationId: postAdminFirstUnloadReviewResolve x-idempotency-required: true x-idempotency-scope: admin-first-unload-review-resolve tags: [admin] summary: Resolve a reviewed first unload whose provider debit outcome is unproven description: Super-admin only. Only for reviews in reconcile_required whose transfer is still unresolved. Never calls a mutating provider API. debit_confirmed first requires a fresh balance read verifying zero whole provider credits; if it is unavailable or different NOTHING is persisted and the response is 503 zero_balance_unverified (definite no-change; retry later with a new key). With a verified expected balance, the attestation (including when it was observed), its audit event and the idempotency result commit atomically and the response is 200. Settlement is then attempted in the same call on a best-effort basis - the 200 review is normally settled, but if settlement itself fails (e.g. amount policy or database error) the 200 review is still reconcile_required with debit_confirmed=true and nothing credited, and the reconciler settles it later only after another verified expected-balance read. Replaying the key returns the latest review state. debit_not_applied (allowed only before any debit confirmation) marks the transfer rejected and returns the review to pending; it moves no PlayGo money. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ReviewIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminResolveFirstUnloadReviewRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: review resolved content: application/json: schema: {"$ref": "#/components/schemas/AdminFirstUnloadReviewCommandResponse"} '400': "$ref": "#/components/responses/ProviderAccountImportBadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ProviderAccountImportConflictError" '503': "$ref": "#/components/responses/ProviderAccountImportUnavailableError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-deposits": get: operationId: getAdminPaymentDeposits tags: - admin summary: Admin payment deposit list parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: user_id in: query required: false schema: type: string format: uuid - name: provider_code in: query required: false schema: "$ref": "#/components/schemas/PaymentDepositProviderCode" - name: state in: query required: false schema: "$ref": "#/components/schemas/PaymentDepositState" - name: created_from in: query required: false schema: type: string format: date-time - name: created_to in: query required: false schema: type: string format: date-time responses: '200': description: admin payment deposits content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentDepositsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" post: operationId: postAdminPaymentDepositsOffApp x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-create tags: [admin] summary: Create an off-app deposit draft, or record and credit it in one step description: Any active admin creates an unsettled draft, or sets settle_now to create and settle it (credit the player's Playable Cash) in one audited transaction with no super-admin approval. settle_now requires reason_code (400 without it). Non-admins get 403. reason_code and note are ignored without settle_now. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminCreateOffAppDepositRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: off-app deposit draft created, or created and settled when settle_now was set content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}": get: operationId: getAdminPaymentDepositsPaymentId tags: - admin summary: Admin payment deposit detail parameters: - name: payment_id in: path required: true schema: type: string format: uuid responses: '200': description: admin payment deposit detail content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentDepositDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" put: operationId: putAdminPaymentDepositsPaymentIdOffApp x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-update tags: [admin] summary: Edit an unsettled off-app deposit draft security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminUpdateOffAppDepositRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: off-app deposit draft updated content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/settle": post: operationId: postAdminPaymentDepositsPaymentIdSettle x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-settle tags: [admin] summary: Settle an off-app deposit draft security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminSettleOffAppDepositRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Off-app settlement recorded. Whole-dollar and X.99 principals are credited by the shared deposit rule; unsupported settled principals enter reconciliation without wallet credit. content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/void": post: operationId: postAdminPaymentDepositsPaymentIdVoid x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-void tags: [admin] summary: Void an unsettled off-app deposit draft security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminVoidOffAppDepositRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: off-app deposit voided content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/convert-to-off-app": post: operationId: postAdminPaymentDepositsPaymentIdConvertToOffApp x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-convert tags: [admin] summary: Convert a stuck provider deposit into a settled off-app deposit description: Super admin only. For a provider deposit that was never credited and is still open (checkout created or stale, provider pending, player or KYC pending, or awaiting reconciliation) but was paid another way. In one audited transaction it records and credits an off-app deposit linked by supersedes_payment_id and moves the original to the terminal superseded state. A later provider success on the original never credits; it opens a deposit financial case. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminConvertDepositToOffAppRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: the settled off-app deposit that supersedes the original content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/reversal-preview": get: operationId: getAdminPaymentDepositsPaymentIdReversalPreview tags: [admin] summary: Preview an off-app deposit compensating reversal parameters: - name: payment_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: reversal impact and blockers content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositReversalPreview"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/reverse": post: operationId: postAdminPaymentDepositsPaymentIdReverse x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-reverse tags: [admin] summary: Confirm an off-app deposit compensating reversal security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminReverseOffAppDepositRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: off-app deposit reversed content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': description: reversal blocked without financial mutation content: application/json: schema: {"$ref": "#/components/schemas/AdminOffAppDepositReversalConflictResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/proof-assets": post: operationId: postAdminPaymentDepositsPaymentIdProofAssets x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-proof-initiate tags: [admin] summary: Initiate a private off-app deposit proof upload security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminInitiateWithdrawalProofUploadRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: private proof upload initiated content: application/json: schema: {"$ref": "#/components/schemas/AdminDepositProofUploadResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/proof-assets/{proof_id}/finalize": post: operationId: postAdminPaymentDepositsPaymentIdProofAssetsProofIdFinalize x-idempotency-required: true x-idempotency-scope: payment-off-app-deposit-proof-finalize tags: [admin] summary: Finalize and verify a private off-app deposit proof upload security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: proof_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: proof finalized content: application/json: schema: {"$ref": "#/components/schemas/AdminDepositProofAssetResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-deposits/{payment_id}/proof-assets/{proof_id}/preview": get: operationId: getAdminPaymentDepositsPaymentIdProofAssetsProofIdPreview tags: [admin] summary: Create an authenticated short-lived off-app deposit proof preview parameters: - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: proof_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: short-lived signed preview content: application/json: schema: {"$ref": "#/components/schemas/AdminWithdrawalProofPreviewResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payments/deposit-policy": get: operationId: getAdminDepositPolicy tags: [admin] summary: Get deposit provider policy (admin access) parameters: - in: query name: history schema: {type: boolean, default: false} description: Include the latest 30 audited payment-settings changes. responses: '200': description: Deposit provider policy content: application/json: schema: {"$ref": "#/components/schemas/AdminDepositPolicy"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminDepositPolicy tags: [admin] summary: Update deposit provider policy (super-admin only) security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UpdateAdminDepositPolicyRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Deposit provider policy updated content: application/json: schema: {"$ref": "#/components/schemas/AdminDepositPolicy"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/nowpayments-payout-policy": get: operationId: getAdminNowPaymentsPayoutPolicy tags: [admin] summary: Get NOWPayments automatic payout policy (super-admin only) responses: '200': description: payout policy content: application/json: schema: {"$ref": "#/components/schemas/AdminNowPaymentsPayoutPolicy"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} patch: operationId: patchAdminNowPaymentsPayoutPolicy tags: [admin] summary: Toggle NOWPayments automatic payouts (super-admin only) security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminNowPaymentsPayoutPolicyUpdate"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: payout policy updated content: application/json: schema: {"$ref": "#/components/schemas/AdminNowPaymentsPayoutPolicy"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/notifications/bundle-policy": get: operationId: getAdminNotificationBundlePolicy tags: [admin] summary: Read notification bundle switches (active staff) responses: "200": description: Current default-ON notification policy content: application/json: schema: {"$ref": "#/components/schemas/AdminNotificationBundlePolicy"} "401": {"$ref": "#/components/responses/UnauthorizedError"} "403": {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminNotificationBundlePolicy tags: [admin] security: - csrfToken: [] summary: Replace notification switches with audited version CAS (super-admin) description: Full replacement. Repeating an accepted expected_version returns conflict without another change. An uncertain response requires reloading the current policy before another edit. parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminNotificationBundlePolicyReplace"} responses: "426": {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: Saved notification policy content: application/json: schema: {"$ref": "#/components/schemas/AdminNotificationBundlePolicy"} "400": {"$ref": "#/components/responses/BadRequestError"} "401": {"$ref": "#/components/responses/UnauthorizedError"} "403": {"$ref": "#/components/responses/ForbiddenError"} "409": {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications": get: operationId: getAdminExternalNotifications tags: [admin] summary: External notification settings, recipients and event catalog (super-admin only) responses: '200': description: external notification settings content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/recipients": post: operationId: postAdminExternalNotificationsRecipients tags: [admin] summary: Add an external notification recipient (super-admin only) description: A new recipient only receives events that happen after it is saved. Idempotency-Key is intentionally exempt because a duplicate address is rejected with 409. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationRecipientCreate"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: recipient created content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationRecipient"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/recipients/{recipient_id}": patch: operationId: patchAdminExternalNotificationsRecipientsRecipientId tags: [admin] summary: Update, pause or resume an external notification recipient (super-admin only) description: Pausing or changing the address cancels everything queued but unsent, and resuming or changing the address restarts the history cutoff. expected_version provides optimistic concurrency. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ExternalNotificationRecipientIdParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationRecipientUpdate"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: recipient updated content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationRecipient"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} delete: operationId: deleteAdminExternalNotificationsRecipientsRecipientId tags: [admin] summary: Remove an external notification recipient (super-admin only) description: The recipient is archived so delivery and audit history remain; queued emails are cancelled. The address can be added again afterwards. Idempotency-Key is intentionally exempt because removal is guarded by expected_version. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ExternalNotificationRecipientIdParam" - name: expected_version in: query required: true schema: {type: integer, minimum: 1} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': description: recipient removed '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/recipients/{recipient_id}/test": post: operationId: postAdminExternalNotificationsRecipientsRecipientIdTest tags: [admin] summary: Queue a test email to a saved recipient (super-admin only) description: Uses the normal outbox and is rate limited to one per minute per recipient. Idempotency-Key is intentionally exempt because the cooldown bounds repeats. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ExternalNotificationRecipientIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '202': description: test email queued content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationDelivery"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '429': {"$ref": "#/components/responses/RateLimitedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/telegram": get: operationId: getAdminExternalNotificationsTelegram tags: [admin] summary: Telegram alert channel state (super-admin only) description: The bot (token always masked, never returned in full) and each recipient's link state. A recipient is waiting_for_start until that admin sends /start to the bot. responses: '200': description: telegram channel state content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramOverview"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/telegram/bot": put: operationId: putAdminExternalNotificationsTelegramBot tags: [admin] summary: Set the Telegram bot token (super-admin only) description: The token is checked with Telegram (getMe), stored sealed and never returned. 400 when the token is malformed or Telegram rejects it; 409 when the bot is already polled or has a webhook elsewhere (used by another site). Replacing it with a different bot unlinks every recipient (each must send /start again) and drops queued Telegram messages. Idempotency-Key is intentionally exempt because the call replaces the one stored token. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramBotInput"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: bot stored content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramOverview"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} delete: operationId: deleteAdminExternalNotificationsTelegramBot tags: [admin] summary: Remove the Telegram bot (super-admin only) description: Unlinks every recipient and drops queued Telegram messages. Idempotency-Key is intentionally exempt because removal is naturally idempotent. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: bot removed content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramOverview"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/telegram/bot/test": post: operationId: postAdminExternalNotificationsTelegramBotTest tags: [admin] summary: Check the configured Telegram bot (super-admin only) description: Calls only getMe with the stored sealed token. No linked recipient is needed; no message is sent and no updates are consumed. 409 if no token is configured, 400 if Telegram rejects it, 503 if Telegram is unavailable or returns an invalid response. Idempotency-Key is intentionally exempt because the check has no state-changing side effects. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '200': description: bot reachable and authenticated content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramBotHealth"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/recipients/{recipient_id}/telegram": put: operationId: putAdminExternalNotificationsRecipientsRecipientIdTelegram tags: [admin] summary: Set or clear a recipient's Telegram username (super-admin only) description: Case-insensitive; a leading @ is ignored. Every save, including the same username, resets the learned chat and requires a fresh /start. A null or empty username removes only Telegram setup, including while waiting, and skips queued Telegram messages; email identity and subscriptions are preserved. Idempotency-Key is intentionally exempt because this explicit relink command resets one channel. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ExternalNotificationRecipientIdParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramUsernameInput"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: username stored content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramRecipient"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/recipients/{recipient_id}/telegram/test": post: operationId: postAdminExternalNotificationsRecipientsRecipientIdTelegramTest tags: [admin] summary: Queue a test Telegram message to a linked recipient (super-admin only) description: The message is sent immediately and the outcome is in last_message (sent, failed with an error, or queued for retry). Rate limited to one per minute per recipient. 409 when the bot is not configured or the recipient has not sent /start. Idempotency-Key is intentionally exempt because the cooldown bounds repeats. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/ExternalNotificationRecipientIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '202': description: test message queued content: application/json: schema: {"$ref": "#/components/schemas/AdminTelegramRecipient"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '429': {"$ref": "#/components/responses/RateLimitedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/deliveries": get: operationId: getAdminExternalNotificationsDeliveries tags: [admin] summary: Recent external notification deliveries (super-admin only) parameters: - name: recipient_id in: query required: false schema: {type: string, format: uuid} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 200, default: 50} responses: '200': description: recent deliveries, newest first content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveriesResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/external-notifications/deliveries/{delivery_id}": get: operationId: getAdminExternalNotificationsDeliveriesDeliveryId tags: [admin] summary: One delivery with its full event membership (super-admin only) parameters: - name: delivery_id in: path required: true schema: {type: string, format: uuid} - name: offset in: query required: false schema: {type: integer, minimum: 0, default: 0} - name: limit in: query required: false schema: {type: integer, minimum: 1, maximum: 500, default: 100} responses: '200': description: delivery detail content: application/json: schema: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveryDetail"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/closeouts/preview": post: operationId: postAdminCloseoutPreview tags: [admin] summary: Preview closing stale, never-paid deposits as abandoned description: Super admins only (ADR 0019, CONTRACTS C5b). Starts from the close-out candidates the Inbox counts (playgo_payment_closeout_candidates with the 24 hour threshold) - stale provider checkouts and unsettled off-app drafts, never credited (including a durable wallet credit not yet recorded on the intent), with no provider webhook or timeout, and no player waiting in chat. Each provider checkout is then checked with its provider. Only an affirmative non-payment (not found) or a provider with no status lookup keeps a checkout closeable. A paid or failed one goes through the reconciler (credited, or marked failed); an errored, timed-out or skipped lookup and any inconclusive status are listed under excluded and are never bulk-closed. Lookups run at most 4 at a time, 10 seconds each, within a 15 second budget, shortened to reserve time before the handler deadline. Closing has no wallet effect. The token is single-use, valid for 10 minutes, bound to exactly the listed items and to the admin who previewed. At most 25 candidates are checked; has_more says more are eligible. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: close-out preview content: application/json: schema: {"$ref": "#/components/schemas/CloseoutPreview"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/closeouts": post: operationId: postAdminCloseout tags: [admin] summary: Close the previewed deposits as abandoned description: Super admins only. Moves every previewed item to the terminal abandoned state with a closed_out audit event carrying the reason. No wallet effect. A refused confirm returns 409 with a typed reason and closes nothing - token_used (already confirmed by this admin; closed_count and ids report what that confirm closed, so a retry after a lost response learns the outcome), token_expired, token_foreign (another admin's token, or one never issued) or items_changed (an item stopped being eligible or was touched since the preview). A provider success that arrives after close-out never credits; it opens a financial case. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CloseoutRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: closed items content: application/json: schema: {"$ref": "#/components/schemas/CloseoutResult"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': description: confirm refused; nothing was closed by this call content: application/json: schema: {"$ref": "#/components/schemas/CloseoutConflict"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payouts/notifications": get: operationId: getAdminPayoutNotifications summary: Read the latest payout event facts description: Active staff only. Returns at most 50 immutable events, newest first. Approval is not payment; this feed creates no financial command. responses: "200": description: Bounded payout feed; items is empty when opted out content: application/json: schema: {"$ref": "#/components/schemas/AdminPayoutNotifications"} "401": {"$ref": "#/components/responses/UnauthorizedError"} "403": {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payouts/board": get: operationId: getAdminPayoutBoard tags: [admin] summary: Every payout on one board, by who has to act description: Any admin may read the board (ADR 0019). Lanes are needs_you (awaiting approval, or approved and waiting for an admin to send the money), in_flight (automatic payouts being processed), problems (provider action, reconciliation, internal failure, anything past its expected time) and done_recent (completed within the range). Each lane lists at most lane_limit rows, oldest first except done_recent (newest first); count is the full lane size. Late uses the payout settings. Money totals are computed by the database. parameters: - name: range in: query required: false schema: {"$ref": "#/components/schemas/PayoutBoardRange"} - name: lane_limit in: query required: false schema: {type: integer, minimum: 1, maximum: 100, default: 25} responses: '200': description: payout board content: application/json: schema: {"$ref": "#/components/schemas/PayoutBoard"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payouts/settings": get: operationId: getAdminPayoutSettings tags: [admin] summary: Payout late thresholds and the mark-paid proof requirement description: Any admin may read the settings and their recent change history. responses: '200': description: payout settings content: application/json: schema: {"$ref": "#/components/schemas/PayoutSettingsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminPayoutSettings tags: [admin] summary: Change the payout settings description: Super admins only. The change is a compare-and-set on expected_version and is recorded with the actor, reason code and note. Manual late thresholds range from 15 minutes to 14 days, automatic ones from 5 minutes to 7 days, in whole minutes. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UpdatePayoutSettingsRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated payout settings content: application/json: schema: {"$ref": "#/components/schemas/PayoutSettingsResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-settings": get: operationId: getAdminBonusSettings tags: [admin] summary: The deployment's bonus rule settings and their change history description: Any admin may read the current bonus rules (ADR 0023), their version, who changed them last, and the most recent changes, newest first, at most 20. Money is integer cents; percentages are basis points. responses: '200': description: bonus settings content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusSettingsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminBonusSettings tags: [admin] summary: Change the bonus rule settings description: Super admins only. Replaces every value at once as a compare-and-set on expected_version; a stale version returns 409 and changes nothing. The change applies to rewards settled after it commits; earned, pending and frozen referral amounts never change. It is recorded with the actor, reason code, note and the previous and next values. referral_tier is a system reason and returns 400. A retry with the same Idempotency-Key and the same request returns the original result; the same key for a different request is a 409. Percentages are whole percents written as basis points (multiples of 100) until the player contract carries basis points. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-settings requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/PutAdminBonusSettingsRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated bonus settings content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusSettingsResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/referrals/referrers": get: operationId: listAdminReferralReferrers tags: [admin] summary: Players who invited friends, with what their invitations earned description: Any admin. Read-only over the referral codes, selections and frozen referral outcomes. Ordered by rewarded friends, then invited friends, then the newest invitation. q matches the referrer's email, display name or referral code, case-insensitively. parameters: - name: q in: query required: false schema: {type: string, minLength: 2, maxLength: 100} - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: referrers content: application/json: schema: {"$ref": "#/components/schemas/AdminReferralReferrerListResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/referrals/referrers/{user_id}": get: operationId: getAdminReferralReferrer tags: [admin] summary: One referrer and the friends they invited description: Any admin. Friends are newest first. A friend's amounts are the frozen qualification amounts (including historical game-load awards). parameters: - name: user_id in: path required: true schema: {type: string, format: uuid} - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: referrer detail content: application/json: schema: {"$ref": "#/components/schemas/AdminReferralReferrerDetailResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-settings/preview": post: operationId: previewAdminBonusSettings tags: [admin] summary: Example payouts for a set of bonus rule values, computed by the server description: Any admin. Read-only; nothing is saved, so no Idempotency-Key. The examples are the base-rule payouts for fixed sample deposits and loads, computed in Postgres (ADR 0015). Values out of bounds return 400. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/BonusPreviewRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: example payouts content: application/json: schema: {"$ref": "#/components/schemas/BonusPreviewResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-history": get: operationId: listAdminBonusHistory tags: [admin] summary: Every change to bonus rules, schemes, enrolments and perk tiers description: Any admin. Newest first. Automatic perk-tier enrolments have no actor. parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: bonus history content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusHistoryResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes/readiness": post: operationId: previewAdminBonusSchemeReadiness tags: [admin] security: [{csrfToken: []}] summary: Preview scheme availability without saving requestBody: required: true content: application/json: schema: {$ref: "#/components/schemas/BonusSchemeReadinessPreviewRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: Backend-owned readiness for the proposed scheme; no changes saved content: application/json: schema: {$ref: "#/components/schemas/SettingsReadiness"} default: {$ref: "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes": get: operationId: listAdminBonusSchemes tags: [admin] summary: Special bonus schemes description: Any admin. Newest first. responses: '200': description: schemes content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusSchemeListResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: createAdminBonusScheme tags: [admin] summary: Create a special bonus scheme description: Super admins only. A scheme overrides some base rules for its enrolled players; per rule, a player gets the single best payout of the base rule and their active schemes, never a sum. Names are unique (409). A retry with the same Idempotency-Key and request returns the original scheme; the same key for another request is a 409. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-schemes requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CreateAdminBonusSchemeRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: created scheme content: application/json: schema: {"$ref": "#/components/schemas/BonusScheme"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes/{scheme_id}": get: operationId: getAdminBonusScheme tags: [admin] summary: One special bonus scheme parameters: - "$ref": "#/components/parameters/BonusSchemeIdParam" responses: '200': description: scheme content: application/json: schema: {"$ref": "#/components/schemas/BonusScheme"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminBonusScheme tags: [admin] summary: Change a special bonus scheme description: Super admins only. Replaces the name, status, dates and overrides as a compare-and-set on expected_version (409 when stale). Changes apply to later settlements only. Idempotent per Idempotency-Key. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/BonusSchemeIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-schemes requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/PutAdminBonusSchemeRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: updated scheme content: application/json: schema: {"$ref": "#/components/schemas/BonusScheme"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes/{scheme_id}/enabled": put: operationId: setAdminBonusSchemeEnabled tags: [admin] summary: Turn any special scheme on or off description: Superadmins only. Audited version compare-and-set, idempotent. On activates in the same request. Off changes no rules, dates, enrollments or frozen awards. New schemes save Off; live edits preserve availability. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/BonusSchemeIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-schemes requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/SetAdminBonusSchemeEnabledRequest"} responses: '200': description: Updated scheme, with availability and audit version content: application/json: schema: {"$ref": "#/components/schemas/BonusScheme"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes/{scheme_id}/enrollments": get: operationId: listAdminBonusSchemeEnrollments tags: [admin] summary: Players actively enrolled in a scheme description: Any admin. Newest first. parameters: - "$ref": "#/components/parameters/BonusSchemeIdParam" - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: enrolments content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusSchemeEnrollmentListResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: enrollAdminBonusScheme tags: [admin] summary: Enrol players in a scheme by email description: Super admins only. Emails are matched to existing players, case-insensitively; unknown emails are returned, never created. Players already actively enrolled are returned separately and unchanged. Idempotent per Idempotency-Key. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/BonusSchemeIdParam" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-schemes requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/EnrollAdminBonusSchemeRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: enrolment result content: application/json: schema: {"$ref": "#/components/schemas/AdminBonusSchemeEnrollResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/bonus-schemes/{scheme_id}/enrollments/{enrollment_id}/remove": post: operationId: removeAdminBonusSchemeEnrollment tags: [admin] summary: Remove a player from a scheme description: Super admins only. The player keeps rewards already earned. Removing an enrolment that is already removed is a no-op. Idempotent per Idempotency-Key. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/BonusSchemeIdParam" - name: enrollment_id in: path required: true schema: {type: string, format: uuid} - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-schemes requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/RemoveAdminBonusSchemeEnrollmentRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': description: removed '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/referrals/perk-tiers": get: operationId: getAdminReferralPerkTiers tags: [admin] summary: Top-referrer perk tiers description: Any admin. Reaching a tier's count of rewarded referrals enrols the inviter in the tier's scheme when a referral reward settles. responses: '200': description: perk tiers content: application/json: schema: {"$ref": "#/components/schemas/AdminReferralPerkTiersResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminReferralPerkTiers tags: [admin] summary: Replace the top-referrer perk tiers description: Super admins only. Replaces the whole list as a compare-and-set on expected_version (409 when stale). New tiers apply from the next settled referral reward. Idempotent per Idempotency-Key. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" x-idempotency-required: true x-idempotency-scope: admin-bonus-perk-tiers requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/PutAdminReferralPerkTiersRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: perk tiers content: application/json: schema: {"$ref": "#/components/schemas/AdminReferralPerkTiersResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/users/{user_id}/bonus-rules": get: operationId: getAdminUserBonusRules tags: [admin] summary: The bonus rules that apply to one player description: Any admin. Lists the player's active schemes and, per rule, the rule with the highest maximum payout and which scheme supplied it (absent = base rule). A claim compares the actual payouts of the base rule and each active scheme and pays the higher. parameters: - name: user_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: effective bonus rules content: application/json: schema: {"$ref": "#/components/schemas/AdminUserBonusRulesResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals": get: operationId: getAdminPaymentWithdrawals tags: - admin summary: Admin payment withdrawal list parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: user_id in: query required: false schema: type: string format: uuid - name: provider_code in: query required: false schema: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" - name: state in: query required: false schema: "$ref": "#/components/schemas/PaymentWithdrawalState" - name: tier in: query required: false schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalTier" - name: queue in: query required: false schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalQueue" - name: created_from in: query required: false schema: type: string format: date-time - name: created_to in: query required: false schema: type: string format: date-time responses: '200': description: admin payment withdrawals content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalsResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-withdrawals/{payment_id}/acknowledge": post: operationId: postAdminPaymentWithdrawalsPaymentIdAcknowledge tags: - admin summary: Acknowledge a withdrawal for the shared operator inbox description: Idempotently records the first admin who reviewed the withdrawal. This does not change its financial lifecycle state. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_id in: path required: true schema: type: string format: uuid responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: acknowledged admin payment withdrawal content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalAcknowledgementResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-withdrawals/{payment_id}": get: operationId: getAdminPaymentWithdrawalsPaymentId tags: - admin summary: Admin payment withdrawal detail parameters: - name: payment_id in: path required: true schema: type: string format: uuid responses: '200': description: admin payment withdrawal detail content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalDetailResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-withdrawals/{payment_id}/paying-claim": get: operationId: getAdminPaymentWithdrawalsPaymentIdPayingClaim tags: [admin] summary: Read paying claim status parameters: - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: attempt_id in: query schema: {type: string, format: uuid} responses: '200': description: Current paying claim status content: application/json: schema: {"$ref": "#/components/schemas/WithdrawalPayingClaimStatus"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: postAdminPaymentWithdrawalsPaymentIdPayingClaim tags: [admin] summary: Claim a hand-paid cash-out before paying security: - csrfToken: [] parameters: - {"$ref": "#/components/parameters/ClientBuildHeader"} - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/WithdrawalPayingClaimRequest"} responses: '200': description: Current paying claim status content: application/json: schema: {"$ref": "#/components/schemas/WithdrawalPayingClaimStatus"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} delete: operationId: deleteAdminPaymentWithdrawalsPaymentIdPayingClaim tags: [admin] summary: Release a claim after confirming nothing was sent security: - csrfToken: [] parameters: - {"$ref": "#/components/parameters/ClientBuildHeader"} - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/WithdrawalPayingClaimRequest"} responses: '204': {description: Claim released} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/mark-paid": post: operationId: postAdminPaymentWithdrawalsPaymentIdMarkPaid x-idempotency-required: true x-idempotency-scope: payment-withdrawal-mark-paid tags: - admin summary: Admin approves a hand-paid cash-out, which records it paid description: The Approve of a cash-out an admin sends by hand (ADR 0019, 2026-11-16 amendment). The admin must answer Yes to "Did you pay the player already?" (player_paid_confirmed true); approving records the cash-out paid in one step. A payout approved before the amendment (provider_created) is finished the same way. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminMarkPaymentWithdrawalPaidRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: admin payment withdrawal marked paid content: application/json: schema: "$ref": "#/components/schemas/AdminPaymentWithdrawalCommandResponse" '400': description: Invalid manual payout details; admins receive submitted fee and cash-out limits for fee_invalid. content: application/json: schema: {"$ref": "#/components/schemas/AdminMarkPaidValidationResponse"} '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': description: the payout changed, its reference is already used, or its player has open risk signals and no approval reason was given content: application/json: schema: "$ref": "#/components/schemas/AdminMarkPaidConflictResponse" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/payment-withdrawals/{payment_id}/mark-paid/preview": get: operationId: getAdminPaymentWithdrawalsPaymentIdMarkPaidPreview tags: [admin] summary: Read-only Postgres projection of gross, fee, tip and sent amount for manual mark-paid parameters: - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: fee_cents in: query schema: {type: integer, format: int64, minimum: 0, default: 0} responses: '200': description: Authoritative live fee/net preview; does not reserve, settle or call a vendor content: application/json: schema: {"$ref": "#/components/schemas/AdminManualPayoutPreview"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/proof-assets": post: operationId: postAdminPaymentWithdrawalsPaymentIdProofAssets tags: [admin] summary: Initiate a private withdrawal proof upload security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminInitiateWithdrawalProofUploadRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '201': description: private proof upload initiated content: application/json: schema: {"$ref": "#/components/schemas/AdminWithdrawalProofUploadResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/proof-assets/{proof_id}/finalize": post: operationId: postAdminPaymentWithdrawalsPaymentIdProofAssetsProofIdFinalize tags: [admin] summary: Finalize and verify a private withdrawal proof upload security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: proof_id in: path required: true schema: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: proof finalized content: application/json: schema: {"$ref": "#/components/schemas/AdminWithdrawalProofAssetResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/proof-assets/{proof_id}/preview": get: operationId: getAdminPaymentWithdrawalsPaymentIdProofAssetsProofIdPreview tags: [admin] summary: Create an authenticated short-lived proof preview parameters: - name: payment_id in: path required: true schema: {type: string, format: uuid} - name: proof_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: short-lived signed preview content: application/json: schema: {"$ref": "#/components/schemas/AdminWithdrawalProofPreviewResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/withdrawal-proof-objects/{proof_id}": parameters: - name: proof_id in: path required: true schema: {type: string, format: uuid} - name: token in: query required: true schema: {type: string, minLength: 1, maxLength: 8192} put: x-client-build-exemption: signed-object operationId: putWithdrawalProofObjectsProofId security: [] tags: [withdrawal-proof-objects] summary: Upload a private withdrawal proof through a single-object capability description: The request Content-Type and browser-settable integrity headers are bound by the capability token and verified before atomic publication. requestBody: required: true content: application/octet-stream: schema: {type: string, format: binary, minLength: 1, maxLength: 8388608} responses: '204': {description: proof object published} '400': {"$ref": "#/components/responses/BadRequestError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} '412': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} get: x-client-build-exemption: signed-object operationId: getWithdrawalProofObjectsProofId security: [] tags: [withdrawal-proof-objects] summary: Stream a private withdrawal proof through a short-lived capability responses: '200': description: private withdrawal proof stream headers: Cache-Control: {schema: {type: string}} Content-Disposition: {schema: {type: string}} Content-Length: {schema: {type: integer, format: int64}} Content-Type: {schema: {type: string}} Pragma: {schema: {type: string}} content: application/octet-stream: schema: {type: string, format: binary} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/approve": post: operationId: postAdminPaymentWithdrawalsPaymentIdApprove x-idempotency-required: true x-idempotency-scope: payment-withdrawal-approve tags: [admin] summary: Approve an immutable withdrawal and queue provider dispatch description: For payouts a provider sends. A hand-paid cash-out (payout_mode manual) is refused with 409; its Approve is mark-paid. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminApprovePaymentWithdrawalRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: withdrawal approved and dispatch queued content: application/json: schema: {"$ref": "#/components/schemas/AdminPaymentWithdrawalCommandResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/reject": post: operationId: postAdminPaymentWithdrawalsPaymentIdReject x-idempotency-required: true x-idempotency-scope: payment-withdrawal-reject tags: [admin] summary: Reject a withdrawal and release its reservation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminRejectPaymentWithdrawalRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: withdrawal rejected content: application/json: schema: {"$ref": "#/components/schemas/AdminPaymentWithdrawalCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-withdrawals/{payment_id}/confirm-failed": post: operationId: postAdminPaymentWithdrawalsPaymentIdConfirmFailed x-idempotency-required: true x-idempotency-scope: payment-withdrawal-confirm-failed tags: [admin] summary: Confirm a reconciled provider failure and release its reservation security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: payment_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminConfirmPaymentWithdrawalFailedRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: withdrawal failure confirmed content: application/json: schema: {"$ref": "#/components/schemas/AdminPaymentWithdrawalCommandResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/product-analytics/events": get: operationId: getAdminProductAnalyticsEvents tags: - admin summary: Admin product analytics event list parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: event_name in: query required: false schema: type: string minLength: 1 maxLength: 128 - name: occurred_from in: query required: false schema: type: string format: date-time - name: occurred_to in: query required: false schema: type: string format: date-time responses: '200': description: product analytics events content: application/json: schema: "$ref": "#/components/schemas/ProductAnalyticsEventsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/product-analytics/overview": get: operationId: getAdminProductAnalyticsOverview tags: - admin summary: Admin product analytics aggregate overview parameters: - name: occurred_from in: query required: false description: Start of the window. Defaults to the last 30 days; the overview never aggregates all history unless the caller names an earlier start. schema: type: string format: date-time - name: occurred_to in: query required: false schema: type: string format: date-time responses: '200': description: product analytics overview content: application/json: schema: "$ref": "#/components/schemas/ProductAnalyticsOverviewResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/ops-events": get: operationId: getAdminOpsEvents tags: - admin summary: Admin operations event feed description: Derives ops events from payment, provider-transfer, and immutable wallet-adjustment operational records. parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: severity in: query required: false schema: type: string enum: - info - warning - critical - name: kind in: query required: false schema: type: string enum: - provider_transfer - payment_deposit - payment_webhook - wallet_adjustment - provider_capability - system - name: resource_kind in: query required: false schema: type: string enum: - provider-transfers - reconciliation - payments - users - providers - system responses: '200': description: admin ops events content: application/json: schema: "$ref": "#/components/schemas/AdminOpsEventsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-transfers": get: operationId: getAdminProviderTransfers tags: - admin summary: Admin provider transfer list and redemption logs description: With direction=unload, returns cursor-paged redemption logs and filtered totals. Date bounds are inclusive from / exclusive to (UTC Today by default). Wallet credit and forfeit are settled journal amounts; unresolved outcomes never imply wallet credit. Other calls retain the existing transfer list. parameters: - name: transfer_id in: query description: Exact transfer lookup for the existing admin detail view. schema: {type: string, format: uuid} - name: direction in: query schema: {type: string, enum: [unload], x-enum-varnames: [AdminRedemptionsUnload]} - name: from in: query schema: {type: string, format: date-time} - name: to in: query schema: {type: string, format: date-time} - name: game in: query schema: {"$ref": "#/components/schemas/ProviderCode"} - name: player_id in: query schema: {type: string, format: uuid} - name: include_player_summary in: query description: Requires player_id; includes independent lifetime and last-30-day totals and top games for that exact player. schema: {type: boolean} - name: player in: query schema: {type: string, maxLength: 120} - name: redemption_status in: query schema: {"$ref": "#/components/schemas/RedemptionLogStatus"} - name: cursor in: query schema: {type: string, maxLength: 2048} - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: state in: query required: false schema: "$ref": "#/components/schemas/ProviderTransferState" responses: '200': description: provider transfers content: application/json: schema: "$ref": "#/components/schemas/ProviderTransfersResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/provider-transfers/{transfer_id}/confirm-not-applied": post: operationId: postAdminProviderTransfersTransferIdConfirmNotApplied x-idempotency-required: true x-idempotency-scope: admin-provider-load-resolve tags: [admin] summary: Confirm an unresolved game load was not applied description: Superadmin only. Requires independent provider-outcome evidence and explicit confirmation. Restores the original cash, withdrawable and freeplay sources atomically with operator audit and idempotency. Never calls the provider, infers failure from balance alone, or retries a load. Only unresolved normal loads with proven source reservations are eligible; unloads, health probes, terminal transfers and legacy unallocated loads are refused. The same key replays the result; changed payloads conflict. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" - name: transfer_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminResolveProviderLoadRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: load rejected and original sources restored content: application/json: schema: {"$ref": "#/components/schemas/ProviderTransferResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} '409': {"$ref": "#/components/responses/ConflictError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/financial-cases": get: operationId: getAdminFinancialCases tags: [admin] summary: List all uncertain financial cases with authoritative global count parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: Uncertain financial cases; ordinary approvals remain in Payments content: application/json: schema: type: object required: [cases, total] properties: cases: {type: array, items: {"$ref": "#/components/schemas/AdminFinancialCase"}} total: {type: integer, format: int64, minimum: 0} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/financial-cases/{kind}/{case_id}": parameters: - name: kind in: path required: true schema: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} - name: case_id in: path required: true schema: {type: string, format: uuid} get: operationId: getAdminFinancialCase tags: [admin] summary: Read financial case actions and investigation history description: >- Applied deposit actions are disabled when the verified paid principal differs from the intent or is neither a whole dollar nor an amount ending in 99 cents. Such cases remain open for investigation or escalation, without wallet credit. responses: '200': description: Financial case detail content: application/json: schema: {"$ref": "#/components/schemas/AdminFinancialCaseDetail"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/financial-cases/{kind}/{case_id}/verify-procedure": parameters: - name: kind in: path required: true schema: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} - name: case_id in: path required: true schema: {type: string, format: uuid} get: operationId: getAdminFinancialCaseVerifyProcedure tags: [admin] summary: How an operator verifies this case in the provider's own panel description: The procedure for a game load, game cash-out, deposit or withdrawal case whose outcome is unconfirmed (ADR 0019). It says what happened, which identifiers to search the provider's panel by (exactly the lookup keys that provider supports for transfers), what to compare, and the neutral outcomes this case's resolve flow accepts. It never recommends an outcome and nothing is pre-selected; every value is a code the frontend words. Each outcome says whether the viewer can submit it now, from the case's own actions; a case that accepts no definite outcome offers only cant_tell_yet. Read-only; any admin may read it. Credit-move and imported-review cases have no single-provider procedure and are 404. responses: '200': description: the verify procedure content: application/json: schema: {"$ref": "#/components/schemas/VerifyProcedure"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '404': {"$ref": "#/components/responses/NotFoundError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/financial-cases/{kind}/{case_id}/preview": parameters: - name: kind in: path required: true schema: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} - name: case_id in: path required: true schema: {type: string, format: uuid} post: operationId: postAdminFinancialCasePreview tags: [admin] summary: Superadmin previews evidence-backed financial resolution description: >- Deposit previews use the verified paid principal when available and require it to match the intent. Whole-dollar principals credit exactly; principals ending in 99 cents credit the next whole dollar with a separately ledgered one-cent house subsidy. Other settled principals cannot be credited: applied actions are disabled, previews and resolution are rejected, and the case remains open for investigation or escalation. Retained contradictory paid evidence also disables not_applied and prevents resolution as unpaid, including execution after a stale preview. Deposits with no such retained proof may still be resolved as genuinely unpaid. Provider fees are not wallet principal. security: [{csrfToken: []}] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/AdminFinancialCaseCommand"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Immutable expiring preview; no vendor or wallet writes content: application/json: schema: {"$ref": "#/components/schemas/AdminFinancialCasePreview"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/financial-cases/{kind}/{case_id}/resolve": parameters: - name: kind in: path required: true schema: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} - name: case_id in: path required: true schema: {type: string, format: uuid} post: operationId: postAdminFinancialCaseResolve tags: [admin] x-idempotency-required: true x-idempotency-scope: admin-financial-case-resolve security: [{csrfToken: []}] summary: Superadmin executes preview or records investigation note/escalation description: >- Deposit settlement revalidates the same paid-principal and wallet-credit rule as the preview. Unsupported or mismatched reported principals cannot be operator-credited. The payment-intent credit identity covers both provider receipts and any one-cent house subsidy, so replay cannot grant either twice. parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: allOf: - {"$ref": "#/components/schemas/AdminFinancialCaseCommand"} - type: object required: [preview_token] properties: preview_token: {type: string, format: uuid} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Financial case outcome or durable investigation note content: application/json: schema: {"$ref": "#/components/schemas/AdminFinancialCaseDetail"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/reconciliation/queue": get: operationId: getAdminReconciliationQueue tags: - admin summary: Admin reconciliation queue parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: reconciliation queue content: application/json: schema: "$ref": "#/components/schemas/ReconciliationQueueResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/providers/fake/outcome": post: operationId: postAdminProvidersFakeOutcome tags: - admin summary: Configure next fake provider outcome in local/dev description: Idempotency-Key is intentionally exempt because this local/dev-only control mutates ephemeral fake-provider script state and is disabled outside local environments. security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/FakeProviderOutcomeRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: fake outcome configured content: application/json: schema: "$ref": "#/components/schemas/FakeProviderOutcomeResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/referrals/status": get: operationId: getReferralsStatus tags: - referrals summary: Current user's referral code, share URL, pending selection, and final outcome responses: '200': description: referral status content: application/json: schema: "$ref": "#/components/schemas/ReferralStatusResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/referrals/selection": post: operationId: postReferralsSelection x-idempotency-required: false tags: - referrals summary: Save or replace the current user's pending referral code before first successful wallet deposit security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReferralSelectionRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: referral selection saved content: application/json: schema: "$ref": "#/components/schemas/ReferralSelectionResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/referrals/rewards": get: operationId: getReferralsRewards tags: - referrals summary: Current user's per-referral referrer rewards (claimable and claimed) responses: '200': description: referrer rewards content: application/json: schema: "$ref": "#/components/schemas/ReferralRewardsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/referrals/rewards/claim": post: operationId: postReferralsRewardClaim x-idempotency-required: false tags: - referrals summary: Claim the referrer's configured reward for one rewarded referral security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReferralRewardClaimRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: referral reward claimed content: application/json: schema: "$ref": "#/components/schemas/ReferralRewardClaimResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/referrals/bonus/claim": post: operationId: postReferralsBonusClaim x-idempotency-required: false tags: - referrals summary: Claim the invited player's one-off first-deposit referral bonus security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: referral bonus claimed content: application/json: schema: "$ref": "#/components/schemas/ReferralRewardClaimResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/summary": get: operationId: getRewardsSummary tags: - rewards summary: Current user's reward balances and catalogs responses: '200': description: reward summary content: application/json: schema: "$ref": "#/components/schemas/RewardsSummaryResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/history": get: operationId: getRewardsHistory tags: - rewards summary: Current user's reward history parameters: - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" - name: kind in: query required: false description: Restrict the history to a single reward event kind. schema: "$ref": "#/components/schemas/RewardEventKind" responses: '200': description: reward history content: application/json: schema: "$ref": "#/components/schemas/RewardsHistoryResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/login/daily": post: operationId: postRewardsLoginDaily x-idempotency-required: false tags: - rewards summary: Claim current daily login XP security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: daily login reward claimed or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/login/weekly": post: operationId: postRewardsLoginWeekly x-idempotency-required: false tags: - rewards summary: Claim current weekly login XP security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: weekly login reward claimed or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/xp-claims": post: operationId: postRewardsXpClaims x-idempotency-required: true x-idempotency-scope: reward-xp-claim tags: - rewards summary: Claim an XP reward choice and reset XP security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RewardXPClaimRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: XP reward claimed or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/marketplace/products": get: operationId: getRewardsMarketplaceProducts tags: - rewards summary: List v1 reward marketplace products responses: '200': description: marketplace products content: application/json: schema: "$ref": "#/components/schemas/RewardMarketplaceProductsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/marketplace/purchases": post: operationId: postRewardsMarketplacePurchases x-idempotency-required: true x-idempotency-scope: reward-marketplace-purchase tags: - rewards summary: Buy a reward marketplace product with diamonds security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RewardMarketplacePurchaseRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: marketplace purchase applied or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/recent-winners": get: operationId: getRecentWinners x-client-build-exemption: public-intake tags: [rewards] security: [] summary: Genuine roulette spin results in the configured rolling window description: One newest qualifying award per player, ranked by reward kind and amount. Player labels use username, display name, then email local part; only the masked label is public. parameters: - in: query name: limit schema: {type: integer, minimum: 1, maximum: 100, default: 100} responses: '200': description: Genuine wheel prizes only; game withdrawals and payment cash-outs are excluded headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/RecentWinnersResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/recent-cashout-winners": get: operationId: getRecentCashoutWinners x-client-build-exemption: public-intake tags: [rewards] security: [] summary: Global completed cash-outs and game withdrawals, with masked names description: Completed game-to-wallet returns qualify only when canonical paid profit is strictly above the configured winner floor. Completed payment cash-outs qualify when actual net amount is at least that floor and lifetime completed cash-outs including this one exceed completed deposits at its completion time. Displayed amounts are actual paid receipts. BIG WIN requires game paid profit or payment amount strictly above the configured threshold. Select only the newest qualifying receipt per player across both kinds. Prefer three payments and one game in four rows, filling unused slots with either kind; a one-row request prefers payment. Within each kind rank six-hour UTC buckets by recency, then larger amount, then completion time. Display selected rows newest first, bounded by the admin maximum and four whole rows. Player labels use username, display name, then email local part; only the masked label is public. Test, simulation and non-player accounts are excluded; no private identifiers or exact timestamps are public. parameters: - in: query name: limit schema: {type: integer, minimum: 1, maximum: 100, default: 4} responses: '200': description: Privacy-safe actual cash-out amounts with display-only relative time headers: Cache-Control: schema: {type: string} content: application/json: schema: {"$ref": "#/components/schemas/RecentCashoutWinnersResponse"} '400': {"$ref": "#/components/responses/BadRequestError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/recent-winner-settings": get: operationId: getAdminRecentWinnerSettings tags: [admin] summary: Read large-game-win threshold and audit history responses: '200': description: Current policy and audit content: application/json: schema: {"$ref": "#/components/schemas/RecentWinnerSettingsResponse"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: putAdminRecentWinnerSettings tags: [admin] summary: Super-admin audited large-game-win threshold replacement security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UpdateRecentWinnerSettingsRequest"} responses: '200': description: Updated policy and audit content: application/json: schema: {"$ref": "#/components/schemas/RecentWinnerSettingsResponse"} '400': description: Field-level winners policy validation content: application/json: schema: {"$ref": "#/components/schemas/RecentWinnerSettingsValidationError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} '403': {"$ref": "#/components/responses/ForbiddenError"} '409': {"$ref": "#/components/responses/ConflictError"} '426': {"$ref": "#/components/responses/ClientOutdatedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/rewards/roulette": get: operationId: getRewardsRoulette tags: - rewards summary: Current user's roulette state and possible outcomes responses: '200': description: roulette state content: application/json: schema: "$ref": "#/components/schemas/RewardRouletteResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/roulette/spins": post: operationId: postRewardsRouletteSpins x-idempotency-required: true x-idempotency-scope: reward-roulette-spin tags: - rewards summary: Spend one spin token on roulette security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: roulette spin applied or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/missions": get: operationId: getRewardsMissions tags: - rewards summary: Current user's mission catalog and derived progress description: Mission progress is derived on read from successful deposits; only claims persist. missions_enabled surfaces the missions kill switch so the client can hide the panel and stop offering claims. responses: '200': description: missions summary content: application/json: schema: "$ref": "#/components/schemas/RewardsMissionsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/rewards/missions/claims": post: operationId: postRewardsMissionsClaims x-idempotency-required: false tags: - rewards summary: Claim a completed mission for a reward period description: Idempotency-Key is intentionally exempt because the claim identity is fully server-side - one claim per user, mission, and period key (period_key omitted selects the current period). Duplicate submissions replay the stored result with replayed=true instead of granting again, the same guarantee a client key would provide. security: - csrfToken: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RewardMissionClaimRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: mission claimed or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardMissionClaimResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '409': description: Claim refused. error.mission_claim_reason distinguishes the daily New York reward limit, expiry, an already pending bonus, and a stale claim. error.message is safe player-facing copy. content: application/json: schema: {"$ref": "#/components/schemas/ErrorResponse"} default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/rewards/users/{user_id}/history": get: operationId: getAdminRewardsUsersUserIdHistory tags: - admin - rewards summary: Admin read one user's reward history parameters: - "$ref": "#/components/parameters/UserIdParam" - "$ref": "#/components/parameters/PageParam" - "$ref": "#/components/parameters/PerPageParam" responses: '200': description: reward history content: application/json: schema: "$ref": "#/components/schemas/RewardsHistoryResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/rewards/grants": post: operationId: postAdminRewardsGrants x-idempotency-required: true x-idempotency-scope: reward-admin-grant tags: - admin - rewards summary: Admin grant XP, diamonds, spin tokens, or non-withdrawable freeplay security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminRewardGrantRequest" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: reward grant applied or replayed content: application/json: schema: "$ref": "#/components/schemas/RewardCommandResponse" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" '409': "$ref": "#/components/responses/ConflictError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/sandbox/rewards/sessions": post: operationId: postAdminSandboxRewardsSessions tags: - admin - rewards summary: Create a reward sandbox session description: Idempotency-Key is intentionally exempt because this dev/admin-only control creates ephemeral in-memory simulation state that never touches persistent reward, wallet, or payment data, and the whole surface is disabled (404) unless the rewards sandbox config flag is on. An optional preset loads the session into a named scenario in one call. security: - csrfToken: [] requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxCreateRequest" parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: sandbox session created content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxSnapshot" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/sandbox/rewards/sessions/{session_id}": get: operationId: getAdminSandboxRewardsSessionsSessionId tags: - admin - rewards summary: Read a reward sandbox session snapshot parameters: - "$ref": "#/components/parameters/SandboxSessionIdParam" responses: '200': description: sandbox session snapshot content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxSnapshot" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" delete: operationId: deleteAdminSandboxRewardsSessionsSessionId tags: - admin - rewards summary: Delete a reward sandbox session description: Idempotency-Key is intentionally exempt because deleting ephemeral in-memory sandbox state is naturally idempotent; removing an unknown session is a no-op. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SandboxSessionIdParam" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '204': description: sandbox session deleted '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/sandbox/rewards/sessions/{session_id}/commands": post: operationId: postAdminSandboxRewardsSessionsSessionIdCommands tags: - admin - rewards summary: Inject one command into a reward sandbox session description: Idempotency-Key is intentionally exempt because sandbox steps mutate ephemeral in-memory simulation state only; the operator drives the session interactively and rejected commands are recorded in the session event log rather than failing the request. Domain rejections (not qualified, expired, insufficient balance, conflict) return 200 with the rejection recorded in the returned log entry's error field. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/SandboxSessionIdParam" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxCommand" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: sandbox step applied or rejection recorded content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxStepResult" '400': "$ref": "#/components/responses/BadRequestError" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/admin/sandbox/rewards/presets": get: operationId: getAdminSandboxRewardsPresets tags: - admin - rewards summary: List reward sandbox scenario presets responses: '200': description: sandbox presets content: application/json: schema: "$ref": "#/components/schemas/RewardSandboxPresetsResponse" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" default: "$ref": "#/components/responses/DefaultError" "/api/v1/support/payment-claims": get: operationId: listPlayerPaymentClaims tags: [support] summary: Your manual payment claims description: Signed-in active player; only their own claims. responses: '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaimList"} default: {"$ref": "#/components/responses/DefaultError"} post: operationId: createPlayerPaymentClaim x-idempotency-required: true x-idempotency-scope: manual-payment-claim-create tags: [support] summary: Report a payment for staff review description: Active player. Enabled manual methods only. Idempotent per player and key; changed inputs conflict. No money is booked. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - "$ref": "#/components/parameters/IdempotencyKeyParam" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/CreateManualPaymentClaimRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaim"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/payments/manual-input/parse": post: operationId: parseManualPaymentInput tags: [payments] summary: Parse a receiving profile link, tag or PayPal email without submitting a payment security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/ParseManualPaymentInputRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Normalised receiving identity content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentInput"} '400': {"$ref": "#/components/responses/BadRequestError"} '401': {"$ref": "#/components/responses/UnauthorizedError"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/support/payment-claims/policy": get: operationId: getPlayerPaymentClaimPolicy tags: [support] summary: Enabled manual claim methods description: Active player; manual methods enabled for this brand and server rounding setting. responses: '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaimPolicy"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-claims": get: operationId: listAdminPaymentClaims tags: [support] summary: Manual payment claims awaiting review description: Any admin. Pending claims across Inbox; all claims when conversation_id is set. Newest 100. parameters: - name: conversation_id in: query schema: {type: string, format: uuid} responses: '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/AdminManualPaymentClaimList"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-claims/{claim_id}/decision": post: operationId: decideAdminPaymentClaim x-idempotency-required: false x-idempotency-scope: manual-payment-claim-id tags: [support] summary: Approve or reject a reported payment description: Active superadmin. Idempotency scope is the immutable claim id across actors. Same terminal decision replays; different credit or decision conflicts. Approval atomically records and settles an off-app deposit. Rejection notifies the player and books nothing. security: - csrfToken: [] parameters: - "$ref": "#/components/parameters/ClientBuildHeader" - name: claim_id in: path required: true schema: {type: string, format: uuid} requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/DecideManualPaymentClaimRequest"} responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaim"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/settings/readiness/preview": post: operationId: previewAdminSettingsReadiness tags: [admin] security: [{csrfToken: []}] summary: Preview one settings group without persisting changes requestBody: required: true content: application/json: schema: {$ref: "#/components/schemas/AdminSettingsReadinessPreviewRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: Backend-owned effective state of the proposed settings content: application/json: schema: {$ref: "#/components/schemas/SettingsReadinessMap"} default: {$ref: "#/components/responses/DefaultError"} "/api/v1/admin/payment-settings/readiness": post: operationId: previewAdminPaymentSettingsReadiness tags: [payments] security: - csrfToken: [] summary: Preview effective payment settings without saving or provider calls requestBody: required: true content: application/json: schema: {$ref: "#/components/schemas/PaymentSettingsReadinessPreviewRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} "200": description: Backend-owned configuration readiness; no changes were saved content: application/json: schema: {$ref: "#/components/schemas/SettingsReadinessMap"} default: $ref: "#/components/responses/DefaultError" "/api/v1/admin/payment-claims/policy": get: operationId: getAdminPaymentClaimPolicy tags: [support] summary: Manual claim settings description: Any admin. responses: '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaimPolicy"} default: {"$ref": "#/components/responses/DefaultError"} put: operationId: updateAdminPaymentClaimPolicy x-idempotency-required: false x-idempotency-scope: manual-payment-claim-policy-version tags: [support] summary: Set manual methods and rounding description: Active superadmin. Expected version required; changes are audited. Methods start disabled and rounding defaults to exact. Methods apply to new claims; existing receipts remain reviewable. security: - csrfToken: [] requestBody: required: true content: application/json: schema: {"$ref": "#/components/schemas/UpdateManualPaymentClaimPolicyRequest"} parameters: - "$ref": "#/components/parameters/ClientBuildHeader" responses: '426': {"$ref": "#/components/responses/ClientOutdatedError"} '200': description: Success content: application/json: schema: {"$ref": "#/components/schemas/ManualPaymentClaimPolicy"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-providers": get: operationId: listAdminPaymentVendors tags: [payments] summary: Configured payment vendors and supported read-only balances description: Any admin. Panel URLs resolve through the audited payment-provider link revisions. Providers without a balance API or an effective panel link are omitted. responses: '200': description: Payment vendors content: application/json: schema: {"$ref": "#/components/schemas/AdminPaymentVendorsResponse"} default: {"$ref": "#/components/responses/DefaultError"} "/api/v1/admin/payment-providers/{provider_code}/balance": get: operationId: getAdminPaymentProviderBalance tags: [payments] summary: Read the vendor's account balance description: Any admin. Read-only vendor observation, never a wallet or settlement fact. Successes and failures are cached for 60 seconds and concurrent requests coalesce. A provider without a balance API returns not found. An unavailable observation has a safe reason and no fabricated amounts. parameters: - in: path name: provider_code required: true schema: {type: string, minLength: 1, maxLength: 64} responses: '200': description: Latest balance observation or a clear unavailable state content: application/json: schema: {"$ref": "#/components/schemas/AdminPaymentProviderBalance"} default: {"$ref": "#/components/responses/DefaultError"} /api/v1/drive/state: get: operationId: getDriveState summary: Read the Penguin drive runtime switch. security: [{browserSession: []}] responses: '200': description: Current switch. Environment and network admission still apply. content: application/json: schema: {$ref: '#/components/schemas/DriveState'} default: {$ref: '#/components/responses/DefaultError'} put: operationId: putDriveState summary: Super-admin runtime kill switch. Available while runtime drive is off. security: [{browserSession: [], csrfToken: []}] parameters: - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/DriveState'} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': description: Saved switch. content: application/json: schema: {$ref: '#/components/schemas/DriveState'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/tokens: post: operationId: postDriveToken summary: Issue a scoped token bound to the current super-admin session. security: [{browserSession: [], csrfToken: []}] parameters: - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [ttl_seconds, scope] properties: ttl_seconds: {type: integer, minimum: 1, maximum: 3600} scope: {$ref: '#/components/schemas/DriveScope'} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '201': description: Token is shown once. Never log or record this response. content: application/json: schema: {$ref: '#/components/schemas/DriveToken'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/tokens/{token_id}: delete: operationId: deleteDriveToken summary: Revoke an owned token immediately, including while runtime drive is off. security: [{browserSession: [], csrfToken: []}] parameters: - {$ref: '#/components/parameters/ClientBuildHeader'} - name: token_id in: path required: true schema: {type: string, format: uuid} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '204': {description: Revoked or absent.} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/players/{user_id}/snapshot: get: operationId: getDrivePlayerSnapshot summary: Bounded redacted business state, with no provider IO or feature writes. security: [{browserSession: [], driveToken: []}] parameters: - name: user_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: At most the latest 100 rows per collection, in one database snapshot. content: application/json: schema: {$ref: '#/components/schemas/DrivePlayerSnapshot'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/accounts/{user_id}: put: operationId: putDriveAccount summary: Enroll a dedicated active tester, set caps, or disable an existing enrollment. description: Initial enrollment refuses accounts with provider, payment or ledger history. Normal tester status alone is insufficient. Disabling preserves budgets and history. security: [{browserSession: [], csrfToken: []}] parameters: - name: user_id in: path required: true schema: {type: string, format: uuid} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/DriveAccountPolicy'} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '204': {description: Audited enrollment settings saved.} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions: post: operationId: postDriveSession summary: Mint a restricted drive session for an enrolled synthetic player, never a browser cookie. security: [{browserSession: [], csrfToken: [], driveToken: []}] parameters: - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [user_id, reason] properties: user_id: {type: string, format: uuid} reason: {type: string, minLength: 3, maxLength: 500} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '201': description: A session bound to this actor, browser session, act token and player, valid for at most 15 minutes. content: application/json: schema: {$ref: '#/components/schemas/DriveSession'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions/{session_id}/games/{game_id}/add: post: operationId: postDriveGameAdd summary: Run the ordinary product games operation for the restricted synthetic subject. security: [{browserSession: [], csrfToken: [], driveToken: []}] parameters: - name: session_id in: path required: true schema: {type: string, format: uuid} - {$ref: '#/components/parameters/ClientBuildHeader'} - {$ref: '#/components/parameters/GameIdParam'} - {$ref: '#/components/parameters/IdempotencyKeyParam'} x-idempotency-required: true x-idempotency-scope: drive-session-command x-playgo-command: idempotency: required: true scope: drive-session-command responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': description: Ordinary product result. Money commands retain the original saga and budget on unknown outcomes. content: application/json: schema: {$ref: '#/components/schemas/AddGameResponse'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions/{session_id}/load-preflight: post: operationId: postDriveLoadPreflight summary: Run the ordinary product load-preflight operation for the restricted synthetic subject. security: [{browserSession: [], csrfToken: [], driveToken: []}] parameters: - name: session_id in: path required: true schema: {type: string, format: uuid} - {$ref: '#/components/parameters/ClientBuildHeader'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/LoadPreflightRequest'} responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '200': description: Ordinary product result. Money commands retain the original saga and budget on unknown outcomes. content: application/json: schema: {$ref: '#/components/schemas/LoadPreflight'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions/{session_id}/load: post: operationId: postDriveLoad summary: Run the ordinary product load operation for the restricted synthetic subject. security: [{browserSession: [], csrfToken: [], driveToken: []}] parameters: - name: session_id in: path required: true schema: {type: string, format: uuid} - {$ref: '#/components/parameters/ClientBuildHeader'} - {$ref: '#/components/parameters/IdempotencyKeyParam'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateProviderTransferRequest'} x-idempotency-required: true x-idempotency-scope: drive-session-command x-playgo-command: idempotency: required: true scope: drive-session-command responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '201': description: Ordinary product result. Money commands retain the original saga and budget on unknown outcomes. content: application/json: schema: {$ref: '#/components/schemas/ProviderTransferResponse'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions/{session_id}/unload: post: operationId: postDriveUnload summary: Run the ordinary product unload operation for the restricted synthetic subject. security: [{browserSession: [], csrfToken: [], driveToken: []}] parameters: - name: session_id in: path required: true schema: {type: string, format: uuid} - {$ref: '#/components/parameters/ClientBuildHeader'} - {$ref: '#/components/parameters/IdempotencyKeyParam'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateProviderTransferRequest'} x-idempotency-required: true x-idempotency-scope: drive-session-command x-playgo-command: idempotency: required: true scope: drive-session-command responses: '426': {$ref: '#/components/responses/ClientOutdatedError'} '201': description: Ordinary product result. Money commands retain the original saga and budget on unknown outcomes. content: application/json: schema: {$ref: '#/components/schemas/ProviderTransferResponse'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/sessions/{session_id}/recordings: get: operationId: getDriveRecordings summary: Read sanitized session exchanges and business snapshots, including incomplete steps. security: [{browserSession: [], driveToken: []}] parameters: - name: session_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: At most 32 steps retained for seven days. No credentials or raw error text. content: application/json: schema: {$ref: '#/components/schemas/DriveRecordingIndex'} default: {$ref: '#/components/responses/DefaultError'} /api/v1/drive/recordings/{recording_id}: get: operationId: getDriveRecording summary: Read one bounded sanitized step, including its business snapshots. security: [{browserSession: [], driveToken: []}] parameters: - name: recording_id in: path required: true schema: {type: string, format: uuid} responses: '200': description: One step, retained for seven days. Maximum 256 KiB stored payload. content: application/json: schema: {$ref: '#/components/schemas/DriveRecording'} default: {$ref: '#/components/responses/DefaultError'} components: # Player export accepts only these fields; arbitrary database columns never enter CSV. securitySchemes: driveToken: type: apiKey in: header name: X-PlayGo-Drive-Token description: Session-bound, scoped, expiring Penguin drive token. browserSession: type: apiKey in: cookie name: playgo_session description: Browser session, including anonymous sessions used to bootstrap login. csrfToken: type: apiKey in: header name: X-CSRF-Token description: CSRF token delivered by GET /api/v1/profile/me and required on browser mutating routes. parameters: ClientBuildHeader: name: X-Client-Build in: header required: false description: SHA-256 of the OpenAPI YAML used to generate the frontend API types. Required by the gate when CFG_HTTP_CLIENT_BUILD_FILE is configured. Missing or mismatched hashes receive 426 client_outdated before body decoding. For interactive requests, preserve the unsent draft and prompt Reload without automatically retrying. schema: type: string minLength: 1 BonusSchemeIdParam: name: scheme_id in: path required: true schema: {type: string, format: uuid} PageParam: name: page in: query required: false schema: type: integer minimum: 1 default: 1 PerPageParam: name: per_page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 AdminReportingFromParam: name: from in: query required: false description: Inclusive RFC3339 instant. When omitted, the server derives the start of the default local-calendar window ending at to. schema: type: string format: date-time AdminReportingToParam: name: to in: query required: false description: Exclusive RFC3339 instant. Defaults to request-time generated_at. schema: type: string format: date-time AdminReportingGranularityParam: name: granularity in: query required: false schema: "$ref": "#/components/schemas/AdminReportingGranularity" default: day AdminReportingIncludeInternalParam: name: include_internal in: query required: false description: Deprecated compatibility parameter. Normal reporting always excludes tester and provider-health system accounts. deprecated: true schema: type: boolean default: false GrowthFromParam: name: from in: query required: false description: Inclusive RFC3339 instant. Defaults to the start of the previous 30 local calendar days. schema: type: string format: date-time GrowthToParam: name: to in: query required: false description: Exclusive RFC3339 instant. Defaults to request-time generated_at. schema: type: string format: date-time GrowthAsOfParam: name: as_of in: query required: false description: Retention observation cutoff. Defaults to request-time generated_at. schema: type: string format: date-time GrowthTimezoneParam: name: timezone in: query required: false description: IANA timezone used for cohort and maturity calendar dates. schema: type: string minLength: 1 maxLength: 64 default: America/New_York GameIdParam: name: game_id in: path required: true schema: type: string minLength: 1 TransferIdParam: name: transfer_id in: path required: true schema: type: string format: uuid AliasIdParam: name: alias_id in: path required: true schema: type: string format: uuid ProviderAccountIdParam: name: provider_account_id in: path required: true schema: type: string format: uuid ReviewIdParam: name: review_id in: path required: true schema: type: string format: uuid UserIdParam: name: user_id in: path required: true schema: type: string format: uuid SandboxSessionIdParam: name: session_id in: path required: true schema: type: string format: uuid SupportConversationIdParam: name: conversation_id in: path required: true schema: type: string format: uuid ExternalNotificationRecipientIdParam: name: recipient_id in: path required: true schema: type: string format: uuid ProviderPanelLinkKindParam: name: kind in: path required: true schema: "$ref": "#/components/schemas/ProviderPanelLinkKind" ProviderPanelLinkCodeParam: name: provider_code in: path required: true schema: type: string minLength: 1 maxLength: 64 ProviderCodeParam: name: provider_code in: path required: true schema: "$ref": "#/components/schemas/ProviderCode" CapabilityParam: name: capability in: path required: true schema: "$ref": "#/components/schemas/ProviderCapability" IdempotencyKeyParam: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 responses: ClientOutdatedError: description: Client build is missing or outdated. For interactive requests, preserve the unsent draft and prompt Reload. Never automatically retry the rejected mutation. headers: Cache-Control: schema: {type: string, enum: [no-store]} content: application/json: schema: "$ref": "#/components/schemas/ClientOutdatedErrorResponse" SupportMessageProcessingError: description: Message is still processing. Retry the identical body and Idempotency-Key; do not start a new send. content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" DefaultError: description: error response content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" BadRequestError: description: invalid request content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" UnauthorizedError: description: unauthorized content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" ForbiddenError: description: forbidden content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" ProviderAccountImportBadRequestError: description: invalid provider account link, unlink or review command content: application/json: schema: "$ref": "#/components/schemas/ProviderAccountImportErrorResponse" ProviderAccountImportConflictError: description: provider account link, unlink or review command conflicts with current state content: application/json: schema: "$ref": "#/components/schemas/ProviderAccountImportErrorResponse" ProviderAccountImportUnavailableError: description: a required provider read was unavailable; nothing was changed and the command may be retried content: application/json: schema: "$ref": "#/components/schemas/ProviderAccountImportErrorResponse" ConflictError: description: conflict content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" NotFoundError: description: not found content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" RateLimitedError: description: rate limited content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" schemas: DriveRecordedOperation: type: string enum: [game_add, load_preflight, load, unload] x-enum-varnames: [DriveRecordingGameAdd, DriveRecordingLoadPreflight, DriveRecordingLoad, DriveRecordingUnload] x-go-type: drive.Operation x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/drive} DriveRecordingSummary: type: object additionalProperties: false required: [id, request_id, operation, started_at, http_status, complete] properties: id: {type: string, format: uuid} request_id: {type: string, format: uuid} operation: {$ref: '#/components/schemas/DriveRecordedOperation'} started_at: {type: string, format: date-time} http_status: {type: integer, minimum: 0, maximum: 599} complete: {type: boolean} DriveRecordingIndex: type: object additionalProperties: false required: [version, session_id, recordings] properties: version: {type: integer, enum: [1]} session_id: {type: string, format: uuid} recordings: type: array maxItems: 32 items: {$ref: '#/components/schemas/DriveRecordingSummary'} x-go-type: drive.RecordingIndex x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/drive} DriveRecordedAPI: type: object description: Selected IDs, integer amounts, booleans and closed business enums. Tokens, free text, native identities and URLs are omitted. additionalProperties: true x-go-type: drive.RecordedAPI x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/drive} DriveRecording: type: object additionalProperties: false required: [id, request_id, session_id, operation, started_at, finished_at, http_status, complete, request, response, before, after, exchanges] properties: id: {type: string, format: uuid} request_id: {type: string, format: uuid} session_id: {type: string, format: uuid} operation: {$ref: '#/components/schemas/DriveRecordedOperation'} started_at: {type: string, format: date-time} finished_at: {type: string, format: date-time, nullable: true} http_status: {type: integer, minimum: 0, maximum: 599} complete: {type: boolean} request: {$ref: '#/components/schemas/DriveRecordedAPI'} response: {$ref: '#/components/schemas/DriveRecordedAPI'} before: {$ref: '#/components/schemas/DrivePlayerSnapshot'} after: nullable: true allOf: [{$ref: '#/components/schemas/DrivePlayerSnapshot'}] exchanges: type: array maxItems: 33 items: type: object additionalProperties: false required: [method, url, request_headers, request_body, http_status, response_headers, response_body, incomplete] properties: method: {type: string} url: {type: string} request_headers: {type: string} request_body: {type: string} http_status: {type: integer, nullable: true} response_headers: {type: string} response_body: {type: string} incomplete: {type: boolean} x-go-type: drive.Recording x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/drive} DriveSessionRecording: type: object additionalProperties: false required: [version, session_id, recordings] properties: version: {type: integer, enum: [1]} session_id: {type: string, format: uuid} recordings: type: array maxItems: 32 items: {$ref: '#/components/schemas/DriveRecording'} x-go-type: drive.SessionRecording x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/drive} DriveScope: type: string enum: [read, act] x-enum-varnames: [DriveScopeRead, DriveScopeAct] DriveAccountPolicy: type: object additionalProperties: false required: [enabled, confirm_synthetic, per_call_cap_cents, daily_cap_cents, reason] properties: enabled: {type: boolean} confirm_synthetic: {type: boolean, enum: [true]} per_call_cap_cents: {type: integer, format: int64, minimum: 1} daily_cap_cents: {type: integer, format: int64, minimum: 1} reason: {type: string, minLength: 3, maxLength: 500} DriveSession: type: object additionalProperties: false required: [id, user_id, expires_at] properties: id: {type: string, format: uuid} user_id: {type: string, format: uuid} expires_at: {type: string, format: date-time} LedgerAccountType: type: string enum: [cash, withdrawable_cash, pending_withdrawal, forfeit, deposit_bonus, deposit_subsidy, house_promo, cashout_review_holding] LedgerEntryDirection: type: string enum: [debit, credit] DriveState: type: object additionalProperties: false required: [enabled] properties: enabled: {type: boolean} DriveToken: type: object additionalProperties: false required: [id, token, expires_at] properties: id: {type: string, format: uuid} token: {type: string, writeOnly: false} expires_at: {type: string, format: date-time} DrivePlayerSnapshot: type: object additionalProperties: false required: [user_id, wallet, accounts, transfers, withdrawals, rewards, ledger] properties: user_id: {type: string, format: uuid} wallet: type: array maxItems: 100 items: type: object additionalProperties: false required: [account_type, balance_cents] properties: account_type: {$ref: '#/components/schemas/LedgerAccountType'} balance_cents: {type: integer, format: int64} accounts: type: array maxItems: 100 items: type: object additionalProperties: false required: [id, provider_code, status, balance_credits, balance_observed_at] properties: id: {type: string, format: uuid} provider_code: {$ref: '#/components/schemas/ProviderCode'} status: {$ref: '#/components/schemas/AdminProviderAccountStatus'} balance_credits: {type: integer, format: int64, nullable: true} balance_observed_at: {type: string, format: date-time, nullable: true} transfers: type: array maxItems: 100 items: type: object additionalProperties: false required: [id, provider_account_id, provider_code, direction, state, amount_cents, credits, created_at] properties: id: {type: string, format: uuid} provider_account_id: {type: string, format: uuid} provider_code: {$ref: '#/components/schemas/ProviderCode'} direction: {$ref: '#/components/schemas/TransferDirection'} state: {$ref: '#/components/schemas/ProviderTransferState'} amount_cents: {type: integer, format: int64} credits: {type: integer, format: int64} created_at: {type: string, format: date-time} withdrawals: type: array maxItems: 100 items: type: object additionalProperties: false required: [id, state, amount_cents, created_at] properties: id: {type: string, format: uuid} state: {$ref: '#/components/schemas/PaymentWithdrawalState'} amount_cents: {type: integer, format: int64} created_at: {type: string, format: date-time} rewards: type: array maxItems: 100 items: type: object additionalProperties: false required: [id, event_kind, delta_freeplay_cents, delta_deposit_bonus_cents, created_at] properties: id: {type: string, format: uuid} event_kind: {$ref: '#/components/schemas/RewardEventKind'} delta_freeplay_cents: {type: integer, format: int64} delta_deposit_bonus_cents: {type: integer, format: int64} created_at: {type: string, format: date-time} ledger: type: array maxItems: 100 items: type: object additionalProperties: false required: [id, transaction_id, account_type, direction, amount_cents, created_at] properties: id: {type: string, format: uuid} transaction_id: {type: string, format: uuid} account_type: {$ref: '#/components/schemas/LedgerAccountType'} direction: {$ref: '#/components/schemas/LedgerEntryDirection'} amount_cents: {type: integer, format: int64} created_at: {type: string, format: date-time} IntegrationDomain: type: string enum: [game, payment] IntegrationFieldSource: type: string enum: [inherited, brand_override, brand_secret] IntegrationField: type: object additionalProperties: false required: [name, label, help, secret, required] properties: name: {type: string} label: {type: string} help: {type: string} type: {type: string, enum: [string, boolean]} secret: {type: boolean} required: {type: boolean} default_value: {type: string} catalog_version: {type: string} source: {$ref: '#/components/schemas/IntegrationFieldSource'} IntegrationKind: type: object additionalProperties: false required: [provider_code, family, name, fields, base_url] properties: provider_code: {$ref: '#/components/schemas/ProviderCode'} family: {type: string, description: Adapter configuration kind identifier from the served descriptors; not a game capability family.} name: {type: string} fields: {type: array, items: {$ref: '#/components/schemas/IntegrationField'}} base_url: {type: string} read_only_values: {type: object, additionalProperties: {type: string}, readOnly: true} catalog_version: {type: string} IntegrationKinds: type: object required: [kinds] properties: {kinds: {type: array, items: {$ref: '#/components/schemas/IntegrationKind'}}} IntegrationFieldState: type: object additionalProperties: false required: [name, set, changed_at, changed_by] properties: name: {type: string} set: {type: boolean} changed_at: {type: string, format: date-time} changed_by: {type: string} value: {type: string} catalog_version: {type: string} hint: {type: string, readOnly: true, description: 'First four and last four characters of eligible saved keys. Never passwords, TOTP or short secrets.'} secret_length: {type: integer, readOnly: true, minimum: 20} source: {$ref: '#/components/schemas/IntegrationFieldSource'} IntegrationTestOutcome: type: string enum: [testing, success, auth_failed, network_failed, unsupported, not_tested] IntegrationFieldErrors: type: object additionalProperties: false required: [error, fields] properties: error: {$ref: '#/components/schemas/APIError'} fields: {type: object, additionalProperties: {type: string}} IntegrationConnectionSummaries: type: object additionalProperties: false required: [connections, capabilities] properties: capabilities: {$ref: '#/components/schemas/IntegrationCapabilities'} connections: {type: array, items: {$ref: '#/components/schemas/IntegrationConnectionSummary'}} IntegrationCapabilities: type: object additionalProperties: false required: [games_connect, payments_connect, custom_game_providers] properties: games_connect: {type: boolean} payments_connect: {type: boolean} custom_game_providers: {type: boolean} IntegrationCredentialPresence: type: object additionalProperties: false required: [name, label, required, saved, masked_identifier] properties: name: {type: string} label: {type: string} required: {type: boolean} saved: {type: boolean} hint: {type: string, readOnly: true} secret_length: {type: integer, readOnly: true, minimum: 20} masked_identifier: {type: string, nullable: true, description: 'First two and last two Unicode characters separated by ***. Identifiers of four characters or less are fully masked. Always null for passwords and keys.'} IntegrationConnectionSummary: type: object additionalProperties: false required: [provider_code, family, name, configured, can_configure, blocked_reason, source, endpoint, credentials, revision, phase, test_outcome, tested_at, api_access_mode, api_access_version, api_access_phase] properties: provider_code: {$ref: '#/components/schemas/ProviderCode'} family: {$ref: '#/components/schemas/ProviderFamily'} name: {type: string} configured: {type: boolean, description: Required credential fields are present; does not claim a successful provider check.} can_configure: {type: boolean} blocked_reason: {type: string} source: {type: string, enum: [none, file, database]} endpoint: {type: string, nullable: true, description: Public endpoint without userinfo or URL parameters; null if it cannot be safely displayed.} credentials: {type: array, items: {$ref: '#/components/schemas/IntegrationCredentialPresence'}} revision: {type: integer, format: int64, minimum: 0} phase: {type: string, enum: [file, activating, active, activation_failed, disabled]} test_outcome: {allOf: [{$ref: '#/components/schemas/IntegrationTestOutcome'}], nullable: true} tested_at: {type: string, format: date-time, nullable: true} api_access_mode: {type: string, enum: [on, off]} api_access_version: {type: integer, format: int64, minimum: 0} api_access_phase: {type: string, enum: [on, turning_off, off]} GameCategory: type: string enum: [casino] GameProviderOrigin: type: string enum: [seed, custom] GameProviderState: type: string enum: [draft, verifying, live, suspended, retired] GameCatalogVisibility: type: string enum: [hidden, allowlist_only, public] GameProviderRegistryAvailability: type: string enum: [all, non_production] GameProviderCreateRequest: type: object additionalProperties: false required: [code, display_name, api_base_url, reason] properties: code: {$ref: '#/components/schemas/ProviderCode'} display_name: {type: string, minLength: 2, maxLength: 60} api_base_url: {type: string, maxLength: 512, description: HTTPS DNS name on a public address and an allowlisted port; adapters append their paths.} panel_url: {type: string, maxLength: 512, description: HTTPS operator back office; displayed only, never fetched.} username_part: {type: string, pattern: '^[a-z0-9]{2}$', description: Derived from the code when omitted.} catalog_name: {type: string, minLength: 2, maxLength: 60} logo_url: {type: string, maxLength: 512} reason: {type: string, minLength: 3, maxLength: 500} GameProviderChangeRequest: type: object additionalProperties: false required: [expected_version, reason] properties: expected_version: {type: integer, format: int64, minimum: 1} family: {$ref: '#/components/schemas/ProviderFamily'} display_name: {type: string, minLength: 2, maxLength: 60} api_base_url: {type: string, maxLength: 512} panel_url: {type: string, maxLength: 512} cash_cents_per_provider_credit: {type: integer, format: int64, minimum: 1, description: Optional; must equal the family's scale.} wire_scale: {type: integer, format: int64, minimum: 1, description: Optional; must equal the family's scale.} default_game_id: {type: string, maxLength: 100} catalog_name: {type: string, minLength: 2, maxLength: 60} logo_url: {type: string, maxLength: 512} catalog_visibility: {$ref: '#/components/schemas/GameCatalogVisibility'} reason: {type: string, minLength: 3, maxLength: 500} GameProviderActivationRequest: type: object additionalProperties: false required: [expected_version, verification_run_id, reason] properties: expected_version: {type: integer, format: int64, minimum: 1} verification_run_id: {type: string, format: uuid} reason: {type: string, minLength: 3, maxLength: 500} GameProviderSuspensionRequest: type: object additionalProperties: false required: [expected_version, reason] properties: expected_version: {type: integer, format: int64, minimum: 1} reason: {type: string, minLength: 3, maxLength: 500} IntegrationAgentBalanceCheck: x-go-type: integrations.AgentBalanceCheck x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/integrations} type: object additionalProperties: false description: Agent balance in provider credits around the live test's one-credit load; it must drop by exactly the credited amount. required: [before_credits, after_credits, expected_credits, matched] properties: before_credits: {type: integer, format: int64} after_credits: {type: integer, format: int64} expected_credits: {type: integer, format: int64} matched: {type: boolean} GameProviderDefinitions: type: object additionalProperties: false required: [providers, custom_families] properties: providers: {type: array, items: {$ref: '#/components/schemas/GameProviderDefinition'}} custom_families: {type: array, items: {$ref: '#/components/schemas/CustomGameProviderFamily'}} CustomGameProviderFamilyCode: type: string enum: [agentserver, fastapi, wsterminal, gamevault, juwa, yolo, bluedragon, riverpay, cashier] CustomGameProviderFamily: type: object additionalProperties: false required: [family, cash_cents_per_provider_credit, wire_scale] properties: family: {$ref: '#/components/schemas/CustomGameProviderFamilyCode'} cash_cents_per_provider_credit: {type: integer, format: int64, minimum: 1} wire_scale: {type: integer, format: int64, minimum: 1} GameProviderActivationRefusal: type: string enum: [configuration_disabled, seed_provider, provider_not_verifying, no_live_test, wrong_live_test, test_not_finished, test_expired, definition_changed, credentials_changed, steps_not_passed, agent_balance_unproven, agent_balance_mismatch] GameProviderQualifyingLiveTest: type: object additionalProperties: false required: [run_id, finished_at, definition_revision, credential_revision] properties: run_id: {type: string, format: uuid} finished_at: {type: string, format: date-time} definition_revision: {type: integer, format: int64, minimum: 1} credential_revision: {type: integer, format: int64, minimum: 0} GameProviderDefinition: type: object additionalProperties: false description: A game provider row joined to its current definition revision (ADR 0062). required: [code, origin, state, username_part, version, current_revision, family, display_name, api_base_url, panel_url, cash_cents_per_provider_credit, wire_scale, agent_login_balance_multiplier, default_game_id, catalog_game_id, catalog_name, category, logo_url, added_by_default, catalog_visibility, test_only, registry_availability, verification_run_id, revised_by, revision_reason, revised_at, activation_eligible, activation_refusal, qualifying_live_test] properties: code: {$ref: '#/components/schemas/ProviderCode'} origin: {$ref: '#/components/schemas/GameProviderOrigin'} state: {$ref: '#/components/schemas/GameProviderState'} username_part: {type: string, pattern: '^[a-z0-9]{2}$'} version: {type: integer, format: int64, minimum: 1} current_revision: {type: integer, format: int64, minimum: 1} family: {allOf: [{$ref: '#/components/schemas/ProviderFamily'}], nullable: true, description: Null only while draft.} display_name: {type: string} api_base_url: {type: string, nullable: true, description: Null when the endpoint is brand-local or unset; the provider is then unavailable from definitions.} panel_url: {type: string, nullable: true, description: Operator back office; displayed only, never fetched.} cash_cents_per_provider_credit: {type: integer, format: int64, minimum: 1, nullable: true} wire_scale: {type: integer, format: int64, minimum: 1, nullable: true} agent_login_balance_multiplier: {type: integer, format: int64, minimum: 1} default_game_id: {type: string, nullable: true} catalog_game_id: {type: string, nullable: true, description: Null when the provider has no catalog entry.} catalog_name: {type: string, nullable: true} category: {allOf: [{$ref: '#/components/schemas/GameCategory'}], nullable: true} logo_url: {type: string, nullable: true} added_by_default: {type: boolean} catalog_visibility: {$ref: '#/components/schemas/GameCatalogVisibility'} test_only: {type: boolean} registry_availability: {$ref: '#/components/schemas/GameProviderRegistryAvailability'} verification_run_id: {type: string, format: uuid, nullable: true, description: Passing live test behind a custom activation; null for seeds, whose revision reason is their verification record.} activation_eligible: {type: boolean} activation_refusal: {allOf: [{$ref: '#/components/schemas/GameProviderActivationRefusal'}], nullable: true} qualifying_live_test: {allOf: [{$ref: '#/components/schemas/GameProviderQualifyingLiveTest'}], nullable: true} revised_by: {type: string, description: Actor reference of the current revision, such as system:migration:281.} revision_reason: {type: string} revised_at: {type: string, format: date-time} IntegrationSnapshot: type: object additionalProperties: false required: [provider_code, revision, source, fields, phase, test_outcome, changed_at, changed_by, can_save, blocked_reason] properties: provider_code: {$ref: '#/components/schemas/ProviderCode'} revision: {type: integer, format: int64, minimum: 0} source: {type: string, enum: [file, database]} fields: {type: array, items: {$ref: '#/components/schemas/IntegrationFieldState'}} phase: {type: string, enum: [file, activating, active, activation_failed, disabled]} test_outcome: {allOf: [{$ref: '#/components/schemas/IntegrationTestOutcome'}], nullable: true} changed_at: {type: string, format: date-time, nullable: true} changed_by: {type: string} can_save: {type: boolean} blocked_reason: {type: string} active_revision: {type: integer, format: int64, minimum: 1, nullable: true, description: Payment revision used for new work; absent when inactive} latest_saved_test: {$ref: '#/components/schemas/IntegrationSavedTest'} IntegrationSavedTest: type: object additionalProperties: false description: Latest finished saved-revision payment connection test for the current saved revision; absent when none required: [run_id, revision, passed, eligible_for_activation, completed_at] properties: run_id: {type: string, format: uuid} revision: {type: integer, format: int64, minimum: 1} passed: {type: boolean} eligible_for_activation: {type: boolean, description: True only while the passing test is less than 24 hours old} completed_at: {type: string, format: date-time} IntegrationActivationRequest: type: object additionalProperties: false required: [expected_revision, reason] properties: expected_revision: {type: integer, format: int64, minimum: 1} reason: {type: string, minLength: 3, maxLength: 500} IntegrationSnapshots: type: object required: [integrations] properties: {integrations: {type: array, items: {$ref: '#/components/schemas/IntegrationSnapshot'}}} IntegrationDiagnosticReplay: type: object additionalProperties: false required: [error] properties: error: {$ref: '#/components/schemas/APIError'} original_run_id: {type: string, format: uuid} IntegrationDiagnosticStepID: type: string enum: [read_login, agent_balance, store_info, game_list, player_lookup, create, initial_balance, load, loaded_balance, unload, final_balance, reset, credential_verify, link_verify, cleanup, payment_status, payment_credentials, payment_balance, payment_callbacks, payment_checkout] x-go-type: providers.DiagnosticStepID x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/providers} IntegrationDiagnosticStatus: type: string enum: [PENDING, RUNNING, PASS, FAIL, UNKNOWN, SKIPPED, NOT OFFERED] x-go-type: integrations.DiagnosticStatus x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/integrations} IntegrationLiveTestRequest: type: object additionalProperties: false required: [tester_id, game_id, expected_revision] properties: tester_id: {type: string, format: uuid, description: Existing active tester; never a simulation player} game_id: {type: string, minLength: 1, maxLength: 200} expected_revision: {type: integer, format: int64, minimum: 1} IntegrationDiagnosticDraft: type: object additionalProperties: false required: [expected_revision, fields, catalog_version, plan_version, reason] properties: expected_revision: {type: integer, format: int64, minimum: 0} fields: {type: object, writeOnly: true, maxProperties: 16, additionalProperties: {type: string, maxLength: 2000, writeOnly: true}} clear_fields: {type: array, maxItems: 16, items: {type: string}} catalog_version: {type: string} plan_version: {type: string} reason: {type: string, minLength: 3, maxLength: 500} IntegrationDiagnosticStep: type: object additionalProperties: false required: [id, label, phase, implemented, required, citation, signature_code] properties: credential_check: {type: boolean, description: Adapter-declared step in the inline credential check} id: {$ref: '#/components/schemas/IntegrationDiagnosticStepID'} label: {type: string} phase: {type: string, enum: [read, write]} implemented: {type: boolean} required: {type: boolean} citation: {type: string} signature_code: {type: string} IntegrationDiagnosticPlan: x-go-type: integrations.DiagnosticPlan x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/integrations} type: object additionalProperties: false required: [version, provider_code, credential_check, writes_enabled, credit_cap, steps] properties: version: {type: string} provider_code: {$ref: '#/components/schemas/ProviderCode'} credential_check: {type: boolean} writes_enabled: {type: boolean, description: Payment full checks may create an unpaid test checkout; game read checks remain false.} credit_cap: {type: integer, minimum: 0, maximum: 1, description: Game credit cap is one; payment checks move no money and report zero.} steps: {type: array, items: {$ref: '#/components/schemas/IntegrationDiagnosticStep'}} IntegrationDiagnosticArtifact: type: object additionalProperties: false required: [kind, url, label, order_ref, created_at] properties: kind: {type: string, enum: [test_checkout]} url: {type: string, format: uri, description: Public unpaid test link; never telemetry} label: {type: string, enum: ['Test link, do not pay']} order_ref: {type: string} created_at: {type: string, format: date-time} expires_hint: {type: string} IntegrationDiagnosticResult: type: object additionalProperties: false required: [id, label, sequence, status, reason, citation] properties: artifact: {$ref: '#/components/schemas/IntegrationDiagnosticArtifact'} vendor_status_class: {type: string, pattern: '^[1-5]xx$', description: Coarse vendor HTTP status class; no response body} id: {$ref: '#/components/schemas/IntegrationDiagnosticStepID'} label: {type: string} sequence: {type: integer} status: {$ref: '#/components/schemas/IntegrationDiagnosticStatus'} reason: {type: string} citation: {type: string} IntegrationDiagnosticRun: x-go-type: integrations.DiagnosticRun x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/integrations} type: object additionalProperties: false required: [id, provider_code, mode, status, overall, expected_revision, plan_version, created_at, expires_at, results, report_available] properties: target: {type: string, enum: [saved, draft], description: Payment test target; draft never enables activation} revision: {type: integer, format: int64, nullable: true, minimum: 1} eligible_for_activation: {type: boolean, description: Computed at completion; exact saved revision only} completed_at: {type: string, format: date-time} id: {type: string, format: uuid} provider_code: {$ref: '#/components/schemas/ProviderCode'} mode: {type: string, enum: [credentials, full]} status: {type: string, enum: [running, finished]} overall: {type: string, enum: [PASS, FAIL, UNKNOWN, RUNNING, SKIPPED]} expected_revision: {type: integer, format: int64} plan_version: {type: string} created_at: {type: string, format: date-time} expires_at: {type: string, format: date-time} results: {type: array, items: {$ref: '#/components/schemas/IntegrationDiagnosticResult'}} report_available: {type: boolean} agent_balance: {$ref: '#/components/schemas/IntegrationAgentBalanceCheck'} IntegrationTestResult: type: object additionalProperties: false required: [id, provider_code, outcome, message, expires_at, expected_revision] properties: id: {type: string, format: uuid} provider_code: {$ref: '#/components/schemas/ProviderCode'} outcome: {$ref: '#/components/schemas/IntegrationTestOutcome'} message: {type: string} expires_at: {type: string, format: date-time} expected_revision: {type: integer, format: int64, minimum: 0} GameStoreAgentDirection: {type: string, enum: [agent_to_game, game_to_agent], x-enum-varnames: [GameStoreAgentToGame, GameStoreGameToAgent]} GameStoreAgentResolutionOutcome: {type: string, enum: [succeeded, rejected], x-enum-varnames: [GameStoreResolutionSucceeded, GameStoreResolutionRejected]} GameStoreAgentState: {type: string, enum: [dispatching, succeeded, rejected, unknown, resolved_externally], x-enum-varnames: [GameStoreAgentDispatching, GameStoreAgentSucceeded, GameStoreAgentRejected, GameStoreAgentUnknown, GameStoreAgentResolvedExternally]} GameStoreAgentPreview: type: object additionalProperties: false required: [id, player_id, expected, direction, credits, agent_before, agent_after, game_before, game_after, observed_at, expires_at, available] properties: id: {type: string, format: uuid} player_id: {type: string, format: uuid} expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} direction: {"$ref": "#/components/schemas/GameStoreAgentDirection"} credits: {type: integer, format: int64, minimum: 1} agent_before: {type: integer, format: int64, minimum: 0, nullable: true} agent_after: {type: integer, format: int64, minimum: 0, nullable: true} game_before: {type: integer, format: int64, minimum: 0, nullable: true} game_after: {type: integer, format: int64, minimum: 0, nullable: true} observed_at: {type: string, format: date-time} expires_at: {type: string, format: date-time} available: {type: boolean} GameStoreAgentTransfer: type: object additionalProperties: false required: [id, player_id, preview_id, direction, credits, state, external_order_id, provider_order_id, rejection_code, created_at, resolve_action, reconcile_action, poll_after_ms, resolution_outcome, refused_before_dispatch] properties: id: {type: string, format: uuid} player_id: {type: string, format: uuid} preview_id: {type: string, format: uuid} direction: {"$ref": "#/components/schemas/GameStoreAgentDirection"} credits: {type: integer, format: int64, minimum: 1} state: {"$ref": "#/components/schemas/GameStoreAgentState"} external_order_id: {type: string} provider_order_id: {type: string, nullable: true} rejection_code: {type: string, nullable: true} created_at: {type: string, format: date-time} refused_before_dispatch: {type: boolean} resolution_outcome: {allOf: [{"$ref": "#/components/schemas/GameStoreAgentResolutionOutcome"}], nullable: true} resolve_action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} reconcile_action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} poll_after_ms: {type: integer, nullable: true, minimum: 1000, maximum: 30000} GameStorePasswordReset: type: object additionalProperties: false required: [command_id, player_id, state] properties: command_id: {type: string, format: uuid} player_id: {type: string, format: uuid} state: {type: string, enum: [succeeded, rejected, unknown, resolved_externally]} GameStorePasswordAccess: type: object additionalProperties: false required: [player_id, password] properties: player_id: {type: string, format: uuid} password: {type: string, description: Private ephemeral response only; never a GET or durable replay value.} GameStorePasswordSaved: type: object additionalProperties: false required: [player_id, revision] properties: player_id: {type: string, format: uuid} revision: {type: integer, format: int64, minimum: 1} GameStoreLinkPreviewRequest: type: object additionalProperties: false required: [expected, user_id, expected_slot] properties: expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} user_id: {type: string, format: uuid} expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records an action default when omitted or blank.} GameStoreLinkOptions: type: object required: [user_id, name, expected_slot, action] properties: user_id: {type: string, format: uuid} name: {type: string} expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} GameStoreLinkPreview: type: object required: [id, player_id, user_id, user_name, username, reference, credential_source, identity_confirmed_at, opening_credits, opening_observed_at, expires_at, opening_provenance] properties: id: {type: string, format: uuid} player_id: {type: string, format: uuid} user_id: {type: string, format: uuid} user_name: {type: string} username: {type: string} reference: {type: string} credential_source: {"$ref": "#/components/schemas/CredentialProvenance"} identity_confirmed_at: {type: string, format: date-time} opening_credits: {type: integer, format: int64, nullable: true} opening_observed_at: {type: string, format: date-time, nullable: true} expires_at: {type: string, format: date-time} opening_provenance: {type: string, enum: [external_store_unattributed], x-enum-varnames: [GameStoreExternalUnattributed]} GameStoreLinkResult: type: object required: [player_id, user_id, account_id, effects] properties: player_id: {type: string, format: uuid} user_id: {type: string, format: uuid} account_id: {type: string, format: uuid} effects: {type: array, items: {"$ref": "#/components/schemas/ResourceEffect"}} GameStorePlayerHistory: type: object additionalProperties: false required: [events, next_cursor, provider_history] properties: events: {type: array, maxItems: 50, items: {"$ref": "#/components/schemas/GameStorePlayerHistoryEvent"}} next_cursor: {type: string, nullable: true} provider_history: {type: string, enum: [unavailable], x-enum-varnames: [GameStoreProviderHistoryUnavailable]} GameStorePlayerHistoryEvent: type: object additionalProperties: false required: [id, command_id, operation, outcome, created_at] properties: id: {type: string, format: uuid} command_id: {type: string, format: uuid} operation: {"$ref": "#/components/schemas/GameStoreHistoryOperation"} outcome: {"$ref": "#/components/schemas/AccountManagementOutcome"} created_at: {type: string, format: date-time} GameStoreHistoryOperation: type: string enum: [record_panel_password, password_access, reset_password, agent_load, agent_redeem, resolve_transfer, link_player, create_player] x-enum-varnames: [GameStoreHistoryPanelPassword, GameStoreHistoryPasswordAccess, GameStoreHistoryPasswordReset, GameStoreHistoryAgentLoad, GameStoreHistoryAgentRedeem, GameStoreHistoryResolveTransfer, GameStoreHistoryLinkPlayer, GameStoreHistoryCreatePlayer] GameStorePlayerExpected: type: object additionalProperties: false required: [store_revision, integration_fingerprint, player_revision, credential_id] properties: store_revision: {type: integer, format: int64, minimum: 1} integration_fingerprint: {type: string, minLength: 1, maxLength: 128} player_revision: {type: integer, format: int64, minimum: 1} credential_id: {type: string, format: uuid, nullable: true} GameStorePlayerCreateRequest: type: object additionalProperties: false required: [expected, username, password] properties: expected: {$ref: '#/components/schemas/GameStoreExpected'} username: {type: string, minLength: 1, maxLength: 128} password: {type: string, minLength: 1, maxLength: 255, writeOnly: true} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; the server records the action default when omitted or blank.} GameStoreCreateResolutionRequest: type: object additionalProperties: false required: [expected, account_exists, confirmed_panel_outcome, panel_reference] properties: expected: {$ref: '#/components/schemas/GameStoreExpected'} account_exists: {type: boolean, description: Staff confirmed that the account exists in the provider panel; use Find to link it separately.} confirmed_panel_outcome: {type: boolean, description: Staff confirmed the original request has finished in the provider panel.} panel_reference: {type: string, minLength: 3, maxLength: 255, description: Nonsecret evidence of the original request outcome.} reason: {type: string, maxLength: 2000, description: Optional nonsecret audit reason; blank uses the server action default.} GameStoreAccountCommand: type: object additionalProperties: false required: [command_id, store_id, username, player_id, state, next_step] properties: username: {type: string} command_id: {type: string, format: uuid} store_id: {type: string, format: uuid} player_id: {type: string, format: uuid, nullable: true} state: {$ref: "#/components/schemas/GameStoreCreateState"} next_step: {type: string} lookup_identifier: {type: string, description: Original username to prefill the existing Find lookup after an account-exists resolution.} GameStoreAccountCommands: type: object additionalProperties: false required: [commands, next_cursor] properties: commands: {type: array, maxItems: 50, items: {$ref: '#/components/schemas/GameStoreAccountCommand'}} next_cursor: {type: string, format: uuid, nullable: true} GameStoreCreateState: type: string enum: [dispatching, succeeded, rejected, unknown, resolved_externally] x-go-type: providerstore.AccountCommandState x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/providerstore} GameStorePlayerManagement: type: object additionalProperties: false required: [player_id, store_id, provider_code, game_name, username, reference, native_id, expected, password_saved, credential_source, verified_at, balance_credits, observed_at, linked_player, panel_url, lookup_available, record_panel_password_available, password_access_available, password_reset_available, reset_requires_current_password, unknown_reset_command_id, agent_load_action, agent_redeem_action, pending_agent_transfer_id, link_action, balance_refresh_available] properties: player_id: {type: string, format: uuid} store_id: {type: string, format: uuid} provider_code: {"$ref": "#/components/schemas/ProviderCode"} game_name: {type: string} username: {type: string} reference: {type: string} native_id: {type: string, nullable: true} expected: {"$ref": "#/components/schemas/GameStorePlayerExpected"} password_saved: {type: boolean} credential_source: {allOf: [{"$ref": "#/components/schemas/CredentialProvenance"}], nullable: true} verified_at: {type: string, format: date-time, nullable: true} balance_credits: {type: integer, format: int64, minimum: 0, nullable: true} observed_at: {type: string, format: date-time, nullable: true} linked_player: {allOf: [{"$ref": "#/components/schemas/GameStoreLinkedPlayer"}], nullable: true} panel_url: {type: string, nullable: true} lookup_available: {type: boolean} balance_refresh_available: {type: boolean, description: Explicit bound native lookup is available to refresh this unlinked player's game balance.} record_panel_password_available: {type: boolean} password_access_available: {type: boolean} link_action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} agent_load_action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} agent_redeem_action: {"$ref": "#/components/schemas/AccountManagementInteractionAction"} pending_agent_transfer_id: {type: string, format: uuid, nullable: true} password_reset_available: {type: boolean} reset_requires_current_password: {type: boolean} unknown_reset_command_id: {type: string, format: uuid, nullable: true} GameStoreLookup: type: object additionalProperties: false required: [command_id, store_id, state, player_id, reason, management_reason] properties: command_id: {type: string, format: uuid} store_id: {type: string, format: uuid} state: {type: string, enum: [found, rejected, unknown]} player_id: {type: string, format: uuid, nullable: true} reason: {allOf: [{"$ref": "#/components/schemas/GameStoreManagementReason"}], nullable: true} management_reason: {allOf: [{"$ref": "#/components/schemas/ProviderAccountManagementReason"}], nullable: true} GameStoreLinkedAccount: type: object required: [account_id, user_id, name, username, reference, provider_player_id, balance_credits, observed_at, password_saved] properties: account_id: {type: string, format: uuid} user_id: {type: string, format: uuid} name: {type: string} username: {type: string} reference: {type: string} provider_player_id: {type: string, nullable: true} balance_credits: {type: integer, format: int64, nullable: true} observed_at: {type: string, format: date-time, nullable: true} password_saved: {type: boolean} GameStoreLinkedAccounts: type: object required: [players, next_cursor] properties: players: {type: array, items: {"$ref": "#/components/schemas/GameStoreLinkedAccount"}} next_cursor: {type: string, nullable: true} GameStoreExpected: type: object additionalProperties: false required: [revision, integration_fingerprint] properties: revision: {type: integer, format: int64, minimum: 1} integration_fingerprint: {type: string, minLength: 1, maxLength: 128} GameStore: type: object required: [id, provider_code, name, expected, create_available, roster_available, refresh_available, lookup_available, identifier_label, password_required, api_mode, panel_url, agent_balance_credits, agent_observed_at] properties: id: {type: string, format: uuid} provider_code: {"$ref": "#/components/schemas/ProviderCode"} name: {type: string} expected: {"$ref": "#/components/schemas/GameStoreExpected"} create_available: {type: boolean, description: Server-owned current eligibility for provider-only creation; never inferred by the client.} roster_available: {type: boolean, description: This store supports a full registered-player list, including when API Off.} refresh_available: {type: boolean, description: Backend eligibility for an explicit roster refresh now.} lookup_available: {type: boolean, description: Backend eligibility for explicit native username/ID lookup now.} identifier_label: {type: string} password_required: {type: boolean} api_mode: {"$ref": "#/components/schemas/ProviderAPIAccessMode"} panel_url: {type: string, nullable: true} agent_balance_credits: {type: integer, format: int64, nullable: true} agent_observed_at: {type: string, format: date-time, nullable: true} GameStoreList: type: object required: [stores] properties: stores: {type: array, items: {"$ref": "#/components/schemas/GameStore"}} GameStorePlayer: type: object required: [id, reference, username, provider_player_id, balance_credits, last_seen, linked_player] properties: id: {type: string, format: uuid} reference: {type: string} username: {type: string} provider_player_id: {type: string} linked_player: {allOf: [{"$ref": "#/components/schemas/GameStoreLinkedPlayer"}], nullable: true} balance_credits: {type: integer, format: int64, nullable: true} last_seen: {type: string, format: date-time, nullable: true} GameStoreLinkedPlayer: type: object required: [user_id, account_id, name, password_saved] properties: user_id: {type: string, format: uuid} account_id: {type: string, format: uuid} name: {type: string} password_saved: {type: boolean} GameStorePlayers: type: object required: [snapshot_id, observed_at, total, players, next_cursor] properties: snapshot_id: {type: string, format: uuid, nullable: true} observed_at: {type: string, format: date-time, nullable: true} total: {type: integer, nullable: true, minimum: 0} players: {type: array, items: {"$ref": "#/components/schemas/GameStorePlayer"}} next_cursor: {type: string, nullable: true} GameStoreManagementReason: type: string enum: [store_version_conflict, invalid_store_target, invalid_store_roster, stale_store_roster, store_roster_unavailable, staff_authority_unavailable, refresh_owner_expired, store_api_off, store_credential_unreadable, store_link_slot_occupied, store_link_identity_unconfirmed, store_link_credential_required, store_link_player_unavailable, store_link_preview_expired, store_link_already_bound] GameStoreRefresh: type: object required: [id, store_id, state, requested_at, snapshot_id, failure_reason] properties: id: {type: string, format: uuid} store_id: {type: string, format: uuid} state: {type: string, enum: [queued, running, succeeded, failed]} requested_at: {type: string, format: date-time} snapshot_id: {type: string, format: uuid, nullable: true} failure_reason: {allOf: [{"$ref": "#/components/schemas/GameStoreManagementReason"}], nullable: true} ProviderPasswordProcedure: type: string enum: [native_reset, panel_reset, current_password_or_panel, original_reset_recovery] ProviderAccountPasswordAccessRequest: type: object additionalProperties: false required: [expected, purpose, reason] properties: expected: {"$ref": "#/components/schemas/AccountManagementExpected"} purpose: {type: string, enum: [reveal, copy]} reason: {type: string, minLength: 3, maxLength: 2000} ProviderAccountPasswordAccessResponse: type: object additionalProperties: false required: [username, password, credential_id] properties: username: {type: string} password: {type: string, description: 'Sensitive transient response: never put in caches, storage, logs, history or agent snapshots.'} credential_id: {type: string, format: uuid} AccountActivityState: type: string enum: [requested, wallet_debited, provider_requesting, pending_review, approved, reject_restoring, completed, rejected, unknown_requires_reconcile, failed_internal, source_requesting, source_debited, destination_requesting, compensating_source, compensated, needs_reconcile, succeeded, unknown, cancelled, resolved_externally, queued, running, failed, unrecognized] ProviderAccountActivityItem: type: object additionalProperties: false required: [id, kind, state, summary, occurred_at, amount_cents, provider_credits, transfer_id, related_account_id, command_id, actor_id, actor_name, reason, next_step] properties: id: {type: string, format: uuid} kind: {type: string, enum: [load, unload, credit_move_in, credit_move_out, password_reveal, password_copy_requested, management, provisioning]} state: {$ref: "#/components/schemas/AccountActivityState"} summary: {type: string} occurred_at: {type: string, format: date-time} amount_cents: {type: integer, format: int64, nullable: true} provider_credits: {type: integer, format: int64, nullable: true} transfer_id: {type: string, format: uuid, nullable: true} related_account_id: {type: string, format: uuid, nullable: true} command_id: {type: string, format: uuid, nullable: true} actor_id: {type: string, format: uuid, nullable: true} actor_name: {type: string, nullable: true} reason: {type: string, nullable: true} next_step: {type: string, nullable: true} ProviderAccountActivityResponse: type: object additionalProperties: false required: [items, next_cursor] properties: items: {type: array, items: {"$ref": "#/components/schemas/ProviderAccountActivityItem"}} next_cursor: {type: string, nullable: true} MissingProviderPasswordTask: type: object additionalProperties: false required: [account_id, user_id, player_name, provider_code, username, procedure, next_step] properties: account_id: { type: string, format: uuid } user_id: { type: string, format: uuid } player_name: { type: string } provider_code: { $ref: "#/components/schemas/ProviderCode" } username: { type: string } procedure: { $ref: "#/components/schemas/ProviderPasswordProcedure" } next_step: { type: string } MissingProviderPasswordsResponse: type: object additionalProperties: false required: [items] properties: items: type: array items: { $ref: "#/components/schemas/MissingProviderPasswordTask" } next_cursor: { type: string, format: uuid } ProviderAccountLinkState: {type: string, enum: [linking, verified, failed], x-enum-varnames: [ProviderAccountLinkLinking, ProviderAccountLinkVerified, ProviderAccountLinkFailed]} ProviderAccountProvisioningState: {type: string, enum: [queued, running, succeeded, failed, unknown_requires_reconcile], x-enum-varnames: [ProviderAccountProvisioningQueued, ProviderAccountProvisioningRunning, ProviderAccountProvisioningSucceeded, ProviderAccountProvisioningFailed, ProviderAccountProvisioningUnknown]} AccountManagementRetryPolicy: {"type":"string","enum":["same_request","new_request_after_review","no_retry"],"x-enum-varnames":["ManagementRetrySameRequest","ManagementRetryNewRequestAfterReview","ManagementRetryNoRetry"]} AccountManagementRequirements: {"type":"object","required":["reason_required","password_required","current_password_required","panel_confirmations_required","evidence_required","fresh_zero_preview_required"],"properties":{"reason_required":{"type":"boolean"},"password_required":{"type":"boolean"},"current_password_required":{"type":"boolean"},"panel_confirmations_required":{"type":"boolean"},"evidence_required":{"type":"boolean"},"fresh_zero_preview_required":{"type":"boolean"}}} AccountManagementInteractionAction: {"allOf":[{"$ref":"#/components/schemas/InteractionAction"},{"type":"object","required":["requirements","next_step","retry_policy"],"properties":{"requirements":{"$ref":"#/components/schemas/AccountManagementRequirements"},"next_step":{"type":"string"},"retry_policy":{"$ref":"#/components/schemas/AccountManagementRetryPolicy"}}}]} AccountManagementBalance: {"type":"object","required":["credits","observed_at","issue"],"properties":{"credits":{"type":"integer","format":"int64","minimum":0,"nullable":true},"observed_at":{"type":"string","format":"date-time","nullable":true},"issue":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProviderAccountIssueReason"}]},"credits_not_loaded_before_load":{"$ref":"#/components/schemas/AccountManagementCreditsNotLoaded"}}} AccountManagementCreditsNotLoaded: type: object additionalProperties: false description: Admin advisory only (ADR 0018, 2026-11-10). Present on the admin view when the current cycle's first load was admitted while the game held credits not loaded through the app; the verified balance the load preflight froze. Never a refusal or an action. required: [transfer_id, credits, cents, loaded_at] properties: transfer_id: {type: string, format: uuid} credits: {type: integer, format: int64, minimum: 1} cents: {type: integer, format: int64, minimum: 0} loaded_at: {type: string, format: date-time} AccountManagementCredentialCommand: {"type":"object","required":["command_id","outcome","owner_active","reset_dispatched"],"properties":{"command_id":{"type":"string","format":"uuid"},"outcome":{"$ref":"#/components/schemas/AccountManagementOutcome"},"owner_active":{"type":"boolean"},"reset_dispatched":{"type":"boolean"}}} AccountManagementLink: {"type":"object","required":["state","failure_code","failed_at","active_successor_id"],"properties":{"state":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProviderAccountLinkState"}]},"failure_code":{"type":"string","nullable":true},"failed_at":{"type":"string","format":"date-time","nullable":true},"active_successor_id":{"type":"string","format":"uuid","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"deadline_at":{"type":"string","format":"date-time","nullable":true}}} AccountManagementCommandResponse: {"type":"object","required":["account_id","new_revision","command_id","audit_id","credential","state","effects"],"properties":{"account_id":{"type":"string","format":"uuid"},"new_revision":{"type":"integer","format":"int64","minimum":1},"command_id":{"type":"string","format":"uuid"},"audit_id":{"type":"string","format":"uuid"},"credential":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AccountCredentialSummary"}]},"state":{"$ref":"#/components/schemas/AccountManagementOutcome"},"effects":{"type":"array","items":{"$ref":"#/components/schemas/ResourceEffect"}}}} PasswordRecoverySnapshot: {"type":"object","required":["game_id","expected","credential","options","actions","as_of","identity"],"properties":{"game_id":{"type":"string"},"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"credential":{"$ref":"#/components/schemas/AccountCredentialSummary"},"options":{"$ref":"#/components/schemas/ProviderAccountRepairOptions"},"actions":{"$ref":"#/components/schemas/AccountManagementActions"},"as_of":{"type":"string","format":"date-time"},"identity":{"$ref":"#/components/schemas/AccountManagementIdentity"},"credential_command":{"$ref":"#/components/schemas/AccountManagementCredentialCommand"}},"additionalProperties":false} RecordPanelPasswordRequest: {"type":"object","additionalProperties":false,"required":["expected","password","reason","panel_player_id","evidence","confirmed_same_store_account","confirmed_current_login"],"properties":{"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"password":{"type":"string","minLength":1,"maxLength":255,"writeOnly":true},"reason":{"type":"string","minLength":3,"maxLength":2000},"panel_player_id":{"type":"string","minLength":1},"evidence":{"$ref":"#/components/schemas/PanelPasswordEvidence"},"confirmed_same_store_account":{"type":"boolean","enum":[true]},"confirmed_current_login":{"type":"boolean","enum":[true]},"resolve_unknown_command_id":{"type":"string","format":"uuid"}}} PanelPasswordSupportMessage: {"type":"object","required":["kind","message_id"],"properties":{"kind":{"type":"string","enum":["support_message"],"x-enum-varnames":["PanelEvidenceSupportMessage"]},"message_id":{"type":"string","format":"uuid"}}} PanelPasswordPanelReference: {"type":"object","required":["kind","reference"],"properties":{"kind":{"type":"string","enum":["panel_reference"],"x-enum-varnames":["PanelEvidencePanelReference"]},"reference":{"type":"string","minLength":1,"maxLength":255}}} PanelPasswordEvidence: {"oneOf":[{"$ref":"#/components/schemas/PanelPasswordSupportMessage"},{"$ref":"#/components/schemas/PanelPasswordPanelReference"}],"discriminator":{"propertyName":"kind","mapping":{"support_message":"#/components/schemas/PanelPasswordSupportMessage","panel_reference":"#/components/schemas/PanelPasswordPanelReference"}}} UnlinkConsequences: {"type":"object","required":["account_id","removes_current_game","retains_history","wallet_change_cents","message"],"properties":{"account_id":{"type":"string","format":"uuid"},"removes_current_game":{"type":"boolean"},"retains_history":{"type":"boolean"},"wallet_change_cents":{"type":"integer","format":"int64","enum":[0]},"message":{"type":"string"}}} UnlinkPreviewRequest: {"type":"object","additionalProperties":false,"required":["expected","reason"],"properties":{"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"reason":{"type":"string","minLength":3,"maxLength":2000},"reference":{"type":"string","minLength":1,"maxLength":255,"nullable":true}}} UnlinkPreviewCancelResponse: {type: object, required: [preview_id, state], properties: {preview_id: {type: string, format: uuid}, state: {$ref: "#/components/schemas/UnlinkPreviewState"}}} UnlinkPreviewResponse: {"type":"object","required":["preview_id","state","expected","expires_at","zero_proof_at","zero_proof_value","consequences","action"],"properties":{"preview_id":{"type":"string","format":"uuid"},"state":{"$ref":"#/components/schemas/UnlinkPreviewState"},"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"expires_at":{"type":"string","format":"date-time"},"zero_proof_at":{"type":"string","format":"date-time","nullable":true},"zero_proof_value":{"type":"integer","format":"int64","enum":[0],"nullable":true},"consequences":{"$ref":"#/components/schemas/UnlinkConsequences"},"action":{"$ref":"#/components/schemas/AccountManagementInteractionAction"}}} LinkVerificationRetryRequest: {"type":"object","additionalProperties":false,"required":["expected","expected_slot","account_identifier","password","reason"],"properties":{"expected_slot":{"$ref":"#/components/schemas/ProviderSlotExpected"},"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"account_identifier":{"type":"string","minLength":1,"maxLength":255},"password":{"type":"string","minLength":1,"maxLength":255,"writeOnly":true},"reason":{"type":"string","minLength":3,"maxLength":2000},"reference":{"type":"string","minLength":1,"maxLength":255}}} LinkVerificationRetryResponse: {"type":"object","required":["original_account_id","attempt_account_id","expected","state","effects"],"properties":{"original_account_id":{"type":"string","format":"uuid"},"attempt_account_id":{"type":"string","format":"uuid"},"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"state":{"$ref":"#/components/schemas/AccountManagementOutcome"},"effects":{"type":"array","items":{"$ref":"#/components/schemas/ResourceEffect"}}}} CredentialProvenance: {"type":"string","enum":["legacy_unknown","player_supplied_unverified","native_password_verified","native_creation_confirmed","native_reset_confirmed","staff_panel_attested"],"x-enum-varnames":["CredentialProvenanceLegacyUnknown","CredentialProvenancePlayerSuppliedUnverified","CredentialProvenanceNativePasswordVerified","CredentialProvenanceNativeCreationConfirmed","CredentialProvenanceNativeResetConfirmed","CredentialProvenanceStaffPanelAttested"]} AccountManagementOperation: {"type":"string","enum":["link_existing","verify_current_password","reset_password","record_panel_password","retry_link_verification","unlink_preview","cancel_unlink_preview","unlink"],"x-enum-varnames":["AccountManagementOperationLinkExisting","AccountManagementOperationVerifyCurrentPassword","AccountManagementOperationResetPassword","AccountManagementOperationRecordPanelPassword","AccountManagementOperationRetryLinkVerification","AccountManagementOperationUnlinkPreview","AccountManagementOperationCancelUnlinkPreview","AccountManagementOperationUnlink"]} AccountManagementOutcome: {"type":"string","enum":["requested","succeeded","rejected","unknown","cancelled","resolved_externally"],"x-enum-varnames":["AccountManagementOutcomeRequested","AccountManagementOutcomeSucceeded","AccountManagementOutcomeRejected","AccountManagementOutcomeUnknown","AccountManagementOutcomeCancelled","AccountManagementOutcomeResolvedExternally"]} UnlinkPreviewState: {"type":"string","enum":["ready","blocked","consumed","cancelled","expired"],"x-enum-varnames":["UnlinkPreviewStateReady","UnlinkPreviewStateBlocked","UnlinkPreviewStateConsumed","UnlinkPreviewStateCancelled","UnlinkPreviewStateExpired"]} ProviderAccountManagementReason: {"type":"string","enum":["saved_password_unavailable","credential_unreadable","version_conflict","capability_unavailable","current_password_required","account_management_busy","active_successor_exists","link_attempt_in_progress","balance_not_zero","balance_unverified","preview_required","preview_expired","preview_owner_mismatch","panel_attestation_required","panel_identity_mismatch","command_resolved_externally"],"x-enum-varnames":["ProviderAccountManagementReasonSavedPasswordUnavailable","ProviderAccountManagementReasonCredentialUnreadable","ProviderAccountManagementReasonVersionConflict","ProviderAccountManagementReasonCapabilityUnavailable","ProviderAccountManagementReasonCurrentPasswordRequired","ProviderAccountManagementReasonAccountManagementBusy","ProviderAccountManagementReasonActiveSuccessorExists","ProviderAccountManagementReasonLinkAttemptInProgress","ProviderAccountManagementReasonBalanceNotZero","ProviderAccountManagementReasonBalanceUnverified","ProviderAccountManagementReasonPreviewRequired","ProviderAccountManagementReasonPreviewExpired","ProviderAccountManagementReasonPreviewOwnerMismatch","ProviderAccountManagementReasonPanelAttestationRequired","ProviderAccountManagementReasonPanelIdentityMismatch","ProviderAccountManagementReasonCommandResolvedExternally"]} AccountManagementExpected: {"type":"object","additionalProperties":false,"required":["management_revision","identity_fingerprint","credential_id","credential_updated_at","provisioning_id","provisioning_updated_at"],"properties":{"management_revision":{"type":"integer","format":"int64","minimum":1,"nullable":true},"identity_fingerprint":{"type":"string","minLength":64,"maxLength":64},"credential_id":{"type":"string","format":"uuid","nullable":true},"credential_updated_at":{"type":"string","format":"date-time","nullable":true},"provisioning_id":{"type":"string","format":"uuid","nullable":true},"provisioning_updated_at":{"type":"string","format":"date-time","nullable":true}}} ProviderSlotExpected: {"type":"object","additionalProperties":false,"required":["occupying_account_id","provisioning_id","provisioning_updated_at"],"properties":{"occupying_account_id":{"type":"string","format":"uuid","nullable":true},"provisioning_id":{"type":"string","format":"uuid","nullable":true},"provisioning_updated_at":{"type":"string","format":"date-time","nullable":true}}} AccountCredentialSummary: {"type":"object","additionalProperties":false,"required":["saved","source","verified_at"],"properties":{"saved":{"type":"boolean"},"source":{"$ref":"#/components/schemas/CredentialProvenance"},"verified_at":{"type":"string","format":"date-time","nullable":true}}} AccountManagementIdentity: {"type":"object","additionalProperties":false,"required":["account_id","user_id","provider_code","reference","username","player_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"provider_code":{"type":"string"},"reference":{"type":"string"},"username":{"type":"string"},"player_id":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/AdminProviderAccountStatus"}}} AccountManagementAudit: {"type":"object","additionalProperties":false,"required":["id","actor_id","command_id","operation","outcome","before_revision","after_revision","reason","created_at","retry_id","preview_id","resolved_command_id"],"properties":{"id":{"type":"string","format":"uuid"},"actor_id":{"type":"string","format":"uuid"},"command_id":{"type":"string","format":"uuid"},"operation":{"$ref":"#/components/schemas/AccountManagementOperation"},"outcome":{"$ref":"#/components/schemas/AccountManagementOutcome"},"before_revision":{"type":"integer","format":"int64","nullable":true},"after_revision":{"type":"integer","format":"int64","nullable":true},"reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"retry_id":{"type":"string","format":"uuid","nullable":true},"preview_id":{"type":"string","format":"uuid","nullable":true},"resolved_command_id":{"type":"string","format":"uuid","nullable":true}}} AccountManagementSetupHistory: {"type":"object","additionalProperties":false,"required":["id","state","archived","created_at","updated_at","job_ids"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"$ref":"#/components/schemas/ProviderAccountProvisioningState"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"job_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}} AccountManagementActions: {"type":"object","additionalProperties":false,"required":["verify_current_password","reset_password","record_panel_password","retry_link_verification","unlink_preview"],"properties":{"load":{"$ref":"#/components/schemas/AdminWalletTransferRequest"},"unload":{"$ref":"#/components/schemas/AdminWalletTransferRequest"},"access_saved_password":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"refresh_balance":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"verify_current_password":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"reset_password":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"record_panel_password":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"retry_link_verification":{"$ref":"#/components/schemas/AccountManagementInteractionAction"},"unlink_preview":{"$ref":"#/components/schemas/AccountManagementInteractionAction"}}} AccountManagementSnapshot: {"type":"object","additionalProperties":false,"required":["as_of","expected","identity","credential","options","actions","audit","setup_history","balance","link","credential_command"],"properties":{"as_of":{"type":"string","format":"date-time"},"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"identity":{"$ref":"#/components/schemas/AccountManagementIdentity"},"credential":{"$ref":"#/components/schemas/AccountCredentialSummary"},"options":{"$ref":"#/components/schemas/ProviderAccountRepairOptions"},"actions":{"$ref":"#/components/schemas/AccountManagementActions"},"audit":{"type":"array","items":{"$ref":"#/components/schemas/AccountManagementAudit"}},"setup_history":{"type":"array","items":{"$ref":"#/components/schemas/AccountManagementSetupHistory"}},"balance":{"$ref":"#/components/schemas/AccountManagementBalance"},"link":{"$ref":"#/components/schemas/AccountManagementLink"},"credential_command":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AccountManagementCredentialCommand"}]}}} AccountRepairVerification: {"type":"string","enum":["agent_roster","credential_read","balance_read_only","unavailable"],"x-enum-varnames":["AccountRepairAgentRoster","AccountRepairCredentialRead","AccountRepairBalanceReadOnly","AccountRepairUnavailable"]} PasswordResetResultKind: {"type":"string","enum":["password_material","credential_reference","unavailable"],"x-enum-varnames":["PasswordResetResultKindPasswordMaterial","PasswordResetResultKindCredentialReference","PasswordResetResultKindUnavailable"]} AdminPlayerExportField: type: string enum: [username, email, phone, payout_tags, created_date, status, last_seen] AdminPlayerExportRequest: type: object additionalProperties: false required: [fields, scope] properties: fields: type: array minItems: 1 maxItems: 7 uniqueItems: true items: "$ref": "#/components/schemas/AdminPlayerExportField" scope: type: string enum: [filtered, all] q: type: string maxLength: 256 status: "$ref": "#/components/schemas/UserStatus" deposit_recency: "$ref": "#/components/schemas/AdminRechargeRecencyFilter" game_load_recency: "$ref": "#/components/schemas/AdminRechargeRecencyFilter" EmulationRefusalReason: type: string enum: [invalid_grant, session_mismatch, expired, ended, view_only, operation_never, operation_unclassified, admin_required, super_admin_required, control_header_forbidden] x-enum-varnames: [EmulationInvalidGrant, EmulationSessionMismatch, EmulationExpired, EmulationEnded, EmulationViewOnly, EmulationOperationNever, EmulationOperationUnclassified, EmulationAdminRequired, EmulationSuperAdminRequired, EmulationControlHeaderForbidden] EmulationMode: type: string enum: [view, act] x-enum-varnames: [EmulationModeView, EmulationModeAct] EmulationGrantCreate: type: object additionalProperties: false required: [player_id, reason] properties: player_id: {type: string, format: uuid} reason: {type: string, minLength: 3, maxLength: 400} EmulationFullAccess: type: object additionalProperties: false required: [reason] properties: reason: {type: string, minLength: 3, maxLength: 400} EmulationGrant: type: object required: [id, actor_id, player_id, player_name, mode, reason, created_at, expires_at, ended_at, can_enable_full_access] properties: id: {type: string, format: uuid} actor_id: {type: string, format: uuid} player_id: {type: string, format: uuid} player_name: {type: string} mode: {"$ref": "#/components/schemas/EmulationMode"} reason: {type: string} created_at: {type: string, format: date-time} expires_at: {type: string, format: date-time} ended_at: {type: string, format: date-time, nullable: true} can_enable_full_access: {type: boolean} DollarPayFormCallback: type: object description: Scalar POST-form callback fields from the DollarPay pay-in and payout documentation. The adapter verifies all fields, including extensions, against the sorted MD5 signature before settlement. additionalProperties: true properties: merchant_id: type: string transaction_id: type: string outer_order_sn: type: string pay_status: type: string amount: type: string primary_amount: type: string user_name: type: string status: type: string msg: type: string sign: type: string details: type: string notes: type: string img: type: string ClientOutdatedErrorResponse: type: object required: [error] properties: error: type: object required: [code, message] properties: code: type: string enum: [client_outdated] x-enum-varnames: [OutdatedClientBuild] message: type: string request_id: type: string UserStatus: type: string enum: - pending_email_verification - active - suspended - banned UserRole: type: string enum: - player - admin - super_admin HealthResponse: type: object required: - status - version - uptime_sec - schema_compatibility properties: schema_compatibility: "$ref": "#/components/schemas/SchemaCompatibility" status: type: string enum: - ok version: type: string commit: type: string nullable: true uptime_sec: type: integer format: int64 minimum: 0 SchemaCompatibility: type: object additionalProperties: false description: Compiled inclusive schema range checked against real Goose state at startup and readiness; target is the packaged migration target. required: [min, max, target] properties: min: type: integer format: int64 minimum: 1 maximum: 2147483647 max: type: integer format: int64 minimum: 1 maximum: 2147483647 target: type: integer format: int64 minimum: 1 maximum: 2147483647 VisitorPeriod: type: string enum: [today, 7d, 30d] x-go-type: visitors.Period x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} VisitorSizeBucket: x-go-type: visitors.SizeBucket x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} type: string enum: [small, medium, large, unknown] VisitorPointer: x-go-type: visitors.Pointer x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} type: string enum: [coarse, fine, none, unknown] VisitorDurationBucket: x-go-type: visitors.DurationBucket x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} type: string enum: [under_10s, 10s_to_1m, 1m_to_5m, over_5m, unknown] VisitorSessionObservation: type: object additionalProperties: false x-go-type: visitors.Observation x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} properties: timezone: {type: string, maxLength: 64} language: {type: string, maxLength: 32} screen_bucket: {$ref: '#/components/schemas/VisitorSizeBucket'} viewport_bucket: {$ref: '#/components/schemas/VisitorSizeBucket'} touch_capable: {type: boolean, nullable: true} pointer: {$ref: '#/components/schemas/VisitorPointer'} duration_bucket: {description: Optional approximate browser signal; duration reporting uses server observation span., $ref: '#/components/schemas/VisitorDurationBucket'} referrer_domain: {type: string, maxLength: 253} landing_path: {type: string, maxLength: 256} utm_source: {type: string, maxLength: 64} utm_medium: {type: string, maxLength: 64} utm_campaign: {type: string, maxLength: 64} agent_tag: {type: string, maxLength: 64} referral_tag: {type: string, maxLength: 64} VisitorInsights: type: object additionalProperties: false required: [collecting_since, timezone, current, previous] x-go-type: visitors.Insights x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} properties: collecting_since: {type: string, format: date-time, nullable: true} timezone: {type: string, enum: [America/New_York]} current: {$ref: '#/components/schemas/VisitorWindow'} previous: {$ref: '#/components/schemas/VisitorWindow'} VisitorWindow: type: object additionalProperties: false required: [start, end, measured, visitors, sessions, new_visitors, returning_visitors, authenticated_players, depositors, funnel, breakdowns, coverage] properties: start: {type: string, format: date-time} end: {type: string, format: date-time} measured: {type: boolean} visitors: {type: integer, format: int64, minimum: 0} sessions: {type: integer, format: int64, minimum: 0} new_visitors: {type: integer, format: int64, minimum: 0} returning_visitors: {type: integer, format: int64, minimum: 0} authenticated_players: {type: integer, format: int64, minimum: 0} depositors: {type: integer, format: int64, minimum: 0} funnel: {$ref: '#/components/schemas/VisitorFunnel'} breakdowns: {type: array, maxItems: 23, items: {$ref: '#/components/schemas/VisitorBreakdown'}} coverage: {$ref: '#/components/schemas/VisitorCoverage'} VisitorFunnel: type: object required: [visitors, signups, first_deposit, first_game_load] properties: visitors: {type: integer, format: int64, minimum: 0} signups: {type: integer, format: int64, minimum: 0} first_deposit: {type: integer, format: int64, minimum: 0} first_game_load: {type: integer, format: int64, minimum: 0} VisitorCoverage: description: Delivery diagnostics for the complete New York calendar dates touched by the window; partial boundary dates are not elapsed-window precise and must not be used for period-change comparisons. type: object required: [accepted_observations, dropped_observations, unknown_observations, excluded_sessions] properties: excluded_sessions: {type: integer, format: int64, minimum: 0, description: Known linked staff/test/system/bot sessions excluded from the exact window; anonymous exclusions are unmeasured.} accepted_observations: {type: integer, format: int64, minimum: 0} dropped_observations: {type: integer, format: int64, minimum: 0} unknown_observations: {type: integer, format: int64, minimum: 0} VisitorDimension: type: string enum: [device_class, os_family, browser_family, in_app_browser_kind, display_mode, country, region, timezone, language, screen_bucket, viewport_bucket, touch, pointer, duration_bucket, referrer_domain, landing_path, utm_source, utm_medium, utm_campaign, agent_tag, referral_tag, os_major, browser_major] x-go-type: visitors.Dimension x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/visitors} VisitorBreakdown: type: object required: [dimension, measured, buckets] properties: dimension: {$ref: '#/components/schemas/VisitorDimension'} measured: {type: boolean} buckets: {type: array, maxItems: 102, items: {$ref: '#/components/schemas/VisitorBucket'}} VisitorBucket: type: object required: [value, visitors, funnel_visitors, sessions, authenticated_players, depositors, signups, first_deposit, first_game_load] properties: value: {type: string, maxLength: 253} funnel_visitors: {type: integer, format: int64, minimum: 0, description: First-visit cohort browsers attributed to this segment; denominator for conversion rates.} visitors: {type: integer, format: int64, minimum: 0} sessions: {type: integer, format: int64, minimum: 0} authenticated_players: {type: integer, format: int64, minimum: 0} depositors: {type: integer, format: int64, minimum: 0} signups: {type: integer, format: int64, minimum: 0} first_deposit: {type: integer, format: int64, minimum: 0} first_game_load: {type: integer, format: int64, minimum: 0} ClientDiagnosticBuild: type: string pattern: '^(?:[0-9a-f]{40}|dev)$' maxLength: 40 description: Frontend git rev-parse HEAD at build time, or dev for local Vite. ClientDiagnosticInAppBrowserKind: type: string enum: [messenger, facebook, instagram, other, none] description: Bounded app marker classification; never the raw user agent. ClientDiagnosticRequest: type: object additionalProperties: false required: - tab_build_id - latest_served_build_id - failed_chunk_url - service_worker - cache_names - display_mode - user_agent - in_app_browser - recovery_step - outcome - elapsed_ms properties: tab_build_id: "$ref": "#/components/schemas/ClientDiagnosticBuild" latest_served_build_id: type: string nullable: true pattern: '^(?:[0-9a-f]{40}|dev)$' maxLength: 40 description: Reported frontend marker from /version; null when unknown. failed_chunk_url: type: string nullable: true maxLength: 256 description: Static asset path; server discards origin, query, fragment and unsafe paths. service_worker: type: object additionalProperties: false required: [controller_script_url, waiting_state, installing_state] properties: controller_script_url: type: string nullable: true maxLength: 256 waiting_state: "$ref": "#/components/schemas/ClientDiagnosticWorkerState" installing_state: "$ref": "#/components/schemas/ClientDiagnosticWorkerState" cache_names: type: array maxItems: 16 items: type: string maxLength: 128 display_mode: type: string enum: [browser, standalone] user_agent: type: object additionalProperties: false required: [family, version] properties: family: type: string enum: [chrome, safari, firefox, edge, opera, samsung, other] version: type: string nullable: true maxLength: 32 pattern: '^[0-9]+(?:\.[0-9]+){0,5}$' in_app_browser: type: boolean in_app_browser_kind: "$ref": "#/components/schemas/ClientDiagnosticInAppBrowserKind" description: Optional for older clients; omitted maps to other when in_app_browser is true, otherwise none. recovery_step: type: string enum: [refresh_page, automatic_recovery, manual_recovery, recovery_navigation] outcome: type: string enum: [shown, started, cleanup_complete, cleanup_partial, navigation_requested, navigation_failed, recovered, exhausted] elapsed_ms: type: integer format: int64 minimum: 0 maximum: 9007199254740991 player_id: type: string format: uuid description: Untrusted client claim; validated shape then ignored for correlation. ClientDiagnosticWorkerState: type: string enum: [unknown, none, installing, installed, activating, activated, redundant] VersionResponse: type: object required: - version properties: client_build: type: string nullable: true pattern: '^(?:[0-9a-f]{40}|dev)$' maxLength: 40 description: Current frontend release SHA for update notices and release verification. api_contract_sha256: type: string pattern: '^[0-9a-f]{64}$' description: SHA-256 of the API contract once the deployed frontend and PlayGo agree on it. version: type: string commit: type: string nullable: true date: type: string nullable: true AuthUser: type: object required: - id - email - display_name - role - status - created_at - username - username_default properties: id: type: string format: uuid email: type: string format: email display_name: type: string minLength: 1 role: "$ref": "#/components/schemas/UserRole" status: "$ref": "#/components/schemas/UserStatus" phone: type: string nullable: true description: >- E.164-style phone number with any user-provided formatting (spaces, hyphens, parentheses) preserved, or null when not set. birthday: type: string format: date nullable: true description: Date of birth (YYYY-MM-DD), or null when not set. address: type: string nullable: true description: Free-text postal address, or null when not set. username: type: string nullable: true pattern: '^[a-z0-9]{3,11}$' description: Stored optional game-login base; no uniqueness requirement. username_default: type: string minLength: 1 maxLength: 11 description: Server-normalized email-derived default base for the placeholder. created_at: type: string format: date-time ProfileMeResponse: type: object required: - authenticated - user - csrf_token properties: authenticated: type: boolean user: nullable: true allOf: - "$ref": "#/components/schemas/AuthUser" csrf_token: type: string minLength: 1 OnboardingState: type: object required: - acknowledged_version - acknowledged_at properties: acknowledged_version: type: integer format: int32 minimum: 1 nullable: true description: >- Highest walkthrough version this user has acknowledged, or null when they never have. The client auto-starts the walkthrough when its own version is greater (or when this is null). Recorded when the tour STARTS, not when it finishes, so a mid-tour reload does not restart it — it means "do not auto-start again", not "reached the last step". acknowledged_at: type: string format: date-time nullable: true description: >- When the acknowledged version was first recorded, or null when never. Null exactly when acknowledged_version is null. AcknowledgeOnboardingRequest: type: object additionalProperties: false required: - acknowledged_version properties: acknowledged_version: type: integer format: int32 minimum: 1 maximum: 2147483647 description: >- The walkthrough version the client has just shown the user. Bounded to int32 because the stored column is a Postgres integer: a wider value would wrap on the way into the query and silently write a different version than the one requested. DevSettings: type: object required: - is_tester properties: is_tester: type: boolean description: Whether the current user is on the admin-managed tester allowlist. AdminOnlinePlayer: type: object required: [user_id, username, last_seen_at, last_action, game] properties: user_id: {type: string, format: uuid} username: {type: string} last_seen_at: {type: string, format: date-time} last_action: {type: string, enum: [Browsing, Chat, Payments, Game]} game: type: object nullable: true required: [name] properties: name: {type: string} AdminOnlinePlayersResponse: type: object required: [as_of, online_count, in_game_count, players] properties: as_of: {type: string, format: date-time} online_count: {type: integer, format: int64, minimum: 0} in_game_count: {type: integer, format: int64, minimum: 0} players: {type: array, items: {"$ref": "#/components/schemas/AdminOnlinePlayer"}} AdminTester: type: object required: - user_id - email properties: user_id: type: string format: uuid email: type: string format: email AdminTestersResponse: type: object required: - testers properties: testers: type: array items: "$ref": "#/components/schemas/AdminTester" AddTesterRequest: type: object additionalProperties: false required: - email properties: email: type: string format: email minLength: 3 AuthUserResponse: type: object required: - user properties: user: $ref: "#/components/schemas/AuthUser" VerifyCodeResponse: type: object required: - user - is_new properties: user: $ref: "#/components/schemas/AuthUser" is_new: type: boolean description: >- True when this verification just activated a brand-new (pending email verification) account — i.e. it was a signup, not a returning login. The client uses this to offer a one-time "set a password" prompt. False for returning logins. LoginRequest: type: object required: - email - password additionalProperties: false properties: email: type: string format: email password: type: string minLength: 8 maxLength: 256 LogoutResponse: type: object required: - ok properties: ok: type: boolean RequestLoginRequest: type: object required: [email] additionalProperties: false properties: email: type: string format: email anonymous_subject: type: string format: uuid description: >- Anonymous acquisition subject to link transactionally when this passwordless flow creates a user. It is not a referral identifier. PasswordlessLoginRequestedResponse: type: object required: [email, resend_available_at, expires_at] additionalProperties: false properties: email: type: string format: email resend_available_at: type: string format: date-time expires_at: type: string format: date-time dev_code: type: string nullable: true description: Never set in staging or prod. The login code, present only on env local with the local reveal hook on, or with CFG_AUTH_REVEAL_TEST_CODES on for an email under a reserved test TLD (see request-login). VerifyCodeRequest: type: object required: [email, code] additionalProperties: false properties: email: type: string format: email code: type: string minLength: 6 maxLength: 6 pattern: "^[0-9]{6}$" VerifyMagicLinkRequest: type: object required: [token] additionalProperties: false properties: token: type: string minLength: 1 SignupPreferencesRequest: type: object additionalProperties: false properties: username: type: string maxLength: 120 description: Optional raw username base. Empty leaves the current value unchanged. password: type: string maxLength: 256 description: Optional password. Empty leaves the current password unchanged. SignupPreferencesResponse: type: object required: [user, replayed] properties: user: {"$ref": "#/components/schemas/AuthUser"} replayed: {type: boolean} SignupPreferencesValidationError: type: object required: [error, field] properties: error: {"$ref": "#/components/schemas/APIError"} field: type: string enum: [username, password] x-enum-varnames: [SignupPreferencesValidationErrorFieldUsername, SignupPreferencesValidationErrorFieldPassword] SetPasswordRequest: type: object required: [password] additionalProperties: false properties: password: type: string minLength: 8 maxLength: 256 SetPasswordResponse: type: object required: [ok] properties: ok: type: boolean UpdateProfileRequest: type: object description: >- Partial update of the editable profile fields. Each field is optional; only present fields change. For the optional contact fields (phone, birthday, address) an empty string clears the stored value. Email is not accepted here — it is the login identity and requires a verified change flow. additionalProperties: false minProperties: 1 properties: display_name: type: string minLength: 1 maxLength: 120 description: New display name. Cannot be blank when present. phone: type: string maxLength: 32 description: E.164-style phone. Empty string clears the stored phone. birthday: type: string format: date maxLength: 10 description: Date of birth (YYYY-MM-DD). Empty string clears the stored birthday. address: type: string maxLength: 512 description: Free-text postal address. Empty string clears the stored address. CurrencyCode: type: string enum: - USD MoneyAmount: type: object description: API presentation amount normalized from DB-owned numeric(22,4); not the DB storage/query type. required: - amount_cents - currency_code properties: amount_cents: type: integer format: int64 currency_code: "$ref": "#/components/schemas/CurrencyCode" ProviderCreditAmount: type: object description: API presentation credits normalized from DB-owned numeric(22,4); not the DB storage/query type. required: - credits properties: credits: type: integer format: int64 Pagination: type: object required: - page - per_page - has_next properties: page: type: integer minimum: 1 per_page: type: integer minimum: 1 has_next: type: boolean RedactedEvidenceSummary: type: object required: - provider_code - operation - observed_at properties: provider_code: "$ref": "#/components/schemas/ProviderCode" operation: type: string enum: - create_player - credit_player - debit_player - read_player_balance - launch_game - reset_player_password - find_transfer - list_transfer_records - list_game_records request_id: type: string nullable: true external_order_id: type: string nullable: true http_status: type: integer nullable: true provider_status: type: string nullable: true provider_message: type: string nullable: true latency_ms: type: integer format: int64 nullable: true observed_at: type: string format: date-time WalletSnapshot: type: object required: - user_id - cash_balance - withdrawable_cash - pending_withdrawal - freeplay - total_balance - deposit_bonus - provider_summaries properties: user_id: type: string format: uuid cash_balance: "$ref": "#/components/schemas/MoneyAmount" withdrawable_cash: "$ref": "#/components/schemas/MoneyAmount" pending_withdrawal: "$ref": "#/components/schemas/MoneyAmount" total_balance: description: Server-owned Cash + Withdrawable Cash + Deposit bonus + Free play; excludes reserved Pending withdrawal. "$ref": "#/components/schemas/MoneyAmount" bonus_breakdown: $ref: "#/components/schemas/WalletBonusBreakdown" deposit_bonus: description: Total Bonus available to play, including the referral component. "$ref": "#/components/schemas/MoneyAmount" freeplay: "$ref": "#/components/schemas/MoneyAmount" provider_summaries: type: array items: "$ref": "#/components/schemas/ProviderCreditSummary" WalletBonusBreakdown: type: object required: [deposit_bonus, referral_bonus] properties: deposit_bonus: {$ref: "#/components/schemas/MoneyAmount"} referral_bonus: {$ref: "#/components/schemas/MoneyAmount"} bonus_only_terms: {$ref: "#/components/schemas/WalletBonusOnlyTerms"} WalletBonusOnlyTerms: type: object required: [enabled, minimum_net_winnings, maximum_payout] properties: enabled: {type: boolean} minimum_net_winnings: {$ref: "#/components/schemas/MoneyAmount"} maximum_payout: {$ref: "#/components/schemas/MoneyAmount"} WalletSnapshotResponse: type: object required: - wallet properties: wallet: "$ref": "#/components/schemas/WalletSnapshot" ProviderCreditSummary: type: object required: - provider_code - provider_account_id - balance_credits - observed properties: provider_code: "$ref": "#/components/schemas/ProviderCode" provider_account_id: type: string format: uuid balance_credits: description: API presentation value normalized from DB-owned numeric(22,4) provider balance. type: integer format: int64 observed: type: boolean WalletTransaction: type: object required: - id - type - status - amount - created_at properties: id: type: string format: uuid type: type: string enum: - wallet_credit - wallet_debit - provider_transfer - payment_withdrawal status: type: string enum: - posted - pending - rejected - unknown_requires_reconcile x-enum-varnames: - WalletTransactionStatusPosted - WalletTransactionStatusPending - WalletTransactionStatusRejected - WalletTransactionStatusUnknownRequiresReconcile amount: "$ref": "#/components/schemas/MoneyAmount" provider_code: "$ref": "#/components/schemas/ProviderCode" nullable: true transfer_id: type: string format: uuid nullable: true created_at: type: string format: date-time WalletTransactionsResponse: type: object required: - transactions - pagination properties: transactions: type: array items: "$ref": "#/components/schemas/WalletTransaction" pagination: "$ref": "#/components/schemas/Pagination" ProviderCode: type: string minLength: 2 maxLength: 64 pattern: "^[a-z0-9][a-z0-9_-]{1,63}$" ProviderCapability: type: string enum: - player_list - create_player - credit - debit - balance - launch - reset_password - transfer_find - transfer_list - game_log - agent_balance - force_player_offline - player_link ProviderCapabilityStatus: type: string enum: - enabled - disabled - degraded - reconciliation_only ProviderFamily: type: string enum: - fastapi - wsterminal - gamevault - juwa - bluedragon - riverpay - cashier - agentserver - slotopool - yolo ProviderAPIAccessMode: type: string enum: [on, off] x-enum-varnames: [ProviderAPIOn, ProviderAPIOff] ProviderAPIAccessState: type: string enum: [on, turning_off, off] x-enum-varnames: [ProviderAPIStateOn, ProviderAPIStateTurningOff, ProviderAPIStateOff] ProviderAPIAccessAvailability: type: object required: [mode, state] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} mode: {"$ref": "#/components/schemas/ProviderAPIAccessMode"} state: {"$ref": "#/components/schemas/ProviderAPIAccessState"} AdminProviderAPIAccessAvailability: type: object required: [mode, state] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} mode: {"$ref": "#/components/schemas/ProviderAPIAccessMode"} state: {"$ref": "#/components/schemas/ProviderAPIAccessState"} expires_at: {type: string, format: date-time, nullable: true, readOnly: true, description: Active server-owned automatic On deadline. Null means Off stays until manually changed. Expiry alone does not imply On until the audited change commits.} ProviderAPIAccess: type: object required: [provider_code, mode, state, version, active_calls, unresolved_operations, changed_at, changed_by, changed_by_name, reason, agent_balance_polling] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} provider_code: {"$ref": "#/components/schemas/ProviderCode"} mode: {"$ref": "#/components/schemas/ProviderAPIAccessMode"} state: {"$ref": "#/components/schemas/ProviderAPIAccessState"} version: {type: integer, format: int64} active_calls: {type: integer} unresolved_operations: {type: integer} expires_at: {type: string, format: date-time, nullable: true, readOnly: true} last_change_automatic: {type: boolean, readOnly: true, description: The last change executed a staff-authorized auto-on timer. changed_by identifies its initiating staff member.} changed_at: {type: string, format: date-time, nullable: true} changed_by: {type: string, format: uuid, nullable: true} changed_by_name: {type: string, nullable: true} reason: {type: string, nullable: true} agent_balance_polling: type: string enum: [automatic, on_request] description: On-request avoids scheduled logins for protocols where reading agent balance requires login. Existing observations retain their original time. ProviderAPIAccessValidationError: type: object required: [error, fields] properties: error: {"$ref": "#/components/schemas/APIError"} fields: type: object additionalProperties: {type: string} ProviderAPIAccessConflict: type: object required: [error, current] properties: error: {"$ref": "#/components/schemas/APIError"} current: {"$ref": "#/components/schemas/ProviderAPIAccess"} Provider: type: object required: - code - display_name - family - capabilities properties: api_access: {"$ref": "#/components/schemas/ProviderAPIAccessAvailability"} code: "$ref": "#/components/schemas/ProviderCode" display_name: type: string family: "$ref": "#/components/schemas/ProviderFamily" capabilities: type: array items: "$ref": "#/components/schemas/ProviderCapabilityState" ProviderCapabilityState: type: object required: - capability - status properties: capability: "$ref": "#/components/schemas/ProviderCapability" status: "$ref": "#/components/schemas/ProviderCapabilityStatus" ProvidersResponse: type: object required: - providers properties: providers: type: array items: "$ref": "#/components/schemas/Provider" AdminProvidersResponse: type: object required: [providers, payment_providers] properties: game_store_management_enabled: type: boolean description: ADR 0061 Connect admin site setting. True admits the admin game store table and the game and payment provider Connect surfaces; false or absent means the backend refuses them and the admin hides them. providers: type: array items: {"$ref": "#/components/schemas/AdminProvider"} payment_providers: type: array items: {"$ref": "#/components/schemas/AdminPaymentProvider"} AdminProvider: type: object required: [code, display_name, family, capabilities] properties: api_access: {"$ref": "#/components/schemas/AdminProviderAPIAccessAvailability"} code: {"$ref": "#/components/schemas/ProviderCode"} display_name: {type: string} family: {"$ref": "#/components/schemas/ProviderFamily"} capabilities: type: array items: {"$ref": "#/components/schemas/ProviderCapabilityState"} panel_url: description: The provider's operator back-office, when configured. type: string format: uri transfer_verification: {"$ref": "#/components/schemas/ProviderTransferVerification"} ProviderPanelLinkKind: type: string enum: [game, payment] x-enum-varnames: [ProviderPanelLinkKindGame, ProviderPanelLinkKindPayment] ProviderPanelLinkSource: type: string description: Where the effective link comes from. enum: [override, config, none] x-enum-varnames: [ProviderPanelLinkSourceOverride, ProviderPanelLinkSourceConfig, ProviderPanelLinkSourceNone] ProviderPanelLinkOverrideState: type: string description: custom = an admin set a link, removed = an admin hid the link, none = the setup value is in use. enum: [none, custom, removed] x-enum-varnames: [ProviderPanelLinkOverrideNone, ProviderPanelLinkOverrideCustom, ProviderPanelLinkOverrideRemoved] ProviderPanelLinkAction: type: string description: set needs url; remove shows no link; reset goes back to the setup link. enum: [set, remove, reset] x-enum-varnames: [ProviderPanelLinkActionSet, ProviderPanelLinkActionRemove, ProviderPanelLinkActionReset] ProviderPanelLinkReason: type: string enum: [link_changed, link_broken, provider_moved, other] x-enum-varnames: [ProviderPanelLinkReasonLinkChanged, ProviderPanelLinkReasonLinkBroken, ProviderPanelLinkReasonProviderMoved, ProviderPanelLinkReasonOther] ProviderPanelLinkProblem: type: string description: Why a link change was refused as invalid. not_https denotes a scheme other than HTTP or HTTPS. enum: [not_a_url, not_https, no_host, has_credentials, has_query, has_fragment, too_long, url_missing, unknown_reason, note_required, note_too_long, unknown_action, unchanged] x-enum-varnames: - ProviderPanelLinkProblemNotAURL - ProviderPanelLinkProblemNotHTTPS - ProviderPanelLinkProblemNoHost - ProviderPanelLinkProblemHasCredentials - ProviderPanelLinkProblemHasQuery - ProviderPanelLinkProblemHasFragment - ProviderPanelLinkProblemTooLong - ProviderPanelLinkProblemURLMissing - ProviderPanelLinkProblemUnknownReason - ProviderPanelLinkProblemNoteRequired - ProviderPanelLinkProblemNoteTooLong - ProviderPanelLinkProblemUnknownAction - ProviderPanelLinkProblemUnchanged AdminProviderPanelLink: type: object required: [kind, provider_code, display_name, source, override_state, version] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} kind: {"$ref": "#/components/schemas/ProviderPanelLinkKind"} provider_code: {type: string} display_name: {type: string} effective_url: description: The link admins open; absent when there is none. type: string format: uri source: {"$ref": "#/components/schemas/ProviderPanelLinkSource"} override_state: {"$ref": "#/components/schemas/ProviderPanelLinkOverrideState"} config_url: description: The setup-file link, what a reset restores; absent when the setup file has none. type: string format: uri version: description: Revisions so far; send it back as expected_version. type: integer format: int32 minimum: 0 updated_by: type: string format: uuid updated_by_name: {type: string} updated_at: type: string format: date-time reason_code: {"$ref": "#/components/schemas/ProviderPanelLinkReason"} note: {type: string} AdminProviderPanelLinksResponse: type: object required: [links] properties: links: type: array items: {"$ref": "#/components/schemas/AdminProviderPanelLink"} AdminProviderPanelLinkResponse: type: object required: [link] properties: link: {"$ref": "#/components/schemas/AdminProviderPanelLink"} PutAdminProviderPanelLinkRequest: type: object required: [action, expected_version, reason_code] properties: action: {"$ref": "#/components/schemas/ProviderPanelLinkAction"} url: description: Required for set; must be absent otherwise. Absolute HTTP or HTTPS top-level navigation link, including explicit ports, without credentials, query parameters or a fragment. type: string maxLength: 2048 expected_version: type: integer format: int32 minimum: 0 reason_code: {"$ref": "#/components/schemas/ProviderPanelLinkReason"} note: type: string minLength: 1 maxLength: 400 description: Required when reason_code is other. AdminProviderPanelLinkErrorResponse: type: object required: [error, problem] properties: error: {"$ref": "#/components/schemas/APIError"} problem: {"$ref": "#/components/schemas/ProviderPanelLinkProblem"} AdminProviderPanelLinkRevision: type: object required: [version, action, reason_code, updated_by, updated_at] properties: version: {type: integer, format: int32, minimum: 1} action: {"$ref": "#/components/schemas/ProviderPanelLinkAction"} url: type: string format: uri reason_code: {"$ref": "#/components/schemas/ProviderPanelLinkReason"} note: {type: string} updated_by: {type: string, format: uuid} updated_by_name: {type: string} updated_at: {type: string, format: date-time} AdminProviderPanelLinkHistoryResponse: type: object required: [revisions] properties: revisions: type: array items: {"$ref": "#/components/schemas/AdminProviderPanelLinkRevision"} AdminPaymentProvider: type: object required: [code] properties: code: {"$ref": "#/components/schemas/PaymentDepositProviderCode"} panel_url: description: The payment provider's operator back-office, when configured. type: string format: uri ProviderTransferVerification: type: object description: How an operator verifies one load or cash-out in the provider's own panel. It is a procedure, never a verdict. required: [lookup_keys, match_fields] properties: lookup_keys: description: PlayGo identifiers to search the panel by, most specific first. type: array items: {"$ref": "#/components/schemas/ProviderTransferLookupKey"} match_fields: description: What to compare on the record once found. type: array items: {"$ref": "#/components/schemas/ProviderTransferMatchField"} ProviderTransferLookupKey: type: string enum: [external_order_id, player_account_ref, player_username] x-enum-varnames: [ProviderTransferLookupExternalOrderID, ProviderTransferLookupPlayerAccountRef, ProviderTransferLookupPlayerUsername] ProviderTransferMatchField: type: string enum: [direction, credits, cash_amount, time] x-enum-varnames: [ProviderTransferMatchDirection, ProviderTransferMatchCredits, ProviderTransferMatchCashAmount, ProviderTransferMatchTime] ProviderResponse: type: object required: - provider properties: provider: "$ref": "#/components/schemas/Provider" ProviderProbeType: type: string enum: - agent_balance - read - write - launch - create ProviderProbeLevel: type: string enum: - direct_adapter - full_system ProviderProbeClassification: type: string enum: - passed - failed_provider_business_rule - failed_provider_opaque_rejection - failed_transport - failed_auth_or_signature - failed_config_missing - unknown_timeout - unsupported - capability_disabled - drift_detected - restore_failed - canary_account_missing ProviderProbeRunClassification: type: string enum: - running - passed - failed_provider_business_rule - failed_provider_opaque_rejection - failed_transport - failed_auth_or_signature - failed_config_missing - unknown_timeout - unsupported - capability_disabled - drift_detected - restore_failed - canary_account_missing x-enum-varnames: - ProviderProbeRunClassificationRunning - ProviderProbeRunClassificationPassed - ProviderProbeRunClassificationFailedProviderBusinessRule - ProviderProbeRunClassificationFailedProviderOpaqueRejection - ProviderProbeRunClassificationFailedTransport - ProviderProbeRunClassificationFailedAuthOrSignature - ProviderProbeRunClassificationFailedConfigMissing - ProviderProbeRunClassificationUnknownTimeout - ProviderProbeRunClassificationUnsupported - ProviderProbeRunClassificationCapabilityDisabled - ProviderProbeRunClassificationDriftDetected - ProviderProbeRunClassificationRestoreFailed - ProviderProbeRunClassificationCanaryAccountMissing ProviderHealthState: type: string enum: - up - degraded - down - blocked - config_missing - drift_detected - restore_failed - unsupported - unknown ProviderHealthFreshnessState: type: string enum: - fresh - stale ProviderProbeRunState: type: string enum: - running - completed ProviderProbeAccountKind: type: string enum: - stable_read - stable_write - manual_create_artifact ProviderProbeAccountStatus: type: string enum: - active - quarantined - retired AdminProviderHealthStatus: type: object required: - provider_code - probe_type - probe_level - health_state - classification - latest_run_id - last_run_at - freshness_state - stale_after properties: provider_code: "$ref": "#/components/schemas/ProviderCode" probe_type: "$ref": "#/components/schemas/ProviderProbeType" probe_level: "$ref": "#/components/schemas/ProviderProbeLevel" health_state: "$ref": "#/components/schemas/ProviderHealthState" classification: "$ref": "#/components/schemas/ProviderProbeClassification" blocked_reason: type: string nullable: true latest_run_id: type: string format: uuid last_run_at: type: string format: date-time freshness_state: "$ref": "#/components/schemas/ProviderHealthFreshnessState" stale_after: type: string format: date-time description: >- For read-probe evidence, the freshness deadline is the configured provider read interval (default 72 hours) plus a five-minute grace period after last_run_at. acknowledged_at: type: string format: date-time nullable: true AdminProviderCanaryAccount: type: object required: - id - provider_code - account_kind - requested_username - provider_player_account_ref - provider_username - baseline_credits - probe_amount_credits - status properties: id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" account_kind: "$ref": "#/components/schemas/ProviderProbeAccountKind" requested_username: type: string provider_player_account_ref: type: string provider_username: type: string provider_player_id: type: string nullable: true baseline_credits: type: integer format: int64 probe_amount_credits: type: integer format: int64 status: "$ref": "#/components/schemas/ProviderProbeAccountStatus" quarantine_reason: type: string nullable: true notes: type: string nullable: true AdminProviderProbeStep: type: object required: - id - step_order - step_name - operation - classification - evidence - started_at properties: id: type: string format: uuid step_order: type: integer format: int32 step_name: type: string operation: type: string classification: "$ref": "#/components/schemas/ProviderProbeClassification" evidence: type: object additionalProperties: true error_message: type: string nullable: true started_at: type: string format: date-time completed_at: type: string format: date-time nullable: true AdminProviderProbeRun: type: object required: - id - provider_code - probe_type - probe_level - trigger_source - state - classification - started_at - steps properties: id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" probe_type: "$ref": "#/components/schemas/ProviderProbeType" probe_level: "$ref": "#/components/schemas/ProviderProbeLevel" trigger_source: type: string state: "$ref": "#/components/schemas/ProviderProbeRunState" classification: "$ref": "#/components/schemas/ProviderProbeRunClassification" summary: type: string nullable: true started_at: type: string format: date-time completed_at: type: string format: date-time nullable: true steps: type: array items: "$ref": "#/components/schemas/AdminProviderProbeStep" AdminProviderAgentBalance: type: object required: - credits - refill_below_credits - checked_at properties: credits: type: integer format: int64 refill_below_credits: type: integer format: int64 checked_at: type: string format: date-time AdminProviderHealth: type: object required: - provider_code - refill_below_credits - warn_if_no_refill_within_hours - last_refilled_at - statuses - canary_accounts - has_active_stable_read_canary - has_active_stable_write_canary - verify_items properties: provider_code: "$ref": "#/components/schemas/ProviderCode" panel_url: description: The provider's operator back-office, when configured. type: string format: uri refill_below_credits: type: integer format: int64 minimum: 1 maximum: 1000000000 warn_if_no_refill_within_hours: description: Warn when no refill is recorded within this many hours; null is off. type: integer format: int32 minimum: 1 maximum: 720 nullable: true last_refilled_at: description: When an admin last recorded a refill; null when none was recorded. type: string format: date-time nullable: true statuses: type: array items: "$ref": "#/components/schemas/AdminProviderHealthStatus" canary_accounts: type: array items: "$ref": "#/components/schemas/AdminProviderCanaryAccount" has_active_stable_read_canary: type: boolean has_active_stable_write_canary: type: boolean agent_balance: "$ref": "#/components/schemas/AdminProviderAgentBalance" verify_items: description: Unresolved historical health-probe transfers, independent of recent diagnostic history. Read-only verification; no recommended outcome or settlement action. type: array items: "$ref": "#/components/schemas/AdminProviderHealthVerifyItem" recent_runs: type: array items: "$ref": "#/components/schemas/AdminProviderProbeRun" AdminProviderHealthVerifyItem: type: object required: [transfer_id, run_id, user_id, provider_account_id, state, direction, provider_player_account_ref, external_order_id, provider_credits, created_at, verification_steps] properties: transfer_id: type: string format: uuid run_id: type: string format: uuid user_id: type: string format: uuid provider_account_id: type: string format: uuid probe_account_id: type: string format: uuid state: type: string direction: type: string provider_player_account_ref: type: string external_order_id: type: string provider_credits: type: integer format: int64 created_at: type: string format: date-time verification_steps: type: array items: type: string ProviderReadIntervalHours: type: integer format: int32 minimum: 1 maximum: 336 description: Automatic provider read interval in whole hours (default 72). AdminProviderReadSettings: type: object required: [provider_code, read_interval_hours] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} provider_code: "$ref": "#/components/schemas/ProviderCode" read_interval_hours: "$ref": "#/components/schemas/ProviderReadIntervalHours" AdminProviderReadSettingsRequest: type: object additionalProperties: false required: [expected_read_interval_hours, read_interval_hours, reason_code] properties: expected_read_interval_hours: "$ref": "#/components/schemas/ProviderReadIntervalHours" read_interval_hours: "$ref": "#/components/schemas/ProviderReadIntervalHours" reason_code: "$ref": "#/components/schemas/ProviderRefillSettingsChangeReason" note: type: string maxLength: 500 description: Required when reason_code is other. AdminProviderRefillSettingsRequest: type: object required: [expected_refill_below_credits, refill_below_credits, expected_warn_if_no_refill_within_hours, warn_if_no_refill_within_hours, reason_code] properties: expected_refill_below_credits: type: integer format: int64 minimum: 1 maximum: 1000000000 refill_below_credits: type: integer format: int64 minimum: 1 maximum: 1000000000 expected_warn_if_no_refill_within_hours: type: integer format: int32 minimum: 1 maximum: 720 nullable: true warn_if_no_refill_within_hours: type: integer format: int32 minimum: 1 maximum: 720 nullable: true reason_code: "$ref": "#/components/schemas/ProviderRefillSettingsChangeReason" note: type: string minLength: 1 maxLength: 500 description: Required when reason_code is other. ProviderRefillSettingsChangeReason: type: string enum: [operating_policy, correction, other] x-enum-varnames: - ProviderRefillSettingsChangeReasonOperatingPolicy - ProviderRefillSettingsChangeReasonCorrection - ProviderRefillSettingsChangeReasonOther AdminProviderRefillSettings: type: object required: [provider_code, refill_below_credits, warn_if_no_refill_within_hours, updated_by, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} provider_code: "$ref": "#/components/schemas/ProviderCode" refill_below_credits: type: integer format: int64 minimum: 1 maximum: 1000000000 warn_if_no_refill_within_hours: type: integer format: int32 minimum: 1 maximum: 720 nullable: true updated_by: type: string format: uuid updated_at: type: string format: date-time AdminProviderRefill: type: object required: [id, provider_code, recorded_by, recorded_at] properties: id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" recorded_by: type: string format: uuid recorded_at: type: string format: date-time AdminProviderHealthResponse: type: object required: - providers properties: providers: type: array items: "$ref": "#/components/schemas/AdminProviderHealth" AdminProviderHealthDetailResponse: type: object required: - provider properties: provider: "$ref": "#/components/schemas/AdminProviderHealth" AdminProviderProbeResultResponse: type: object required: - run_id - classification - health_state properties: run_id: type: string format: uuid classification: "$ref": "#/components/schemas/ProviderProbeClassification" health_state: "$ref": "#/components/schemas/ProviderHealthState" AdminProviderReadProbeRequest: type: object additionalProperties: false properties: force: type: boolean default: false description: Super admin only. Bypass the ten-minute successful-read cache. AdminProviderReadProbeResultResponse: allOf: - "$ref": "#/components/schemas/AdminProviderProbeResultResponse" - type: object required: [served_from_cache, last_run_at] properties: served_from_cache: type: boolean description: True when the persisted successful result was reused with zero provider calls and no new run. last_run_at: type: string format: date-time description: Completion timestamp of the returned run; a cache hit never advances it. AdminProviderLaunchProbeRequest: type: object properties: game_ref: type: string default: lobby ProviderBootstrapProbeAccountKind: type: string enum: - stable_read - stable_write AdminProviderBootstrapCanaryRequest: type: object required: - account_kind - confirm properties: account_kind: "$ref": "#/components/schemas/ProviderBootstrapProbeAccountKind" confirm: type: boolean AdminProviderCanaryAccountResponse: type: object required: - account properties: account: "$ref": "#/components/schemas/AdminProviderCanaryAccount" AdminProviderQuarantineCanaryRequest: type: object required: - reason - confirm properties: reason: type: string minLength: 1 confirm: type: boolean AdminProviderHealthAcknowledgeRequest: type: object required: - probe_type - probe_level properties: probe_type: "$ref": "#/components/schemas/ProviderProbeType" probe_level: "$ref": "#/components/schemas/ProviderProbeLevel" notes: type: string nullable: true DisabledReasonCode: type: string enum: - bonus_recovery_required - provider_account_disabled - provider_transfer_open - wallet_balance_zero - provider_credits_zero - cashout_no_cycle_loads - cashout_below_minimum - game_inactive - provider_unavailable - provider_account_creation_unavailable - provider_launch_unavailable - game_not_added - provider_account_provisioning - provider_account_creation_failed - provider_account_creation_unknown - support_conversation_resolved - support_conversation_open - support_no_messages - support_not_allowed - support_rate_limited - support_conversation_claimed - first_unload_review_open - provider_account_exists - provider_link_unavailable - credit_moves_disabled - admin_required AdminWalletTransferRequest: description: Entry request offered to authorized staff. Its presence is not admission to move money; the corresponding options/preflight request returns the actual typed refusal or preview. type: object required: [operation_id] properties: operation_id: type: string enum: [getAdminProviderAccountLoadOptions, postAdminProviderAccountUnloadPreflight] StaffWalletRefusalReason: type: string enum: - operational_owner_has_no_wallet - staff_wallet_actions_disabled - inactive_wallet_subject InteractionAction: type: object required: - enabled properties: enabled: type: boolean disabled_reason_code: nullable: true allOf: - "$ref": "#/components/schemas/DisabledReasonCode" disabled_reason: type: string nullable: true ResourceEffect: type: string enum: - wallet.summary - wallet.transactions - provider.accounts - provider-transfers.list - provider-transfers.detail - payment-deposits.list - payment-deposits.detail - payment-deposits.options - payment-methods.list - payment-withdrawals.list - payment-withdrawals.detail - games.catalog - support.conversation - admin.support.inbox - rewards.summary - rewards.history - rewards.marketplace - rewards.roulette - rewards.missions - referrals.status - referrals.rewards - player-notifications.list x-enum-varnames: - ResourceEffectWalletSummary - ResourceEffectWalletTransactions - ResourceEffectProviderAccounts - ResourceEffectProviderTransfersList - ResourceEffectProviderTransfersDetail - ResourceEffectPaymentDepositsList - ResourceEffectPaymentDepositsDetail - ResourceEffectPaymentDepositsOptions - ResourceEffectPaymentMethodsList - ResourceEffectPaymentWithdrawalsList - ResourceEffectPaymentWithdrawalsDetail - ResourceEffectGamesCatalog - ResourceEffectSupportConversationEffect - ResourceEffectAdminSupportInboxEffect - ResourceEffectRewardsSummary - ResourceEffectRewardsHistory - ResourceEffectRewardsMarketplace - ResourceEffectRewardsRoulette - ResourceEffectRewardsMissions - ResourceEffectReferralsStatus - ResourceEffectReferralsRewards - ResourceEffectPlayerNotificationsList PollHint: type: object required: - resource - resource_id - interval_ms properties: resource: type: string enum: - provider_transfer - payment_deposit - payment_withdrawal - games.catalog - support.conversation - admin.support.inbox resource_id: type: string format: uuid after_seq: type: integer format: int64 minimum: 1 nullable: true interval_ms: type: integer minimum: 1 description: Backend-owned polling cadence for this resource in milliseconds. Consumers decide whether they are actively interested in polling; they should not invent their own cadence. For support conversations, open conversations use the active/open cadence while resolved conversations use the slower closed cadence. transport: type: string enum: - short_poll - long_poll nullable: true description: Optional backend-owned transport hint for active consumers. timeout_ms: type: integer minimum: 1 nullable: true description: Optional informational maximum long-poll hold duration in milliseconds. GameCreditMoveSettings: type: object required: [enabled, version, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} enabled: {type: boolean} version: {type: integer, format: int64, minimum: 1} updated_by: {type: string, format: uuid, nullable: true} updated_at: {type: string, format: date-time} GameCreditMoveSettingsChange: type: object required: [version, previous_enabled, next_enabled, actor_id, reason_code, created_at] properties: version: {type: integer, format: int64} previous_enabled: {type: boolean} next_enabled: {type: boolean} actor_id: {type: string, format: uuid} reason_code: {type: string, enum: [operating_policy, correction, other]} note: {type: string, nullable: true} created_at: {type: string, format: date-time} GameCreditMoveSettingsResponse: type: object required: [settings, history, update_action, effects] properties: settings: "$ref": "#/components/schemas/GameCreditMoveSettings" history: type: array items: "$ref": "#/components/schemas/GameCreditMoveSettingsChange" update_action: "$ref": "#/components/schemas/InteractionAction" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" UpdateGameCreditMoveSettingsRequest: type: object required: [enabled, expected_version, reason_code] properties: enabled: {type: boolean} expected_version: {type: integer, format: int64, minimum: 1} reason_code: {type: string, enum: [operating_policy, correction, other]} note: {type: string, maxLength: 500} ProviderBalanceObservationResponse: type: object required: [provider_account_id, balance_credits, balance_observed_at] properties: provider_account_id: {type: string, format: uuid} balance_credits: {type: integer, format: int64, nullable: true, minimum: 0} balance_observed_at: {type: string, format: date-time, nullable: true, description: Timestamp of the stored observation, never presented as current without a successful refresh.} ProviderAccountActions: type: object description: Reconnect is enabled only for a blocked account on a game that can verify the current password. required: - load_provider_credits - unload_provider_credits - move_credits properties: reconnect: "$ref": "#/components/schemas/InteractionAction" move_credits: "$ref": "#/components/schemas/InteractionAction" load_provider_credits: "$ref": "#/components/schemas/InteractionAction" unload_provider_credits: "$ref": "#/components/schemas/InteractionAction" GameActions: type: object description: Reconnect is enabled only for a blocked account on a game that can verify the current password. required: - add - launch properties: reconnect: "$ref": "#/components/schemas/InteractionAction" add: "$ref": "#/components/schemas/InteractionAction" launch: "$ref": "#/components/schemas/InteractionAction" refresh_balance: "$ref": "#/components/schemas/InteractionAction" reset_password: "$ref": "#/components/schemas/InteractionAction" retry_setup: "$ref": "#/components/schemas/InteractionAction" copy_account_ref: "$ref": "#/components/schemas/InteractionAction" favorite: "$ref": "#/components/schemas/InteractionAction" add_existing: "$ref": "#/components/schemas/InteractionAction" AddExistingGameAccountForm: type: object description: Backend-owned form metadata for linking an existing provider account. Clients render exactly this; they never infer it from the provider or its family. required: - identifier_label - password - expected_slot properties: expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} identifier_label: description: Label for the account identifier input (e.g. "Username", "Account ID"). type: string password: type: string enum: [required] x-enum-varnames: [ExistingAccountPasswordRequired] description: Every offered existing-account link requires exact password capture. AddExistingPasswordRequirement: type: string description: Native verifier credential handling. required means native verification needs the password; optional means it can verify identity without it; not_accepted means the native protocol does not verify a supplied password. Existing-account linking and admin identity relink separately require password capture and encrypted storage on success for every adapter; this trait must not hide those password inputs. enum: - required - optional - not_accepted x-enum-varnames: - AddExistingPasswordRequired - AddExistingPasswordOptional - AddExistingPasswordNotAccepted ProviderBalanceReadState: type: object description: State of a real observation; pending credit observations never invent a balance. required: [stale, in_flight, pending] properties: stale: type: boolean in_flight: type: boolean pending: type: boolean ProviderAccount: type: object required: - id - provider_code - provider_player_account_ref - username - status - load_increment_cents - actions - created_at properties: freeplay_load_available_cents: {type: integer, format: int64, minimum: 0, description: "Server-calculated existing Free Play load availability, in whole provider units, for a source choice. No client eligibility or rounding calculation."} bonus_only_available_cents: {type: integer, format: int64, minimum: 0, description: "Server-calculated available whole-credit Bonus-only funding under current admission. Zero or absence does not admit a Bonus load."} account_issue_reason: {"$ref": "#/components/schemas/ProviderAccountIssueReason"} account_issue_message: {type: string, description: Server-owned player copy for the account issue} id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" provider_player_account_ref: type: string username: type: string status: type: string enum: - active - disabled balance_credits: description: API presentation value normalized from DB-owned numeric(22,4) provider balance. type: integer format: int64 nullable: true balance_read_state: "$ref": "#/components/schemas/ProviderBalanceReadState" balance_observed_at: type: string format: date-time nullable: true load_available_amount: description: Maximum currently eligible wallet funding that converts to whole credits for this account, computed by PostgreSQL under the active funding policy. This display choice is not a load approval; load preflight remains mandatory. Zero means no eligible whole-credit load is available. "$ref": "#/components/schemas/MoneyAmount" load_increment_cents: description: Smallest load amount in USD cents that converts to a whole provider credit. type: integer format: int64 minimum: 1 cashout: "$ref": "#/components/schemas/ProviderAccountCashout" actions: "$ref": "#/components/schemas/ProviderAccountActions" created_at: type: string format: date-time PayoutTier: type: object required: [minimum_load_cents] properties: minimum_load_cents: {type: integer, format: int64} base_cap_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991, nullable: true} load_multiplier: {type: integer, format: int64, nullable: true} PayoutPolicy: type: object required: [tiers, maximum_base_cap_cents, excess_percent, minimum_load_multiplier, revision, updated_at, freeplay_winnings_percent, freeplay_min_cash_threshold, block_withdrawable_loads, inapp_signup_freeplay_cents, signup_freeplay_cents, bonus_only_enabled, bonus_only_min_net_winnings_cents, bonus_only_max_payout_cents, bonus_only_winnings_percent, bonus_only_cycle_interval_days, bonus_only_principal_multiplier, deposit_bonus_load_share_enabled, deposit_bonus_load_share_bps] properties: bonus_only_activation_ready: {type: boolean, readOnly: true, description: "True only after the approved maintenance activation is installed. New-cycle enable controls must not be offered while false."} bonus_only_enabled: {type: boolean, x-go-type: "*bool", description: "Bonus-only cycle admission. Release A remains dormant OFF until maintenance activation is installed. Turning OFF blocks new cycles, not issued obligations."} bonus_only_min_net_winnings_cents: {type: integer, format: int64, x-go-type: "*int64", minimum: 100, maximum: 100000, multipleOf: 100, description: "Whole-dollar minimum net winnings, default 5000 cents. Must be no greater than maximum payout. Frozen for each cycle."} bonus_only_max_payout_cents: {type: integer, format: int64, x-go-type: "*int64", minimum: 100, maximum: 100000, multipleOf: 100, description: "Whole-dollar cumulative payout cap per cycle, default 10000 cents. Settings changes affect only new cycles."} bonus_only_winnings_percent: {type: integer, format: int64, x-go-type: "*int64", minimum: 1, maximum: 10000, description: "Net winnings conversion in basis points, default 10000 (100 percent). Frozen per cycle."} bonus_only_cycle_interval_days: {type: integer, format: int64, x-go-type: "*int64", minimum: 1, maximum: 365, description: "Minimum days between successful Bonus-only cycle starts, default 30. Failed reservations do not consume a successful start."} bonus_only_principal_multiplier: {type: integer, format: int64, x-go-type: "*int64", minimum: 1, maximum: 100, description: "Bonus-only payout cap as a multiple of the Bonus principal played: payout never exceeds min(bonus_only_max_payout_cents, principal x multiplier). Default 5. Open cycles keep their recorded multiplier."} deposit_bonus_load_share_enabled: {type: boolean, x-go-type: "*bool", description: "Bonus share per load (ADR 0066). When true, Deposit bonus pays at most deposit_bonus_load_share_bps of each mixed game load. Default false."} deposit_bonus_load_share_bps: {type: integer, format: int64, x-go-type: "*int64", minimum: 100, maximum: 9900, multipleOf: 100, description: "Largest Bonus share of each game load in basis points, a whole percent from 1 to 99. Default 5000 (50 percent)."} readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} inapp_signup_freeplay_cents: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 9007199254740991, description: "Signup free play from src=inapp_open. Zero disables it; an absent stored amount defaults to 500 cents ($5) on every environment. Full policy replacement requires this value."} signup_freeplay_cents: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 9007199254740991, description: "Free play for every new verified signup (#822), once per account with the same per-device and per-email guards as the Messenger link offer. Zero or absent is off. The Messenger link amount applies instead when that link qualifies."} freeplay_winnings_percent: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 10000, description: Integer basis points of freeplay-cycle winnings. Default 2000 equals 20 percent; audited in policy revisions.} block_withdrawable_loads: {type: boolean, x-go-type: "*bool", description: Audited load policy. True blocks Cash out Amount from funding game loads; false funds after Playable Cash. Seeded true; explicit nonnull value required on policy replacement.} freeplay_min_cash_threshold: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 9007199254740991, description: Always-on Playable Cash threshold for Freeplay eligibility. At or above it no Freeplay; below it eligible Freeplay funds the remainder after cash and any policy-permitted withdrawable funding. Never null.} tiers: type: array minItems: 1 maxItems: 20 items: {"$ref": "#/components/schemas/PayoutTier"} maximum_base_cap_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} excess_percent: {type: integer, format: int64, minimum: 10, maximum: 10} revision: {type: integer, format: int64} updated_at: {type: string, format: date-time} minimum_load_multiplier: {type: integer, format: int64, minimum: 1, maximum: 1000, description: Minimum redeemable game balance as a multiple of cumulative cycle load.} BonusOnlyCashoutPreviewRequest: type: object additionalProperties: false required: [cycle_id, expected_cycle_version] properties: cycle_id: {type: string, format: uuid} expected_cycle_version: {type: integer, format: int64, minimum: 1} BonusOnlyCloseLossResponse: type: object required: [bonus_only_cycle, effects] properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle"} effects: {type: array, items: {$ref: "#/components/schemas/ResourceEffect"}} BonusOnlyTerminalPreview: type: object required: [bonus_only_cycle] properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle"} cashout_confirm_token: {type: string, format: uuid, description: "Issued only for an eligible fresh quote. Terminal cash-out must match its exact balance, cycle, principal, policy and forfeiture terms."} BonusOnlyCloseLossRequest: type: object additionalProperties: false required: [cycle_id, expected_cycle_version] properties: cycle_id: {type: string, format: uuid} expected_cycle_version: {type: integer, format: int64, minimum: 1} BonusOnlyCycleState: type: string enum: [reserved, active, settling, review, unknown, closed, failed] BonusOnlyReason: type: string enum: [ok, pending, balance_unavailable, active_elsewhere, cooldown, paid_funds_usable, existing_game_balance, bonus_below_increment, bonus_only_disabled, below_minimum, partial_move_not_allowed, mixed_destination] BonusOnlyCycle: type: object required: [state, principal_cents, net_winnings_cents, min_net_winnings_cents, max_payout_cents, winnings_percent, policy_revision, remaining_payout_cents, payable_cents, forfeit_cents, remaining_net_winnings_cents, balance_known, eligible, reason] properties: admin_context: {$ref: "#/components/schemas/BonusOnlyAdminContext", description: "Private game and original lot context. Populated only by the authorized admin player detail read; omitted from player previews and receipts."} version: {type: integer, format: int64, minimum: 1, description: Cycle CAS version. New-load previews without a durable cycle may omit it.} id: {type: string, format: uuid, description: "Present only for a durably accepted cycle. A new-load preview has no cycle ID."} state: {$ref: "#/components/schemas/BonusOnlyCycleState"} principal_cents: {type: integer, format: int64, minimum: 0} net_winnings_cents: {type: integer, format: int64, minimum: 0} min_net_winnings_cents: {type: integer, format: int64, minimum: 100, maximum: 100000} max_payout_cents: {type: integer, format: int64, minimum: 100, maximum: 100000} winnings_percent: {type: integer, format: int64, minimum: 1, maximum: 10000} policy_revision: {type: integer, format: int64} remaining_payout_cents: {type: integer, format: int64, minimum: 0} payable_cents: {type: integer, format: int64, minimum: 0} forfeit_cents: {type: integer, format: int64, minimum: 0} remaining_net_winnings_cents: {type: integer, format: int64, minimum: 0, description: Server-calculated additional net winnings required under the frozen minimum and percentage.} can_close_loss: {type: boolean, description: "Server-admitted explicit loss closure: fresh verified zero, funded active cycle and no unresolved operation. Net winnings of zero alone do not permit closure."} balance_known: {type: boolean, description: "Whether the projection has a usable game balance observation. When false, net/payable progress values must not be shown as observed money."} eligible: {type: boolean} reason: {$ref: "#/components/schemas/BonusOnlyReason"} next_start_at: {type: string, format: date-time} observed_at: {type: string, format: date-time, description: Game balance observation used for this projection. Absence does not mean a fresh balance.} BonusOnlyAdminContext: type: object required: [provider_account_id, provider_code, game_name, username, sources, close_loss_action] properties: close_loss_action: {$ref: "#/components/schemas/InteractionAction"} provider_account_id: {type: string, format: uuid} provider_code: {$ref: "#/components/schemas/ProviderCode"} game_id: {type: string, description: Configured game catalog identity when available.} game_name: {type: string} username: {type: string} sources: {type: array, items: {$ref: "#/components/schemas/BonusOnlyLotOrigin"}} BonusOnlyLotOrigin: type: object required: [grant_id, reward_event_id, grant_ledger_transaction_id, load_transfer_id, origin, origin_label, granted_cents, allocated_cents, granted_at, transfer_state, refunded, revoked] properties: grant_id: {type: string, format: uuid} payment_id: {type: string, format: uuid, description: Present for Bonus originating from a deposit.} reward_event_id: {type: string, format: uuid} grant_ledger_transaction_id: {type: string, format: uuid} load_transfer_id: {type: string, format: uuid} origin: {$ref: "#/components/schemas/RewardEventKind"} origin_label: {type: string, description: Human display name of the recorded award source.} granted_cents: {type: integer, format: int64, minimum: 1} allocated_cents: {type: integer, format: int64, minimum: 1, description: Original Bonus allocation excluding dust. Refunded or pending rows remain visible and are labelled by their flags and transfer state.} granted_at: {type: string, format: date-time} transfer_state: {$ref: "#/components/schemas/ProviderTransferState"} refunded: {type: boolean} revoked: {type: boolean} PayoutPolicyValidationError: type: object required: [error, fields] properties: error: {"$ref": "#/components/schemas/APIError"} fields: {type: object, additionalProperties: {type: string}, description: "Plain corrective messages keyed by payout-policy input field."} PayoutPolicyChangeReason: type: string description: Why the payout policy changed. enum: [operating_policy, correction, other] x-enum-varnames: - PayoutPolicyChangeReasonOperatingPolicy - PayoutPolicyChangeReasonCorrection - PayoutPolicyChangeReasonOther UpdatePayoutPolicyRequest: type: object required: [tiers, maximum_base_cap_cents, excess_percent, minimum_load_multiplier, expected_revision, reason_code, freeplay_winnings_percent, freeplay_min_cash_threshold, block_withdrawable_loads, inapp_signup_freeplay_cents] properties: bonus_only_enabled: {type: boolean, description: "Bonus-only cycle admission. Release A remains dormant OFF until maintenance activation is installed. Turning OFF blocks new cycles, not issued obligations."} bonus_only_min_net_winnings_cents: {type: integer, format: int64, minimum: 100, maximum: 100000, multipleOf: 100, description: "Whole-dollar minimum net winnings, default 5000 cents. Must be no greater than maximum payout. Frozen for each cycle."} bonus_only_max_payout_cents: {type: integer, format: int64, minimum: 100, maximum: 100000, multipleOf: 100, description: "Whole-dollar cumulative payout cap per cycle, default 10000 cents. Settings changes affect only new cycles."} bonus_only_winnings_percent: {type: integer, format: int64, minimum: 1, maximum: 10000, description: "Net winnings conversion in basis points, default 10000 (100 percent). Frozen per cycle."} bonus_only_cycle_interval_days: {type: integer, format: int64, minimum: 1, maximum: 365, description: "Minimum days between successful Bonus-only cycle starts, default 30. Failed reservations do not consume a successful start."} bonus_only_principal_multiplier: {type: integer, format: int64, minimum: 1, maximum: 100, description: "Bonus-only payout cap as a multiple of the Bonus principal played: payout never exceeds min(bonus_only_max_payout_cents, principal x multiplier). Default 5. Open cycles keep their recorded multiplier."} deposit_bonus_load_share_enabled: {type: boolean, description: "Bonus share per load (ADR 0066). Omitted keeps the stored value."} deposit_bonus_load_share_bps: {type: integer, format: int64, minimum: 100, maximum: 9900, multipleOf: 100, description: "Largest Bonus share of each game load in basis points, a whole percent from 1 to 99. Omitted keeps the stored value."} inapp_signup_freeplay_cents: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 9007199254740991, description: "Signup free play from src=inapp_open. Zero disables it; an absent stored amount defaults to 500 cents ($5) on every environment. Full policy replacement requires this value."} signup_freeplay_cents: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991, description: "Free play for every new verified signup (#822), once per account with the same per-device and per-email guards as the Messenger link offer. Zero or absent is off. The Messenger link amount applies instead when that link qualifies. Omitted keeps the stored amount."} freeplay_winnings_percent: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 10000, description: Integer basis points of freeplay-cycle winnings. Default 2000 equals 20 percent; audited in policy revisions.} block_withdrawable_loads: {type: boolean, x-go-type: "*bool", description: Audited load policy. True blocks Cash out Amount from funding game loads; false funds after Playable Cash. Seeded true; explicit nonnull value required on policy replacement.} freeplay_min_cash_threshold: {type: integer, format: int64, x-go-type: "*int64", minimum: 0, maximum: 9007199254740991, description: Always-on Playable Cash threshold for Freeplay eligibility. At or above it no Freeplay; below it eligible Freeplay funds the remainder after cash and any policy-permitted withdrawable funding. Never null.} tiers: type: array minItems: 1 maxItems: 20 items: {"$ref": "#/components/schemas/PayoutTier"} maximum_base_cap_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} excess_percent: {type: integer, format: int64, minimum: 10, maximum: 10} expected_revision: {type: integer, format: int64} reason_code: "$ref": "#/components/schemas/PayoutPolicyChangeReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. minimum_load_multiplier: {type: integer, format: int64, minimum: 1, maximum: 1000} PayoutSystemQuote: type: object required: [mode, accepted_credits_cents, policy_revision, cycle_load_cents, base_cap_cents, payout_cash_cents, forfeit_cash_cents, excess_percent, excess_payout_cents, minimum_cashout_cents, eligible] properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only source terms and server-calculated cash-out progress.} mode: {"$ref": "#/components/schemas/CashoutAcceptanceMode"} accepted_credits_cents: {type: integer, format: int64, minimum: 0, description: Whole USD cents accepted from existing credits outside the current recorded-load policy. Frozen for an issued audit; zero in normal mode.} freeplay_winnings_percent: {type: integer, format: int64, nullable: true} actual_payout_cents: {type: integer, format: int64} actual_forfeit_cents: {type: integer, format: int64} freeplay_principal_cents: {type: integer, format: int64} policy_revision: {type: integer, format: int64} cycle_deposit_bonus_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus loaded in this cycle; excluded from redemption minimum and maximum.} cycle_cash_cents: {type: integer, format: int64, minimum: 0, description: Playable Cash loaded this cycle.} cycle_withdrawable_cents: {type: integer, format: int64, minimum: 0, description: Cash out Amount loaded this cycle.} cycle_freeplay_cents: {type: integer, format: int64, minimum: 0, description: Free play and campaign bonus loaded this cycle.} cycle_bonus_only_principal_cents: {type: integer, format: int64, minimum: 0, description: Bonus-only principal loaded this cycle; separate from matched Deposit bonus.} cycle_deposit_bonus_loaded_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus in completed loads this cycle; excludes Bonus-only principal and does not net credit moves.} cycle_total_cents: {type: integer, format: int64, minimum: 0, description: Total completed game loads this cycle, including every funding source.} cycle_load_cents: {type: integer, format: int64} base_cap_cents: {type: integer, format: int64} payout_cash_cents: {type: integer, format: int64} forfeit_cash_cents: {type: integer, format: int64} excess_percent: {type: integer, format: int64} excess_payout_cents: {type: integer, format: int64} eligible: {type: boolean} minimum_cashout_cents: {type: integer, format: int64, minimum: 0, description: Minimum redeemable post-link game value in USD cents; existing linked credits do not count toward this minimum.} CashoutPreviewRequest: type: object properties: approved_payout_cents: {type: integer, format: int64} CashoutPreview: type: object required: [provider_account_id, balance_credits, debit_credits, debit_cash_cents, system_quote, preview_token, approved_payout_cents, difference_cents, forfeit_cents] properties: wallet_review: {type: array, items: {"$ref": "#/components/schemas/WalletSourceReview"}} provider_account_id: {type: string, format: uuid} balance_credits: {type: integer, format: int64, minimum: 0} debit_credits: {type: integer, format: int64, minimum: 0} debit_cash_cents: {type: integer, format: int64} system_quote: {"$ref": "#/components/schemas/PayoutSystemQuote"} preview_token: {type: string, format: uuid} approved_payout_cents: {type: integer, format: int64} difference_cents: {type: integer, format: int64} forfeit_cents: {type: integer, format: int64} CashoutOverrideRequest: type: object required: [preview_token, expected_balance_credits, approved_payout_cents, reason] properties: preview_token: {type: string, format: uuid} expected_balance_credits: {type: integer, format: int64, minimum: 0} approved_payout_cents: {type: integer, format: int64} reason: {type: string, minLength: 3, maxLength: 500} ProviderAccountCashout: type: object required: [mode, accepted_credits_cents, eligible, payout_cash, forfeit_cash, policy_revision, cycle_load_cents, base_cap_cents, excess_percent, excess_payout_cents, minimum_cashout_cents, cycle_kind, action] properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only terms and server-computed progress from the shown balance observation.} mode: {"$ref": "#/components/schemas/CashoutAcceptanceMode"} accepted_credits_cents: {type: integer, format: int64, minimum: 0, description: Whole USD cents accepted from existing credits outside the current recorded-load policy. Frozen for an issued audit; zero in normal mode.} freeplay_winnings_percent: {type: integer, format: int64, nullable: true} actual_payout_cents: {type: integer, format: int64} actual_forfeit_cents: {type: integer, format: int64} freeplay_principal_cents: {type: integer, format: int64} eligible: {type: boolean} payout_cash: {"$ref": "#/components/schemas/MoneyAmount"} forfeit_cash: {"$ref": "#/components/schemas/MoneyAmount"} policy_revision: {type: integer, format: int64} cycle_deposit_bonus_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus loaded in this cycle; excluded from redemption minimum and maximum.} cycle_cash_cents: {type: integer, format: int64, minimum: 0, description: Playable Cash loaded this cycle.} cycle_withdrawable_cents: {type: integer, format: int64, minimum: 0, description: Cash out Amount loaded this cycle.} cycle_freeplay_cents: {type: integer, format: int64, minimum: 0, description: Free play and campaign bonus loaded this cycle.} cycle_bonus_only_principal_cents: {type: integer, format: int64, minimum: 0, description: Bonus-only principal loaded this cycle; separate from matched Deposit bonus.} cycle_deposit_bonus_loaded_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus in completed loads this cycle; excludes Bonus-only principal and does not net credit moves.} cycle_total_cents: {type: integer, format: int64, minimum: 0, description: Total completed game loads this cycle, including every funding source.} cycle_load_cents: {type: integer, format: int64} base_cap_cents: {type: integer, format: int64} excess_percent: {type: integer, format: int64} excess_payout_cents: {type: integer, format: int64} cycle_kind: {"$ref": "#/components/schemas/ProviderAccountCycleKind"} minimum_cashout_cents: {type: integer, format: int64, minimum: 0, description: Minimum redeemable post-link game value in USD cents; existing linked credits do not count toward this minimum.} action: {"$ref": "#/components/schemas/ProviderAccountCashoutAction"} review: nullable: true allOf: - "$ref": "#/components/schemas/PlayerFirstUnloadReview" ProviderAccountCycleKind: type: string enum: - normal x-enum-varnames: - ProviderAccountCycleKindNormal ProviderAccountCashoutAction: type: string description: Backend-owned cashout affordance. Linked accounts use cash_out; review_pending identifies historical open first-unload reviews. enum: - cash_out - review_pending - none x-enum-varnames: - CashoutActionCashOut - CashoutActionReviewPending - CashoutActionNone FirstUnloadReviewState: type: string enum: - pending - approving - settling - reconcile_required - settled - rejected - canceled x-enum-varnames: - FirstUnloadReviewStatePending - FirstUnloadReviewStateApproving - FirstUnloadReviewStateSettling - FirstUnloadReviewStateReconcileRequired - FirstUnloadReviewStateSettled - FirstUnloadReviewStateRejected - FirstUnloadReviewStateCanceled PlayerFirstUnloadReview: type: object required: - id - provider_account_id - state - reviewed_balance_credits - requested_at - actions properties: id: type: string format: uuid provider_account_id: type: string format: uuid state: "$ref": "#/components/schemas/FirstUnloadReviewState" reviewed_balance_credits: type: integer format: int64 requested_at: type: string format: date-time actions: type: object required: - cancel properties: cancel: "$ref": "#/components/schemas/InteractionAction" FirstUnloadReviewCommandResponse: type: object required: - review - effects properties: review: "$ref": "#/components/schemas/PlayerFirstUnloadReview" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" replayed: type: boolean default: false AddExistingGameAccountRequest: type: object additionalProperties: false required: - account_identifier - password - expected_slot properties: expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} account_identifier: description: The player's existing username or account id at the game provider. type: string minLength: 1 maxLength: 255 password: description: The exact existing account password. Required for every supported new link; saved privately. A roster lookup does not verify it. Never returned or logged. type: string minLength: 1 maxLength: 255 ProviderAccountImportReason: type: string enum: - account_already_linked - provider_account_exists - provisioning_in_progress - link_unavailable - verification_failed - verification_unavailable - credential_required - first_unload_review_open - first_unload_review_not_required - rereview_required - assignment_not_confirmed - approved_payout_out_of_range - fresh_balance_unavailable - review_not_pending - account_has_open_work - account_not_unlinkable - invalid_request - command_in_progress - idempotency_conflict - review_not_reconcilable - debit_already_confirmed - zero_balance_unverified - maker_checker_conflict x-enum-varnames: - ImportReasonAccountAlreadyLinked - ImportReasonProviderAccountExists - ImportReasonProvisioningInProgress - ImportReasonLinkUnavailable - ImportReasonVerificationFailed - ImportReasonVerificationUnavailable - ImportReasonCredentialRequired - ImportReasonFirstUnloadReviewOpen - ImportReasonFirstUnloadReviewNotRequired - ImportReasonRereviewRequired - ImportReasonAssignmentNotConfirmed - ImportReasonApprovedPayoutOutOfRange - ImportReasonFreshBalanceUnavailable - ImportReasonReviewNotPending - ImportReasonAccountHasOpenWork - ImportReasonAccountNotUnlinkable - ImportReasonInvalidRequest - ImportReasonCommandInProgress - ImportReasonIdempotencyConflict - ImportReasonReviewNotReconcilable - ImportReasonDebitAlreadyConfirmed - ImportReasonZeroBalanceUnverified - ImportReasonMakerCheckerConflict ProviderAccountImportErrorResponse: type: object required: - error - reason properties: error: "$ref": "#/components/schemas/APIError" reason: "$ref": "#/components/schemas/ProviderAccountImportReason" review: description: Present with rereview_required; the refreshed snapshot the admin must review. nullable: true allOf: - "$ref": "#/components/schemas/AdminFirstUnloadReviewSummary" AdminProviderAccountStatus: type: string enum: - linking - active - disabled - link_failed - unlinked x-enum-varnames: - AdminProviderAccountStatusLinking - AdminProviderAccountStatusActive - AdminProviderAccountStatusDisabled - AdminProviderAccountStatusLinkFailed - AdminProviderAccountStatusUnlinked AdminProviderAccountOrigin: type: string enum: - provisioned - linked_by_player - linked_by_admin x-enum-varnames: - AdminProviderAccountOriginProvisioned - AdminProviderAccountOriginLinkedByPlayer - AdminProviderAccountOriginLinkedByAdmin AdminProviderAccountHistoryItem: type: object required: - id - user_id - provider_code - provider_player_account_ref - username - status - origin - cycle_kind - ownership_confirmed - created_at - actions - management_revision - credential - link_failure_code - link_failed_at - active_successor_id - retry_of_account_id - retry_attempt_ids properties: management_revision: {type: integer, format: int64, minimum: 1, nullable: true} credential: {"$ref": "#/components/schemas/AccountCredentialSummary"} link_failure_code: {type: string, nullable: true} link_failed_at: {type: string, format: date-time, nullable: true} active_successor_id: {type: string, format: uuid, nullable: true} retry_of_account_id: {type: string, format: uuid, nullable: true} retry_attempt_ids: {type: array, items: {type: string, format: uuid}} actions: type: object required: - unlink properties: load: "$ref": "#/components/schemas/AdminWalletTransferRequest" unload: "$ref": "#/components/schemas/AdminWalletTransferRequest" unlink: "$ref": "#/components/schemas/InteractionAction" id: type: string format: uuid user_id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" provider_player_account_ref: type: string username: type: string status: "$ref": "#/components/schemas/AdminProviderAccountStatus" origin: "$ref": "#/components/schemas/AdminProviderAccountOrigin" balance_credits: type: integer format: int64 nullable: true balance_observed_at: type: string format: date-time nullable: true opening_balance_credits: description: Balance observed when the existing account was linked (audit only; never booked). type: integer format: int64 nullable: true linked_at: type: string format: date-time nullable: true cycle_kind: "$ref": "#/components/schemas/ProviderAccountCycleKind" ownership_confirmed: description: True for PlayGo-provisioned accounts or verified linked assignments accepted under ADR 0027. No separate first-unload admin review is required; this records acceptance of the assignment, not an independent ownership investigation. type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time PlayerAliasKind: type: string enum: [whatsapp, messenger, imessage, telegram, other] x-enum-varnames: - PlayerAliasKindWhatsApp - PlayerAliasKindMessenger - PlayerAliasKindIMessage - PlayerAliasKindTelegram - PlayerAliasKindOther PlayerAlias: type: object required: [id, user_id, kind, value, created_by, created_at] properties: id: {type: string, format: uuid} user_id: {type: string, format: uuid} kind: {"$ref": "#/components/schemas/PlayerAliasKind"} value: {type: string} created_by: {type: string, format: uuid} created_at: {type: string, format: date-time} PlayerAliasesResponse: type: object required: [aliases] properties: aliases: type: array items: {"$ref": "#/components/schemas/PlayerAlias"} CreatePlayerAliasRequest: type: object additionalProperties: false required: [kind, value] properties: kind: {"$ref": "#/components/schemas/PlayerAliasKind"} value: type: string minLength: 1 maxLength: 80 description: Trimmed before storage; 1 to 80 characters after trimming. AdminSearchMatchField: type: string enum: [name, email, alias, game_username, payout_tag, payment_reference] x-enum-varnames: - AdminSearchMatchFieldName - AdminSearchMatchFieldEmail - AdminSearchMatchFieldAlias - AdminSearchMatchFieldGameUsername - AdminSearchMatchFieldPayoutTag - AdminSearchMatchFieldPaymentReference AdminSearchMatch: type: object required: [field, label, value] properties: field: {"$ref": "#/components/schemas/AdminSearchMatchField"} label: type: string description: Operator-facing name of the matched field, e.g. "WhatsApp" for an alias. value: type: string description: The matched value. Payout tags are always masked. AdminSearchPlayer: type: object required: [id, display_name, email, status, role, last_active_at] properties: is_tester: {type: boolean, description: Backend tester marker.} id: {type: string, format: uuid} display_name: {type: string} email: {type: string} status: {"$ref": "#/components/schemas/UserStatus"} role: {"$ref": "#/components/schemas/UserRole"} last_active_at: {type: string, format: date-time} AdminSearchResult: type: object required: [player, matched] properties: player: {"$ref": "#/components/schemas/AdminSearchPlayer"} matched: {"$ref": "#/components/schemas/AdminSearchMatch"} AdminSearchResponse: type: object required: [results] properties: results: type: array items: {"$ref": "#/components/schemas/AdminSearchResult"} AdminStorySource: type: string enum: [signup, deposit, deposit_event, offapp, withdrawal, withdrawal_event, transfer, transfer_event, credit_move, account_link, first_cashout, support_message, support_event, reward, admin_adjustment, admin_grant, moderation, risk_decision, case_decision, password_reset] x-enum-varnames: - AdminStorySourceSignup - AdminStorySourceDeposit - AdminStorySourceDepositEvent - AdminStorySourceOffapp - AdminStorySourceWithdrawal - AdminStorySourceWithdrawalEvent - AdminStorySourceTransfer - AdminStorySourceTransferEvent - AdminStorySourceCreditMove - AdminStorySourceAccountLink - AdminStorySourceFirstCashout - AdminStorySourceSupportMessage - AdminStorySourceSupportEvent - AdminStorySourceReward - AdminStorySourceAdminAdjustment - AdminStorySourceAdminGrant - AdminStorySourceModeration - AdminStorySourceRiskDecision - AdminStorySourceCaseDecision - AdminStorySourcePasswordReset AdminStoryCategory: type: string enum: [money, game, chat, rewards, admin, account] x-enum-varnames: - AdminStoryCategoryMoney - AdminStoryCategoryGame - AdminStoryCategoryChat - AdminStoryCategoryRewards - AdminStoryCategoryAdmin - AdminStoryCategoryAccount AdminStoryDirection: type: string enum: [in, out, neutral] x-enum-varnames: - AdminStoryDirectionIn - AdminStoryDirectionOut - AdminStoryDirectionNeutral AdminStoryBucket: type: string enum: [cash, withdrawable, freeplay, credits, forfeit, cashout_review_holding] x-enum-varnames: - AdminStoryBucketCash - AdminStoryBucketWithdrawable - AdminStoryBucketFreeplay - AdminStoryBucketCredits - AdminStoryBucketForfeit - AdminStoryBucketCashoutReviewHolding AdminStoryAmount: type: object description: The record's amount in integer cents. `direction` is what the record does to the player's money (a deposit is `in` even before it settles); whether it took effect is told by its state events and by `open`. `credits` is the cash value of Provider Credits. `forfeit` is house-retained cash-out value, shown with neutral direction. `cashout_review_holding` is held value awaiting review, never spendable. required: [cents, direction, bucket] properties: cents: {type: integer, format: int64, minimum: 0} direction: {"$ref": "#/components/schemas/AdminStoryDirection"} bucket: {"$ref": "#/components/schemas/AdminStoryBucket"} AdminStoryBalanceChange: type: object description: An immutable recorded net balance change. USD values are signed integer cents; counts are signed whole units. No balance or policy is inferred. required: [value, unit, bucket] properties: value: {type: integer, format: int64} unit: {type: string, enum: [usd_cents, count]} bucket: {type: string, enum: [cash, withdrawable, deposit_bonus, freeplay, xp, diamonds, spin_tokens]} AdminStoryActorKind: type: string enum: [player, admin, system, provider] x-enum-varnames: - AdminStoryActorKindPlayer - AdminStoryActorKindAdmin - AdminStoryActorKindSystem - AdminStoryActorKindProvider AdminStoryActor: type: object required: [kind, label] properties: kind: {"$ref": "#/components/schemas/AdminStoryActorKind"} id: {type: string, format: uuid, description: The acting user; absent for system and provider actors.} label: {type: string} AdminStoryProvider: type: object description: The game or payment provider. For off-app deposits it is the off-app payment method. required: [code, label] properties: code: {type: string} label: {type: string} AdminStoryRefKind: type: string enum: [player, deposit, withdrawal, transfer, credit_move, provider_account, first_cashout, support_conversation, support_message, reward_event, admin_adjustment, risk_review] x-enum-varnames: - AdminStoryRefKindPlayer - AdminStoryRefKindDeposit - AdminStoryRefKindWithdrawal - AdminStoryRefKindTransfer - AdminStoryRefKindCreditMove - AdminStoryRefKindProviderAccount - AdminStoryRefKindFirstCashout - AdminStoryRefKindSupportConversation - AdminStoryRefKindSupportMessage - AdminStoryRefKindRewardEvent - AdminStoryRefKindAdminAdjustment - AdminStoryRefKindRiskReview AdminStoryRef: type: object description: A record the row drills down to. required: [kind, id] properties: kind: {"$ref": "#/components/schemas/AdminStoryRefKind"} id: {type: string, format: uuid} AdminStorySeverity: type: string enum: [none, info, warn, critical] x-enum-varnames: - AdminStorySeverityNone - AdminStorySeverityInfo - AdminStorySeverityWarn - AdminStorySeverityCritical AdminStoryItem: type: object required: [id, source, occurred_at, category, kind, actor, refs, severity, cashout_breakdown] properties: cashout_breakdown: nullable: true allOf: - "$ref": "#/components/schemas/CashoutBreakdown" reward_calculation: "$ref": "#/components/schemas/AdminStoryRewardCalculation" id: {type: string, format: uuid, description: The id of the source row; unique per source.} source: {"$ref": "#/components/schemas/AdminStorySource"} occurred_at: {type: string, format: date-time} category: {"$ref": "#/components/schemas/AdminStoryCategory"} kind: type: string description: Stable code `.`, for example `deposit.checkout_created` or `transfer_event.unknown_requires_reconcile`. Record rows (deposit, offapp, withdrawal, transfer, credit_move) carry the record's state when the page is read; the frontend owns the copy. amount: {"$ref": "#/components/schemas/AdminStoryAmount"} balance_changes: type: array maxItems: 5 description: Recorded net changes for reward and grant rows, posted receipt amounts for successful payment-credit events, or the wallet buckets a settled, unrefunded game load drew from (Playable Cash, Cash out Amount, Deposit bonus including consumed dust, Free play). An empty array means the recorded event had no net balance change. Absent means this read has no recorded reward breakdown; use amount when available and never infer a missing historical value. Existing amount describes the record's intended value and direction, not proof of settlement. items: {"$ref": "#/components/schemas/AdminStoryBalanceChange"} actor: {"$ref": "#/components/schemas/AdminStoryActor"} provider: {"$ref": "#/components/schemas/AdminStoryProvider"} message: type: string maxLength: 200 description: Provider message, reason or note, whitespace collapsed and cut to 200 characters. refs: type: array items: {"$ref": "#/components/schemas/AdminStoryRef"} severity: {"$ref": "#/components/schemas/AdminStorySeverity"} AdminStoryRewardCalculation: type: object description: How a deposit reward, mission claim or referral milestone worked out its amount, exactly as recorded when it was granted (Olin 120921). Present only on reward rows of those kinds. Every amount is the value computed at the grant; never recompute it. A field is absent when its step did not apply or the grant predates recording it. properties: mission_id: {"$ref": "#/components/schemas/RewardMissionId"} rules_version: {type: integer, format: int64, description: The bonus rule settings version that paid.} scheme_id: {type: string, format: uuid, description: The bonus scheme whose rule paid; absent means the base rules.} deposit_cents: {type: integer, format: int64, description: The deposit a deposit reward was computed from.} mission: {"$ref": "#/components/schemas/AdminStoryMissionCalculation"} next_deposit_bonus: {"$ref": "#/components/schemas/AdminStoryNextDepositBonusCalculation"} campaign: {"$ref": "#/components/schemas/AdminStoryCampaignCalculation"} every_deposit: {"$ref": "#/components/schemas/AdminStoryEveryDepositCalculation"} every_deposit_reduction: {"$ref": "#/components/schemas/AdminStoryEveryDepositReduction"} daily_ceiling_reduction: {"$ref": "#/components/schemas/AdminStoryDailyCeilingReduction"} AdminStoryEveryDepositReduction: type: object description: A first- or second-deposit match pays only what exceeds the every-deposit bonus of the same deposit. required: [every_deposit_bonus_cents, from_cents] properties: every_deposit_bonus_cents: {type: integer, format: int64} from_cents: {type: integer, format: int64, description: The match before the reduction.} AdminStoryDailyCeilingReduction: type: object description: The daily freeplay ceiling cut the claim to what was left of it that day. required: [from_cents] properties: from_cents: {type: integer, format: int64, description: The claim before the ceiling.} ceiling_cents: {type: integer, format: int64, description: The daily ceiling; absent on older grants.} AdminStoryMissionCalculation: type: object description: A mission claim's payout before reductions. base_cents is the deposit amount, deposit sum or deposit volume measured; count is the qualifying deposits, days or referrals counted. required: [basis, computed_cents] properties: basis: {"$ref": "#/components/schemas/RewardMissionPayoutBasis"} base_cents: {type: integer, format: int64} count: {type: integer, format: int64} required_cents: {type: integer, format: int64} required_count: {type: integer, format: int64} percent: {type: integer, format: int32, description: Whole percent.} cap_cents: {type: integer, format: int64} computed_cents: {type: integer, format: int64, description: The freeplay the rule computed; 0 for next-deposit tiers, which set a pending bonus of percent up to cap_cents.} AdminStoryNextDepositBonusCalculation: type: object description: The pending next-deposit bonus this deposit used. required: [percent, limit_cents, bonus_cents] properties: percent: {type: integer, format: int32, description: Whole percent.} limit_cents: {type: integer, format: int64} bonus_cents: {type: integer, format: int64} AdminStoryCampaignCalculation: type: object description: The claimed deposit campaign that paid this deposit. required: [campaign_id, title, percent, cap_left_cents, bonus_cents] properties: campaign_id: {type: string, format: uuid} title: {type: string} percent: {type: integer, format: int32, description: Whole percent.} cap_left_cents: {type: integer, format: int64, description: What was left of the campaign's cap before this deposit.} bonus_cents: {type: integer, format: int64} AdminStoryEveryDepositCalculation: type: object description: The every-deposit bonus of this deposit. It never stacks with the deposit's other bonuses, so paid_cents is what exceeded them. required: [percent_bps, cap_cents, bonus_cents, paid_cents] properties: percent_bps: {type: integer, format: int32, description: Basis points (1000 = 10%).} cap_cents: {type: integer, format: int64, description: 0 means no cap.} bonus_cents: {type: integer, format: int64} other_bonus_cents: {type: integer, format: int64, description: The deposit's other bonuses it did not stack with; absent on older grants.} paid_cents: {type: integer, format: int64} AdminStoryWaitingFor: type: string enum: [provider_confirmation, provider_order_status, admin_approval, admin_reply, player_action, payout, reconciler] x-enum-varnames: - AdminStoryWaitingForProviderConfirmation - AdminStoryWaitingForProviderOrderStatus - AdminStoryWaitingForAdminApproval - AdminStoryWaitingForAdminReply - AdminStoryWaitingForPlayerAction - AdminStoryWaitingForPayout - AdminStoryWaitingForReconciler AdminStoryWait: type: object description: A record that has not reached a final state and what it waits for. required: [ref, waiting_for, since] properties: ref: {"$ref": "#/components/schemas/AdminStoryRef"} waiting_for: {"$ref": "#/components/schemas/AdminStoryWaitingFor"} since: {type: string, format: date-time, description: When the record entered its current state.} expires_at: type: string format: date-time description: When the wait times out (stale checkout, approval or action deadline, claim or link lease). next_check_at: {type: string, format: date-time, description: When the reconciler next checks the record.} provider: {"$ref": "#/components/schemas/AdminStoryProvider"} amount: {"$ref": "#/components/schemas/AdminStoryAmount"} AdminPlayerMoneyTotal: type: object required: [count, cents, recent_count, recent_cents] properties: count: {type: integer, format: int64, minimum: 0} cents: {type: integer, format: int64, minimum: 0} recent_count: {type: integer, format: int64, minimum: 0, description: Rows since recent_since.} recent_cents: {type: integer, format: int64, minimum: 0, description: Cents since recent_since.} AdminPlayerGameMoney: type: object required: [provider_code, provider_label, load_count, load_cents, unload_count, unload_cents, last_at] properties: provider_code: {type: string, minLength: 1} provider_label: {type: string, description: The game's display name; empty when the provider is no longer registered.} load_count: {type: integer, format: int64, minimum: 0} load_cents: {type: integer, format: int64, minimum: 0} unload_count: {type: integer, format: int64, minimum: 0} unload_cents: {type: integer, format: int64, minimum: 0} last_at: {type: string, format: date-time} AdminPlayerMoneySummary: type: object required: [as_of, recent_since, deposits, game_loads, game_unloads, payouts_paid, payouts_open_count, payouts_open_cents, staff_tips_count, staff_tips_cents, staff_tips_open_cents, games] properties: as_of: {type: string, format: date-time} recent_since: {type: string, format: date-time} deposits: {"$ref": "#/components/schemas/AdminPlayerMoneyTotal"} game_loads: {"$ref": "#/components/schemas/AdminPlayerMoneyTotal"} game_unloads: {"$ref": "#/components/schemas/AdminPlayerMoneyTotal"} payouts_paid: {"$ref": "#/components/schemas/AdminPlayerMoneyTotal"} payouts_open_count: {type: integer, format: int64, minimum: 0, description: Payouts not yet paid or closed, including the one being reviewed.} payouts_open_cents: {type: integer, format: int64, minimum: 0} staff_tips_count: {type: integer, format: int64, minimum: 0, description: Staff tips on paid payouts.} staff_tips_cents: {type: integer, format: int64, minimum: 0} staff_tips_open_cents: {type: integer, format: int64, minimum: 0, description: Staff tips on payouts still open.} last_deposit_at: {type: string, format: date-time} last_game_at: {type: string, format: date-time} games: type: array description: One row per game with a completed load or unload, most recent first. items: {"$ref": "#/components/schemas/AdminPlayerGameMoney"} AdminBusinessManualPayoutTipPlayer: type: object required: [user_id, email, display_name, earned_count, earned_amount, waiting_count, waiting_amount] properties: user_id: {type: string, format: uuid} email: {type: string} display_name: {type: string} earned_count: {type: integer, format: int64, minimum: 0} earned_amount: {"$ref": "#/components/schemas/MoneyAmount"} waiting_count: {type: integer, format: int64, minimum: 0} waiting_amount: {"$ref": "#/components/schemas/MoneyAmount"} AdminBusinessManualPayoutTips: type: object description: Staff tips recorded on manual payouts, excluding internal/tester/staff identities. Earned tips are on payouts paid inside the window (settlement time); waiting tips are on payouts still open now, whatever the window. Players are ordered by earned then waiting amount; at most 50 are listed, player_count counts all. required: [earned_count, earned_amount, waiting_count, waiting_amount, player_count, players] properties: earned_count: {type: integer, format: int64, minimum: 0} earned_amount: {"$ref": "#/components/schemas/MoneyAmount"} waiting_count: {type: integer, format: int64, minimum: 0} waiting_amount: {"$ref": "#/components/schemas/MoneyAmount"} player_count: {type: integer, format: int64, minimum: 0} players: type: array items: {"$ref": "#/components/schemas/AdminBusinessManualPayoutTipPlayer"} AdminStoryPage: type: object required: [as_of, open, items] properties: as_of: {type: string, format: date-time, description: The story is cut at this instant; later pages keep it.} open: type: array items: {"$ref": "#/components/schemas/AdminStoryWait"} items: type: array items: {"$ref": "#/components/schemas/AdminStoryItem"} next_cursor: type: string nullable: true description: Cursor of the next (older) page; null on the last page. AdminSituationKind: type: string enum: [deposit_unconfirmed, transfer_unknown, credit_move_unknown, payout_request, payout_needs_attention, first_cashout, offapp_draft, player_risk, device_cluster, provider_incident, provider_refill, chat_waiting, closeout_candidates, money_route_failure, cashout_review, payment_payout_unavailable, provider_account_issue] x-enum-varnames: - AdminSituationKindDepositUnconfirmed - AdminSituationKindTransferUnknown - AdminSituationKindCreditMoveUnknown - AdminSituationKindPayoutRequest - AdminSituationKindPayoutNeedsAttention - AdminSituationKindFirstCashout - AdminSituationKindOffappDraft - AdminSituationKindPlayerRisk - AdminSituationKindDeviceCluster - AdminSituationKindProviderIncident - AdminSituationKindProviderRefill - AdminSituationKindChatWaiting - AdminSituationKindCloseoutCandidates - AdminSituationKindMoneyRouteFailure - AdminSituationKindCashoutReview - AdminSituationKindPaymentPayoutUnavailable - AdminSituationKindProviderAccountIssue AdminSituationSeverity: type: string enum: [info, warn, critical] x-enum-varnames: - AdminSituationSeverityInfo - AdminSituationSeverityWarn - AdminSituationSeverityCritical AdminSituationSort: type: string description: Server-owned ordering before pagination. A cursor belongs to its selected sort. default: latest enum: [urgency, latest] x-enum-varnames: - AdminSituationSortUrgency - AdminSituationSortLatest AdminSituationFilter: type: string description: Inbox tab. Chat holds every situation where the player waits, so it overlaps the others. enum: [all, money, payouts, chat, platform, closeout] x-enum-varnames: - AdminSituationFilterAll - AdminSituationFilterMoney - AdminSituationFilterPayouts - AdminSituationFilterChat - AdminSituationFilterPlatform - AdminSituationFilterCloseout AdminSituationLinkedKind: type: string enum: [provider_transfer, financial_case, reconciliation_item, ops_event, risk_review, payment_deposit, payment_withdrawal, first_cashout_review, credit_move, support_conversation, provider_health, cashout_review, provider_account] x-enum-varnames: - AdminSituationLinkedProviderTransfer - AdminSituationLinkedFinancialCase - AdminSituationLinkedReconciliationItem - AdminSituationLinkedOpsEvent - AdminSituationLinkedRiskReview - AdminSituationLinkedPaymentDeposit - AdminSituationLinkedPaymentWithdrawal - AdminSituationLinkedFirstCashoutReview - AdminSituationLinkedCreditMove - AdminSituationLinkedSupportConversation - AdminSituationLinkedProviderHealth - AdminSituationLinkedCashoutReview - AdminSituationLinkedProviderAccount AdminSituationActionCode: type: string enum: [acknowledge_withdrawal, approve_withdrawal, reject_withdrawal, mark_withdrawal_paid, approve_first_cashout, reject_first_cashout, settle_off_app_deposit, void_off_app_deposit, record_off_app_deposit, acknowledge_risk_review, snooze_risk_review, moderate_player, acknowledge_provider_health, update_refill_threshold, record_provider_refill, reply_to_player, approve_cashout_review, reject_cashout_review, recheck_provider_account, relink_provider_account, set_provider_account_password, reset_provider_account_password] x-enum-varnames: - AdminSituationActionAcknowledgeWithdrawal - AdminSituationActionApproveWithdrawal - AdminSituationActionRejectWithdrawal - AdminSituationActionMarkWithdrawalPaid - AdminSituationActionApproveFirstCashout - AdminSituationActionRejectFirstCashout - AdminSituationActionSettleOffAppDeposit - AdminSituationActionVoidOffAppDeposit - AdminSituationActionRecordOffAppDeposit - AdminSituationActionAcknowledgeRiskReview - AdminSituationActionSnoozeRiskReview - AdminSituationActionModeratePlayer - AdminSituationActionAcknowledgeProviderHealth - AdminSituationActionUpdateRefillThreshold - AdminSituationActionRecordProviderRefill - AdminSituationActionReplyToPlayer - AdminSituationActionApproveCashoutReview - AdminSituationActionRejectCashoutReview - AdminSituationActionRecheckProviderAccount - AdminSituationActionRelinkProviderAccount - AdminSituationActionSetProviderAccountPassword - AdminSituationActionResetProviderAccountPassword AdminSituationCauseCode: type: string description: Why the situation exists, as the record's state, the risk signal or a feed-level cause. The frontend owns the words. enum: [unknown_requires_reconcile, provider_creation_rejected, provider_status_unrecognized, failed_internal, outcome_contradicted, reconcile_required, pending, approving, settling, needs_reconcile, webhook_mismatch, checkout_created, stale_pending, provider_created, awaiting_settlement, new, waiting_for_approval, approved_send_payment, action_required, deposit_velocity_24h, provider_transfer_velocity_24h, withdrawal_velocity_24h, reconciliation_required, failure_velocity_7d, destination_reuse, fingerprint_reuse, provider_down, transfer_failures, agent_balance_low, refill_overdue, player_message_unread, stale_never_paid, money_route_failure, pending_review, payout_access_denied, account_not_found, account_unreadable, credentials_rejected] x-enum-varnames: - AdminSituationCauseUnknownRequiresReconcile - AdminSituationCauseProviderCreationRejected - AdminSituationCauseProviderStatusUnrecognized - AdminSituationCauseFailedInternal - AdminSituationCauseOutcomeContradicted - AdminSituationCauseReconcileRequired - AdminSituationCausePending - AdminSituationCauseApproving - AdminSituationCauseSettling - AdminSituationCauseNeedsReconcile - AdminSituationCauseWebhookMismatch - AdminSituationCauseCheckoutCreated - AdminSituationCauseStalePending - AdminSituationCauseProviderCreated - AdminSituationCauseAwaitingSettlement - AdminSituationCauseNew - AdminSituationCauseWaitingForApproval - AdminSituationCauseApprovedSendPayment - AdminSituationCauseActionRequired - AdminSituationCauseDepositVelocity24h - AdminSituationCauseProviderTransferVelocity24h - AdminSituationCauseWithdrawalVelocity24h - AdminSituationCauseReconciliationRequired - AdminSituationCauseFailureVelocity7d - AdminSituationCauseDestinationReuse - AdminSituationCauseFingerprintReuse - AdminSituationCauseProviderDown - AdminSituationCauseTransferFailures - AdminSituationCauseAgentBalanceLow - AdminSituationCauseRefillOverdue - AdminSituationCausePlayerMessageUnread - AdminSituationCauseStaleNeverPaid - AdminSituationCauseMoneyRouteFailure - AdminSituationCausePendingReview - AdminSituationCausePayoutAccessDenied - AdminSituationCauseAccountNotFound - AdminSituationCauseAccountUnreadable - AdminSituationCauseCredentialsRejected AdminSituationLinked: type: object description: A record folded into the situation. `id` is what the record's own admin route takes (an ops event id is its feed id, a provider health id is `provider:probe_type:probe_level`); `case_kind` is set for financial cases. required: [kind, id] properties: kind: {"$ref": "#/components/schemas/AdminSituationLinkedKind"} id: {type: string} case_kind: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} AdminSituationAction: type: object description: An action the backend offers. Disabled actions stay listed with the reason; the owning route still enforces its own gate. A linked financial case is acted on through its own detail route, which lists the outcomes that are safe for that case. required: [code, enabled] properties: code: {"$ref": "#/components/schemas/AdminSituationActionCode"} enabled: {type: boolean} disabled_reason: type: string enum: [super_admin_required] x-enum-varnames: [AdminSituationDisabledSuperAdminRequired] AdminSituationPlayer: type: object required: [id, name, email] properties: id: {type: string, format: uuid} name: {type: string} email: {type: string} AdminSituationMember: type: object required: [id, name] properties: id: {type: string, format: uuid} name: {type: string} AdminSituationProvider: type: object required: [code, label] properties: code: {type: string} label: {type: string} AdminSituationSubject: type: object required: [players] properties: player: {"$ref": "#/components/schemas/AdminSituationPlayer"} provider: {"$ref": "#/components/schemas/AdminSituationProvider"} players: description: Members of a device cluster or players hit by a provider incident. type: array items: {"$ref": "#/components/schemas/AdminSituationMember"} AdminSituationCause: type: object required: [code] properties: code: {"$ref": "#/components/schemas/AdminSituationCauseCode"} provider_message: type: string maxLength: 200 description: The provider's latest message about the record, redacted. AdminSituationChat: type: object description: The player's unread support conversation; the player is waiting. required: [conversation_id, unread] properties: conversation_id: {type: string, format: uuid} unread: {type: integer, format: int64, minimum: 1} last_player_message_at: {type: string, format: date-time} AdminSituationRefillReason: type: string description: Why a game store needs a refill. enum: [agent_balance_low, refill_overdue] x-enum-varnames: [AdminSituationRefillReasonAgentBalanceLow, AdminSituationRefillReasonRefillOverdue] ProviderAccountReconnectRequest: type: object additionalProperties: false required: [password, expected] properties: expected: {"$ref": "#/components/schemas/AccountManagementExpected"} password: {type: string, minLength: 1, maxLength: 255, description: Current game password; never logged or returned} ProviderAccountSetPasswordRequest: type: object additionalProperties: false required: [password, reason, expected] properties: expected: {"$ref": "#/components/schemas/AccountManagementExpected"} password: {type: string, minLength: 1, maxLength: 255, description: Current password already set in the provider panel} reason: {type: string, minLength: 3, maxLength: 2000} ProviderAccountResetPasswordRequest: type: object additionalProperties: false required: [reason, expected] properties: expected: {"$ref": "#/components/schemas/AccountManagementExpected"} current_password: {type: string, minLength: 1, maxLength: 255, description: Current game password only where the server action requires it; otherwise omitted} reason: {type: string, minLength: 3, maxLength: 2000} GamePasswordResetRequest: type: object additionalProperties: false required: [expected] properties: expected: {"$ref": "#/components/schemas/AccountManagementExpected"} current_password: {type: string, minLength: 1, maxLength: 255, description: Current game password only where required by the server action} ProviderAccountCredentialRepairResponse: type: object required: [provider_account_id, message, effects] properties: new_revision: {type: integer, format: int64, minimum: 1, description: Confirmed management revision; older recorded replay results may omit it} credential: {"$ref": "#/components/schemas/AccountCredentialSummary"} provider_account_id: {type: string, format: uuid} message: {type: string} password: {type: string, description: Reset only, one-time initial confirmed response; omitted on replay and never in notifications} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} ProviderAccountRepairOptions: type: object required: [verification, password, reconnect_enabled, set_password_enabled, reset_password_enabled, reset_requires_current_password, reset_result_kind] properties: verification: {"$ref": "#/components/schemas/AccountRepairVerification"} reset_result_kind: {"$ref": "#/components/schemas/PasswordResetResultKind"} password: {"$ref": "#/components/schemas/AddExistingPasswordRequirement"} reconnect_enabled: {type: boolean} set_password_enabled: {type: boolean} reset_password_enabled: {type: boolean} reset_requires_current_password: {type: boolean} ProviderAccountRecheckRequest: type: object additionalProperties: false required: [reason] properties: reason: {type: string, minLength: 1, maxLength: 2000} ProviderAccountRelinkRequest: type: object additionalProperties: false required: [reason, username, provider_player_id, password] properties: reason: {type: string, minLength: 3, maxLength: 2000, description: Nonsecret reason without submitted or saved game passwords} username: {type: string, minLength: 1, maxLength: 255} provider_player_id: {type: string, minLength: 1, maxLength: 255} password: {type: string, minLength: 1, maxLength: 255, description: Current game password is required for every relink and saved encrypted on success. Native verification may prove identity only; never returned} ProviderAccountRepairResponse: type: object required: [provider_account_id, stored_reference, stored_username, status, identity_changed, issue_cleared, options, effects] properties: provider_account_id: {type: string, format: uuid} stored_reference: {type: string} stored_username: {type: string} stored_player_id: {type: string} current_reference: {type: string} current_username: {type: string} current_player_id: {type: string} verification_proof: {type: string, enum: [agent_scoped_lookup, credential_verified, agent_signed_balance_read]} native_status: {type: string, description: Only when explicitly provided by the adapter} status: type: string enum: [balance_readable, change_suggested, unknown, not_found, verification_failed] x-enum-varnames: [AccountRepairBalanceReadable, AccountRepairChangeSuggested, AccountRepairUnknown, AccountRepairNotFound, AccountRepairVerificationFailed] balance_credits: {type: integer, format: int64, minimum: 0} identity_changed: {type: boolean} issue_cleared: {type: boolean} options: {"$ref": "#/components/schemas/ProviderAccountRepairOptions"} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} ProviderAccountIssueReason: type: string enum: [not_found, account_unreadable, credentials_rejected] x-enum-varnames: [ProviderAccountIssueNotFound, ProviderAccountIssueUnreadable, ProviderAccountIssueCredentialsRejected] ProviderFailureCategory: type: string enum: [timeout, transport, decode, auth, upstream_error, invalid_account, credentials_rejected, unsupported, canceled, deferred] x-enum-varnames: [ProviderFailureCategoryTimeout, ProviderFailureCategoryTransport, ProviderFailureCategoryDecode, ProviderFailureCategoryAuth, ProviderFailureCategoryUpstreamError, ProviderFailureCategoryInvalidAccount, ProviderFailureCategoryCredentialsRejected, ProviderFailureCategoryUnsupported, ProviderFailureCategoryCanceled, ProviderFailureCategoryDeferred] AdminMoneyRouteFailure: type: object required: [count] properties: user_id: {type: string, format: uuid} provider_account_id: {type: string, format: uuid} provider_code: {$ref: '#/components/schemas/ProviderCode'} failure_category: {$ref: '#/components/schemas/ProviderFailureCategory'} count: {type: integer, format: int64, minimum: 1} AdminMoneyRouteContext: type: object required: [failures, unattributed_errors, affected_player_count, truncated, scope, operation, next_step] properties: failures: type: array maxItems: 32 items: {$ref: '#/components/schemas/AdminMoneyRouteFailure'} affected_player_count: {type: integer, format: int64, minimum: 0, maximum: 32} unattributed_errors: {type: integer, format: int64, minimum: 0} truncated: {type: boolean} scope: {type: string, enum: [single_player, multiple_players, unattributed]} operation: {type: string, enum: [load, redemption, deposit, cash_out, money_request]} next_step: {type: string, enum: [check_game_credentials, check_provider_authentication, check_connection, inspect_provider_response, inspect_failures]} AdminProvisioningReconciliation: type: object description: Safe operator context for definite creation refusals or exhausted read-only reconciliation. required: [provisioning_id, job_id, attempts] properties: provisioning_id: {type: string, format: uuid} job_id: {type: string, format: uuid} attempts: {type: integer, format: int32, minimum: 1} reason: {type: string, enum: [provider_authentication, username_taken, unknown_refusal], x-enum-varnames: [ProvisioningProviderAuthentication, ProvisioningUsernameTaken, ProvisioningUnknownRefusal], description: Typed definite no-create reason; absent for uncertain reconciliation.} next_step: {type: string, enum: [check_provider_authentication_then_retry, retry_with_new_username_or_link_existing, inspect_provider_response], x-enum-varnames: [ProvisioningCheckAuthenticationThenRetry, ProvisioningRetryOrLink, ProvisioningInspectResponse]} vendor_code: {type: string, maxLength: 32, pattern: '^[A-Za-z0-9_.-]*$', description: Adapter-selected sanitized native status code; no inferred meaning.} panel_url: {type: string, format: uri, description: Configured provider operator panel; never includes credentials.} AdminSituationFacts: type: object description: Numbers and safe operator context; each is present only where it applies. properties: provider_account_id: {type: string, format: uuid} account_username: {type: string} account_issue_reason: {"$ref": "#/components/schemas/ProviderAccountIssueReason"} provider_panel_url: {type: string, format: uri, description: Existing approved provider operator panel link} money_route_context: $ref: '#/components/schemas/AdminMoneyRouteContext' provisioning: {"$ref": "#/components/schemas/AdminProvisioningReconciliation"} money_route: {type: string, description: HTTP method and matched route template; never a concrete request URL.} error_count: {type: integer, format: int64, minimum: 3, description: Cumulative observed failures in the active episode.} last_status: {type: integer, format: int32, minimum: 100, maximum: 599, description: Last observed status in the active episode.} rejected_transfers: {type: integer, format: int64, minimum: 0} unknown_transfers: {type: integer, format: int64, minimum: 0} agent_balance_credits: description: Latest provider agent balance, whole credits. type: integer format: int64 refill_below_credits: description: Effective refill threshold, whole credits. type: integer format: int64 refill_reasons: description: Why a store needs a refill; one or both reasons. type: array items: {"$ref": "#/components/schemas/AdminSituationRefillReason"} warn_if_no_refill_within_hours: description: The store's refill time limit, when it is on. type: integer format: int32 last_refilled_at: description: When an admin last recorded a refill of the store. type: string format: date-time refill_due_at: description: When the refill time limit runs out (or ran out). type: string format: date-time never_paid_deposits: {type: integer, format: int64, minimum: 0, description: 'Close-out candidates to review: stale never-paid checkouts before the provider check. The close-out preview may exclude some (an unconfirmed provider check), so show this as "N to review", not as N to close.'} expired_offapp_drafts: {type: integer, format: int64, minimum: 0, description: Unsettled off-app drafts past the close-out threshold, to review.} AdminSituation: type: object required: [key, kind, subject, cause, since, severity, facts, linked, actions] properties: seen: {type: boolean, description: Whether this staff member has read the current situation.} activity_at: {type: string, format: date-time, description: Version to acknowledge when marking this situation as read.} key: type: string description: Stable deduplication key, e.g. `transfer:`. kind: {"$ref": "#/components/schemas/AdminSituationKind"} subject: {"$ref": "#/components/schemas/AdminSituationSubject"} cause: {"$ref": "#/components/schemas/AdminSituationCause"} stakes_cents: description: Money at stake in USD cents, when the problem holds money. type: integer format: int64 since: {type: string, format: date-time} expires_at: {type: string, format: date-time} severity: {"$ref": "#/components/schemas/AdminSituationSeverity"} chat: {"$ref": "#/components/schemas/AdminSituationChat"} facts: {"$ref": "#/components/schemas/AdminSituationFacts"} linked: type: array items: {"$ref": "#/components/schemas/AdminSituationLinked"} actions: type: array items: {"$ref": "#/components/schemas/AdminSituationAction"} AdminSituationCounts: type: object description: Situations per filter across the whole feed, whichever filter was requested. They drive the Inbox badges. required: [all, money, payouts, chat, platform, closeout] properties: all: {type: integer, minimum: 0} unread: {type: integer, minimum: 0, description: Open unread situations for signed-in staff across all filters.} money: {type: integer, minimum: 0} payouts: {type: integer, minimum: 0} chat: {type: integer, minimum: 0} platform: {type: integer, minimum: 0} closeout: {type: integer, minimum: 0} AdminSituationPage: type: object required: [as_of, situations, counts, next_cursor] properties: as_of: {type: string, format: date-time} situations: type: array items: {"$ref": "#/components/schemas/AdminSituation"} counts: {"$ref": "#/components/schemas/AdminSituationCounts"} next_cursor: type: string nullable: true ProviderAccountLinkOption: type: object additionalProperties: false required: [game_id, game_name, provider_code, form, action] properties: game_id: {type: string} game_name: {type: string} provider_code: {"$ref": "#/components/schemas/ProviderCode"} form: {"$ref": "#/components/schemas/AddExistingGameAccountForm"} action: {"$ref": "#/components/schemas/InteractionAction"} AdminProviderAccountHistoryResponse: type: object required: - accounts - link_options properties: link_options: {type: array, items: {"$ref": "#/components/schemas/ProviderAccountLinkOption"}} accounts: type: array items: "$ref": "#/components/schemas/AdminProviderAccountHistoryItem" AdminLinkProviderAccountRequest: type: object additionalProperties: false required: - game_id - account_identifier - password - expected_slot - reason properties: expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} game_id: type: string minLength: 1 account_identifier: type: string minLength: 1 maxLength: 255 password: type: string minLength: 1 maxLength: 255 reason: type: string minLength: 3 maxLength: 2000 reference: type: string minLength: 1 maxLength: 255 nullable: true AdminProviderAccountLinkResponse: type: object required: - account properties: account: "$ref": "#/components/schemas/AdminProviderAccountHistoryItem" replayed: type: boolean default: false AdminUnlinkProviderAccountRequest: {"type":"object","additionalProperties":false,"required":["expected","preview_id","reason"],"properties":{"expected":{"$ref":"#/components/schemas/AccountManagementExpected"},"preview_id":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":3,"maxLength":2000},"reference":{"type":"string","minLength":1,"maxLength":255,"nullable":true}}} AdminProviderAccountUnlinkResponse: type: object required: - account - effects - fresh_balance_credits - fresh_balance_read - cycle_kind - loaded_principal_on_provider properties: effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" account: "$ref": "#/components/schemas/AdminProviderAccountHistoryItem" last_known_balance_credits: type: integer format: int64 nullable: true fresh_balance_credits: type: integer format: int64 enum: [0] fresh_balance_read: type: string enum: - succeeded x-enum-varnames: - FreshBalanceReadSucceeded cycle_kind: "$ref": "#/components/schemas/ProviderAccountCycleKind" loaded_principal_on_provider: description: PlayGo-funded principal (cash + withdrawable + freeplay) loaded in the open cycle and left on the provider. allOf: - "$ref": "#/components/schemas/MoneyAmount" replayed: type: boolean default: false AdminFirstUnloadReviewSummary: type: object required: - id - user_id - provider_account_id - provider_code - state - snapshot_version - reviewed_balance_credits - reviewed_value - reviewed_observed_at - requested_at properties: id: type: string format: uuid user_id: type: string format: uuid user_email: type: string nullable: true provider_account_id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" state: "$ref": "#/components/schemas/FirstUnloadReviewState" snapshot_version: type: integer format: int32 reviewed_balance_credits: type: integer format: int64 reviewed_value: description: Cash value of the reviewed balance; the maximum approvable payout. allOf: - "$ref": "#/components/schemas/MoneyAmount" reviewed_observed_at: type: string format: date-time requested_at: type: string format: date-time approved_payout: nullable: true allOf: - "$ref": "#/components/schemas/MoneyAmount" approved_by: type: string format: uuid nullable: true provider_transfer_id: type: string format: uuid nullable: true settled_at: type: string format: date-time nullable: true AdminFirstUnloadReviewListResponse: type: object required: - reviews properties: reviews: type: array items: "$ref": "#/components/schemas/AdminFirstUnloadReviewSummary" AdminFirstUnloadReviewCycleLoad: type: object required: - transfer_id - amount - provider_credits - source_cash - source_withdrawable - source_freeplay - completed_at properties: source_deposit_bonus_cents: {type: integer, format: int64, minimum: 0} source_campaign_bonus_cents: {type: integer, format: int64, minimum: 0} transfer_id: type: string format: uuid amount: "$ref": "#/components/schemas/MoneyAmount" provider_credits: type: integer format: int64 source_cash: "$ref": "#/components/schemas/MoneyAmount" source_withdrawable: "$ref": "#/components/schemas/MoneyAmount" source_freeplay: "$ref": "#/components/schemas/MoneyAmount" completed_at: type: string format: date-time AdminFirstUnloadReviewEvent: type: object required: - id - kind - created_at - details properties: id: type: string format: uuid kind: type: string actor_id: type: string format: uuid nullable: true reason: type: string nullable: true details: type: object additionalProperties: true created_at: type: string format: date-time AdminFirstUnloadReviewDetail: type: object required: - review - account - link_proof - cycle_loads - cycle_principal - events - actions - debit_confirmed properties: actions: type: object required: - approve - reject - resolve_debit_confirmed - resolve_debit_not_applied properties: approve: "$ref": "#/components/schemas/InteractionAction" reject: "$ref": "#/components/schemas/InteractionAction" resolve_debit_confirmed: "$ref": "#/components/schemas/InteractionAction" resolve_debit_not_applied: "$ref": "#/components/schemas/InteractionAction" debit_confirmed: description: True once the provider debit of the reviewed unload is known to have been applied. type: boolean review: "$ref": "#/components/schemas/AdminFirstUnloadReviewSummary" account: "$ref": "#/components/schemas/AdminProviderAccountHistoryItem" link_proof: type: string enum: - agent_scoped_lookup - credential_verified - agent_signed_balance_read x-enum-varnames: - LinkProofAgentScopedLookup - LinkProofCredentialVerified - LinkProofAgentSignedBalanceRead link_reason: type: string nullable: true link_requested_by: type: string format: uuid nullable: true cycle_loads: type: array items: "$ref": "#/components/schemas/AdminFirstUnloadReviewCycleLoad" cycle_principal: type: object required: - cash - withdrawable - freeplay properties: total_loaded_cents: {type: integer, format: int64, minimum: 0} deposit_bonus_cents: {type: integer, format: int64, minimum: 0} campaign_bonus_cents: {type: integer, format: int64, minimum: 0} cash: "$ref": "#/components/schemas/MoneyAmount" withdrawable: "$ref": "#/components/schemas/MoneyAmount" freeplay: "$ref": "#/components/schemas/MoneyAmount" events: type: array items: "$ref": "#/components/schemas/AdminFirstUnloadReviewEvent" AdminApproveFirstUnloadReviewRequest: type: object additionalProperties: false required: - snapshot_version - expected_balance_credits - approved_payout_cents - assignment_confirmed - reason properties: snapshot_version: type: integer format: int32 minimum: 1 expected_balance_credits: type: integer format: int64 minimum: 0 approved_payout_cents: description: Whole-cent payout, 0 up to the cash value of the fresh balance. type: integer format: int64 minimum: 0 assignment_confirmed: description: The admin confirms the provider account belongs to this player. type: boolean reason: type: string minLength: 1 maxLength: 2000 AdminResolveFirstUnloadReviewRequest: type: object additionalProperties: false required: - resolution - provider_evidence_reference - reason properties: resolution: type: string enum: - debit_confirmed - debit_not_applied x-enum-varnames: - ResolutionDebitConfirmed - ResolutionDebitNotApplied provider_evidence_reference: description: Provider-side evidence (e.g. provider panel transaction id or ticket) backing the resolution. type: string minLength: 1 maxLength: 255 reason: type: string minLength: 1 maxLength: 2000 AdminRejectFirstUnloadReviewRequest: type: object additionalProperties: false required: - reason properties: reason: type: string minLength: 1 maxLength: 2000 AdminFirstUnloadReviewCommandResponse: type: object required: - review properties: review: "$ref": "#/components/schemas/AdminFirstUnloadReviewSummary" replayed: type: boolean default: false AdminResolveProviderLoadRequest: type: object required: [reason, evidence_reference, confirmed_not_applied] properties: reason: type: string minLength: 1 maxLength: 2000 evidence_reference: type: string minLength: 1 maxLength: 255 confirmed_not_applied: type: boolean enum: [true] ProviderAccountsResponse: type: object required: - accounts properties: accounts: type: array items: "$ref": "#/components/schemas/ProviderAccount" GameAccountSetupState: type: string enum: - not_added - not_created - queued - running - active - disabled - failed - unknown_requires_reconcile Game: type: object required: - id - provider_code - name - category - active - added - added_at - provider_account_setup_state - provider_account_setup_message - favorite - launch_mode - actions properties: api_access_message: {type: string, description: Server-owned paused-provider explanation and support guidance.} api_access: {"$ref": "#/components/schemas/ProviderAPIAccessAvailability"} id: type: string provider_code: "$ref": "#/components/schemas/ProviderCode" name: type: string category: "$ref": "#/components/schemas/GameCategory" active: type: boolean added: type: boolean added_at: type: string format: date-time nullable: true description: When this player first added the game, from user_games.created_at. Null when no player library row exists. Catalog order does not represent add order. thumbnail_url: type: string nullable: true download_url: type: string format: uri nullable: true description: Public player download/install URL from the active audited admin game-link setting. Absent or null when no setting is active. Never an agent panel, account credential, per-account launch URL or code/catalog default. provider_account_setup_state: "$ref": "#/components/schemas/GameAccountSetupState" provider_account_setup_message: type: string nullable: true provider_account_id: type: string format: uuid nullable: true provider_account_label: description: User-facing provider login/username shown as the Game ID. type: string nullable: true provider_player_account_ref: description: Backend/provider account reference used for provider operations; may be an internal numeric ID or UUID-like token. type: string nullable: true copyable_ref: description: User-facing value copied by the Game ID action; usually the provider account label, not the backend operation reference. type: string nullable: true provider_credit_balance: description: API presentation value normalized from DB-owned numeric(22,4) provider balance. type: integer format: int64 nullable: true provider_credit_balance_read_state: "$ref": "#/components/schemas/ProviderBalanceReadState" provider_credit_observed_at: type: string format: date-time nullable: true masked_credential: type: string nullable: true favorite: type: boolean launch_mode: type: string enum: - new_tab actions: "$ref": "#/components/schemas/GameActions" add_existing_form: description: Present when the game's provider supports linking an existing account (actions.add_existing may still be disabled). Null when unsupported. nullable: true allOf: - "$ref": "#/components/schemas/AddExistingGameAccountForm" GamesResponse: type: object required: - games - poll properties: games: type: array items: "$ref": "#/components/schemas/Game" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" GameResponse: type: object required: - game properties: game: "$ref": "#/components/schemas/Game" GameCommandResponse: type: object required: - game - effects properties: game: "$ref": "#/components/schemas/Game" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" GameCredentialResponse: type: object additionalProperties: false required: - username - password properties: username: type: string minLength: 1 password: type: string minLength: 1 ProviderCredentialEmailStatus: type: string enum: - queued - unavailable - failed - not_available ProviderCredentialDelivery: type: object additionalProperties: false required: - reveal_available - email_status - message properties: credential_id: {type: string, format: uuid, description: Exact persisted credential for this result; use as the reveal precondition} reveal_available: type: boolean description: Whether the newly returned provider credential was securely persisted and can be revealed on demand. email_status: "$ref": "#/components/schemas/ProviderCredentialEmailStatus" message: type: string minLength: 1 description: Non-secret feedback suitable for the player UI. GamePasswordResetResponse: type: object additionalProperties: false required: - game - effects - credential_delivery properties: game: "$ref": "#/components/schemas/Game" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" credential_delivery: "$ref": "#/components/schemas/ProviderCredentialDelivery" AddGameResponse: type: object required: - game - effects - poll properties: game: "$ref": "#/components/schemas/Game" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" replayed: type: boolean default: false SetGameFavoriteRequest: type: object additionalProperties: false required: - favorite properties: favorite: type: boolean LaunchGameRequest: type: object additionalProperties: false properties: return_url: type: string nullable: true locale: type: string nullable: true LaunchGameResponse: type: object required: - game_id - provider_code - provider_account_id - launch_mode - launch_url - fallback - effects properties: game_id: type: string provider_code: "$ref": "#/components/schemas/ProviderCode" provider_account_id: type: string format: uuid launch_mode: type: string enum: - new_tab launch_url: type: string expires_at: type: string format: date-time nullable: true fallback: type: boolean evidence: nullable: true allOf: - "$ref": "#/components/schemas/RedactedEvidenceSummary" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" SupportConversationStatus: type: string enum: - open - resolved SupportSenderKind: type: string enum: - user - support - system SupportActions: type: object required: - send_message - mark_read - resolve - reopen properties: send_message: "$ref": "#/components/schemas/InteractionAction" mark_read: "$ref": "#/components/schemas/InteractionAction" resolve: "$ref": "#/components/schemas/InteractionAction" reopen: "$ref": "#/components/schemas/InteractionAction" SupportContactLinkField: type: string enum: [messenger_url, telegram_url, whatsapp_url, sms_phone, email] x-enum-varnames: [SupportContactFieldMessenger, SupportContactFieldTelegram, SupportContactFieldWhatsApp, SupportContactFieldSMS, SupportContactFieldEmail] SupportContactLinksValidationError: type: object required: [error] properties: error: {"$ref": "#/components/schemas/APIError"} field: {"$ref": "#/components/schemas/SupportContactLinkField"} SupportContactLinks: type: object required: [version, whatsapp_url, email, sms_phone, inapp_signup_freeplay_cents] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} inapp_signup_freeplay_cents: {type: integer, format: int64, minimum: 0, readOnly: true, description: "Public signup offer amount. Show Get $X free play only above zero; the verified signup rechecks current policy and eligibility."} version: type: integer format: int64 minimum: 0 whatsapp_url: type: string maxLength: 2048 description: Empty or an HTTPS wa.me / api.whatsapp.com contact link with an international phone number. email: type: string maxLength: 254 description: Empty or a plain support email address, without a display name. messenger_url: type: string maxLength: 2048 description: Empty or an official HTTPS m.me, messenger.com/t, facebook.com, www.facebook.com, m.facebook.com, fb.me or fb.com destination. Empty hides the shortcut. telegram_url: type: string maxLength: 2048 description: Optional HTTPS t.me username contact; empty hides it. Omit on PATCH to preserve the current value. sms_phone: type: string nullable: true maxLength: 16 description: International phone number with leading + for the text-message (sms:) shortcut, or null when none is set (hide the shortcut). Opens the device default messaging app (iMessage on iOS, Google Messages on Android). UpdateSupportContactLinksRequest: type: object required: [expected_version, whatsapp_url, email, sms_phone] properties: expected_version: type: integer format: int64 minimum: 0 whatsapp_url: type: string maxLength: 2048 email: type: string maxLength: 254 messenger_url: type: string maxLength: 2048 description: Omit to preserve the current destination; send an empty string to hide it. telegram_url: type: string maxLength: 2048 description: Optional HTTPS t.me username contact; empty hides it. Omit on PATCH to preserve the current value. sms_phone: type: string nullable: true minLength: 1 maxLength: 16 description: International phone number with leading +, or null to hide the shortcut. Always sent; send the current value to keep it. SupportConversation: type: object required: - id - user_id - status - unread_for_user - unread_for_support - version - created_at - updated_at - actions - poll properties: id: type: string format: uuid user_id: type: string format: uuid status: "$ref": "#/components/schemas/SupportConversationStatus" last_message_seq: type: integer format: int64 minimum: 1 nullable: true last_message_at: type: string format: date-time nullable: true last_user_message_at: type: string format: date-time nullable: true last_support_message_at: type: string format: date-time nullable: true user_last_read_seq: type: integer format: int64 minimum: 1 nullable: true support_last_read_seq: type: integer format: int64 minimum: 1 nullable: true unread_for_user: type: integer minimum: 0 unread_for_support: type: integer minimum: 0 version: type: integer format: int64 minimum: 1 resolved_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time actions: "$ref": "#/components/schemas/SupportActions" poll: "$ref": "#/components/schemas/PollHint" AdminSupportConversation: allOf: - "$ref": "#/components/schemas/SupportConversation" - type: object required: - player_email - claim - aliases properties: pending_actions_count: {type: integer, format: int64, minimum: 0, description: "Domain pending work, independent of unread messages."} player_email: type: string format: email last_message: "$ref": "#/components/schemas/SupportLastMessagePreview" aliases: type: array description: The player's active aliases, oldest first. items: {"$ref": "#/components/schemas/SupportPlayerAlias"} player_display_name: type: string nullable: true resolved_by_user_id: type: string format: uuid nullable: true resolved_by_label: type: string nullable: true resolution_note_text: type: string maxLength: 2000 nullable: true claim: "$ref": "#/components/schemas/SupportClaim" SupportLastMessagePreview: type: object additionalProperties: false description: The conversation's newest message, absent before the first. text_preview is its text on one line, cut to 140 characters with an ellipsis when longer; it is absent for an image, whose kind says what it is. required: [kind, sender_kind, created_at] properties: kind: type: string enum: [text, image] x-enum-varnames: [SupportLastMessageKindText, SupportLastMessageKindImage] text_preview: {type: string, maxLength: 141} sender_kind: {"$ref": "#/components/schemas/SupportSenderKind"} created_at: {type: string, format: date-time} SupportPlayerAlias: type: object additionalProperties: false required: [kind, value] properties: kind: {"$ref": "#/components/schemas/PlayerAliasKind"} value: {type: string} SupportClaim: type: object description: Advisory lock state for an admin support conversation, computed relative to the requesting admin. `mine` means the caller holds the active claim; `other` means a different admin does; `unclaimed` means no active claim. required: - state properties: state: type: string enum: - unclaimed - mine - other x-enum-varnames: [SupportClaimStateUnclaimed, SupportClaimStateMine, SupportClaimStateOther] holder_label: type: string description: Display label of the admin holding the claim; null when unclaimed. nullable: true expires_at: type: string format: date-time description: When the active claim lease expires; null when unclaimed. nullable: true SupportMessage: type: object required: - id - conversation_id - seq - sender_kind - public_sender_label - body_text - body_bytes - created_at properties: attachment_id: type: string format: uuid id: type: string format: uuid conversation_id: type: string format: uuid seq: type: integer format: int64 minimum: 1 sender_kind: "$ref": "#/components/schemas/SupportSenderKind" sender_user_id: type: string format: uuid nullable: true public_sender_label: type: string minLength: 1 admin_sender_label: type: string description: Admin-only label for support-authored messages; omitted from player message responses. nullable: true body_text: type: string minLength: 1 maxLength: 8000 body_bytes: type: integer minimum: 1 maximum: 8000 client_message_id: type: string minLength: 1 nullable: true created_at: type: string format: date-time SupportConversationResponse: type: object required: - conversation properties: conversation: "$ref": "#/components/schemas/SupportConversation" AdminSupportConversationResponse: type: object required: - conversation properties: conversation: "$ref": "#/components/schemas/AdminSupportConversation" AdminSupportConversationsResponse: type: object required: - conversations properties: conversations: type: array items: "$ref": "#/components/schemas/AdminSupportConversation" next_cursor: type: string nullable: true SupportTyping: type: object required: [label, expires_in_ms, version] properties: label: {type: string, description: Player public label for staff; Support for players.} expires_in_ms: {type: integer, minimum: 1, maximum: 6000} version: {type: string, format: uuid} SupportMessagesResponse: type: object required: - messages - has_more properties: typing: nullable: true allOf: - "$ref": "#/components/schemas/SupportTyping" description: Opposite-side ephemeral typing; null when inactive. Never a message or read receipt. messages: type: array items: "$ref": "#/components/schemas/SupportMessage" has_more: type: boolean has_more_after: type: boolean description: Set only for an admin around_seq window; true when newer messages exist after it. AdminSupportSearchField: type: string description: What a hit matched. enum: [message, display_name, email, alias] x-enum-varnames: [AdminSupportSearchFieldMessage, AdminSupportSearchFieldDisplayName, AdminSupportSearchFieldEmail, AdminSupportSearchFieldAlias] SupportSearchHighlight: type: object additionalProperties: false description: A matched range of the snippet text in UTF-16 code units (JavaScript string indexes), start inclusive, end exclusive. required: [start, end] properties: start: {type: integer, minimum: 0} end: {type: integer, minimum: 1} SupportSearchSnippet: type: object additionalProperties: false description: Plain text, never markup. truncated_start and truncated_end say the original continues before or after the excerpt. required: [text, highlights, truncated_start, truncated_end] properties: text: {type: string} highlights: type: array items: {"$ref": "#/components/schemas/SupportSearchHighlight"} truncated_start: {type: boolean} truncated_end: {type: boolean} SupportSearchPlayer: type: object additionalProperties: false required: [id, display_name, email] properties: id: {type: string, format: uuid} display_name: {type: string, nullable: true} email: {type: string} SupportSearchMessage: type: object additionalProperties: false required: [id, seq, sender_kind, created_at] properties: id: {type: string, format: uuid} seq: {type: integer, format: int64} sender_kind: {"$ref": "#/components/schemas/SupportSenderKind"} created_at: {type: string, format: date-time} AdminSupportSearchHit: type: object additionalProperties: false description: message is present only when field is message. required: [conversation_id, conversation_status, player, field, at, snippet] properties: conversation_id: {type: string, format: uuid} conversation_status: {"$ref": "#/components/schemas/SupportConversationStatus"} player: {"$ref": "#/components/schemas/SupportSearchPlayer"} field: {"$ref": "#/components/schemas/AdminSupportSearchField"} message: {"$ref": "#/components/schemas/SupportSearchMessage"} at: {type: string, format: date-time} snippet: {"$ref": "#/components/schemas/SupportSearchSnippet"} AdminSupportSearchResponse: type: object additionalProperties: false required: [hits] properties: hits: type: array items: {"$ref": "#/components/schemas/AdminSupportSearchHit"} next_cursor: {type: string} AdminSupportConversationSearchMatch: type: object additionalProperties: false required: [message, snippet] properties: message: {"$ref": "#/components/schemas/SupportSearchMessage"} snippet: {"$ref": "#/components/schemas/SupportSearchSnippet"} AdminSupportConversationSearchResponse: type: object additionalProperties: false required: [matches, total] properties: matches: type: array items: {"$ref": "#/components/schemas/AdminSupportConversationSearchMatch"} total: {type: integer, format: int64} next_cursor: {type: string} SupportMessageCommandResponse: type: object required: - conversation - message - effects properties: conversation: "$ref": "#/components/schemas/SupportConversation" message: "$ref": "#/components/schemas/SupportMessage" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" replayed: type: boolean SupportConversationCommandResponse: type: object required: - conversation - effects properties: conversation: "$ref": "#/components/schemas/SupportConversation" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" replayed: type: boolean SupportAttachmentUploadRequest: type: object additionalProperties: false required: [upload_id, filename, content_type, size_bytes, checksum_sha256] properties: upload_id: type: string format: uuid filename: type: string minLength: 1 maxLength: 255 content_type: type: string enum: [image/png, image/jpeg] size_bytes: type: integer format: int64 minimum: 1 maximum: 8388608 checksum_sha256: type: string pattern: '^[a-f0-9]{64}$' SupportAttachmentUploadResponse: type: object required: [id, upload_url, headers, expires_at] properties: id: type: string format: uuid upload_url: type: string headers: type: object additionalProperties: type: string expires_at: type: string format: date-time SupportSendMessageRequest: type: object required: - body_text additionalProperties: false properties: attachment_id: type: string format: uuid body_text: type: string minLength: 1 maxLength: 8000 client_message_id: type: string minLength: 1 nullable: true SupportMarkReadRequest: type: object required: - seq additionalProperties: false properties: seq: type: integer format: int64 minimum: 1 SupportTransitionRequest: type: object required: - expected_version additionalProperties: false properties: expected_version: type: integer format: int64 minimum: 1 resolution_note_text: type: string description: Optional admin-only note recorded when resolving a support conversation. maxLength: 2000 nullable: true SupportClaimRequest: type: object additionalProperties: false properties: takeover: type: boolean description: When true, forcibly take an active claim held by another admin. When false or omitted, an active foreign claim is left untouched. TransferDirection: type: string enum: - load - unload CashoutReviewState: type: string enum: [pending_review, approved, reject_restoring, rejected] x-enum-varnames: [CashoutReviewPending, CashoutReviewApproved, CashoutReviewRestoring, CashoutReviewRejected] CashoutReview: type: object required: [transfer_id, user_id, provider_account_id, provider_code, provider_username, player_name, player_email, state, provider_credits, debit_cents, payout_cents, withdrawable_cents, consumed_freeplay_cents, forfeit_cents, policy_revision, cycle_load_cents, system_payout_cents, acceptance_mode, accepted_credits_cents, quoted_at, created_at, updated_at] properties: transfer_id: {type: string, format: uuid} user_id: {type: string, format: uuid} provider_account_id: {type: string, format: uuid} provider_code: {"$ref": "#/components/schemas/ProviderCode"} provider_username: {type: string} player_name: {type: string} player_email: {type: string} player_alias: {type: string, nullable: true} state: {"$ref": "#/components/schemas/CashoutReviewState"} provider_credits: {type: integer, format: int64} debit_cents: {type: integer, format: int64} payout_cents: {type: integer, format: int64} withdrawable_cents: {type: integer, format: int64} consumed_freeplay_cents: {type: integer, format: int64} forfeit_cents: {type: integer, format: int64} policy_revision: {type: integer, format: int64} cycle_deposit_bonus_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus loaded in this cycle; excluded from redemption minimum and maximum.} cycle_cash_cents: {type: integer, format: int64, minimum: 0} cycle_withdrawable_cents: {type: integer, format: int64, minimum: 0} cycle_freeplay_cents: {type: integer, format: int64, minimum: 0} cycle_bonus_only_principal_cents: {type: integer, format: int64, minimum: 0} cycle_deposit_bonus_loaded_cents: {type: integer, format: int64, minimum: 0, description: Deposit bonus in completed loads this cycle; excludes Bonus-only principal and does not net credit moves.} cycle_total_cents: {type: integer, format: int64, minimum: 0} cycle_credits_not_loaded_cents: {type: integer, format: int64, minimum: 0, description: "Advisory only (ADR 0018, 2026-11-10): cash value of credits not loaded through the app that were already in the game when this cycle's first load was admitted, as its load preflight froze them; 0 when none. Never changes the quote."} cycle_load_cents: {type: integer, format: int64} system_payout_cents: {type: integer, format: int64} acceptance_mode: {"$ref": "#/components/schemas/CashoutAcceptanceMode"} accepted_credits_cents: {type: integer, format: int64, minimum: 0, description: Cents of game value accepted by the quote's acceptance mode; 0 for normal.} quoted_at: {type: string, format: date-time} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} decision_actor_id: {type: string, format: uuid, nullable: true} decision_reason: {type: string, nullable: true} restoration_transfer_id: {type: string, format: uuid, nullable: true} restoration_state: nullable: true allOf: [{"$ref": "#/components/schemas/ProviderTransferState"}] CashoutReviewList: type: object required: [reviews] properties: reviews: type: array items: {"$ref": "#/components/schemas/CashoutReview"} CashoutReviewDecisionRequest: type: object additionalProperties: false required: [reason] properties: reason: {type: string, minLength: 3, maxLength: 500} CashoutReviewSettings: type: object required: [require_review, review_unrecorded_credits, revision, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} require_review: {type: boolean, description: 'Game cash-outs require review. Default ON; applies to newly issued player quotes.'} review_unrecorded_credits: {type: boolean, description: 'Cash-outs that pay game credits PlayGo never loaded go to review, independent of require_review. Default ON; applies to newly issued player quotes.'} revision: {type: integer, format: int64} updated_at: {type: string, format: date-time} updated_by: {type: string, format: uuid, nullable: true} CashoutReviewSettingsRequest: type: object additionalProperties: false required: [require_review, review_unrecorded_credits, expected_revision, reason] properties: require_review: {type: boolean} review_unrecorded_credits: {type: boolean} expected_revision: {type: integer, format: int64, minimum: 1} reason: {type: string, minLength: 3, maxLength: 500} CashoutReviewSettingEvent: type: object required: [revision, previous_require_review, require_review, previous_review_unrecorded_credits, review_unrecorded_credits, actor_id, reason, created_at] properties: revision: {type: integer, format: int64} previous_require_review: {type: boolean} require_review: {type: boolean} previous_review_unrecorded_credits: {type: boolean, nullable: true, description: Null when the event predates the unrecorded-credit review setting.} review_unrecorded_credits: {type: boolean, nullable: true, description: Null when the event predates the unrecorded-credit review setting.} actor_id: {type: string, format: uuid} reason: {type: string} created_at: {type: string, format: date-time} CashoutReviewSettingsHistory: type: object required: [events] properties: events: type: array items: {"$ref": "#/components/schemas/CashoutReviewSettingEvent"} ProviderTransferState: type: string enum: - requested - wallet_debited - provider_requesting - pending_review - approved - reject_restoring - completed - rejected - unknown_requires_reconcile - failed_internal x-enum-varnames: - ProviderTransferStateRequested - ProviderTransferStateWalletDebited - ProviderTransferStateProviderRequesting - ProviderTransferStatePendingReview - ProviderTransferStateApproved - ProviderTransferStateRejectRestoring - ProviderTransferStateCompleted - ProviderTransferStateRejected - ProviderTransferStateUnknownRequiresReconcile - ProviderTransferStateFailedInternal CreateProviderTransferRequest: type: object description: Request uses USD cents as command input; persistence stores DB numeric(22,4) cash_amount and DB-computed provider_credits through the provider amount policy. For LOAD, amount_cents is required. For UNLOAD it is optional and IGNORED — a cashout is a full-balance settlement whose payout the server computes from balance and cycle-loaded credits. required: - provider_account_id additionalProperties: false properties: bonus_only_cashout_consent: {type: boolean, description: "Required true for Bonus-only terminal cash-out together with the fresh shown preflight_token. Confirms principal and excess forfeiture; never substitutes for matching balance/cycle/policy evidence."} preflight_token: {type: string, format: uuid, description: Required for every player load; binds amount, allocation and explicit freeplay consent. Optional for guided normal cashout confirmation bound to the shown balance cycle and policy.} provider_account_id: type: string format: uuid game_id: type: string nullable: true amount_cents: type: integer format: int64 minimum: 1 ProviderCreditMoveDestination: type: object required: [provider_account_id, provider_credits] properties: provider_account_id: type: string format: uuid provider_credits: type: integer format: int64 ProviderCreditMoveOptionsResponse: type: object required: [destinations] properties: recent_move: "$ref": "#/components/schemas/ProviderCreditMove" source_credits: type: integer format: int64 description: Whole provider credits that will move. value_cents: type: integer format: int64 destinations: type: array items: "$ref": "#/components/schemas/ProviderCreditMoveDestination" CreateProviderCreditMoveRequest: type: object additionalProperties: false required: [source_account_id, destination_account_id, expected_source_credits] properties: source_account_id: type: string format: uuid destination_account_id: type: string format: uuid expected_source_credits: type: integer format: int64 minimum: 1 ProviderCreditMove: type: object required: [id, source_account_id, destination_account_id, source_credits, destination_credits, state, reconciliation_required, created_at] properties: id: type: string format: uuid source_account_id: type: string format: uuid destination_account_id: type: string format: uuid source_credits: type: integer format: int64 destination_credits: type: integer format: int64 state: type: string enum: [requested, source_requesting, source_debited, destination_requesting, compensating_source, completed, rejected, compensated, needs_reconcile] reconciliation_required: type: boolean created_at: type: string format: date-time completed_at: type: string format: date-time nullable: true ProviderCreditMoveResponse: type: object required: [move, effects] properties: move: "$ref": "#/components/schemas/ProviderCreditMove" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" CashoutAcceptanceMode: type: string description: Source of the accepted game value; normal uses recorded-load policy. Acceptance never replaces fresh-read and verified-zero settlement. enum: [normal, linked_credits_accepted, unrecorded_credits_accepted] x-enum-varnames: - CashoutAcceptanceModeNormal - CashoutAcceptanceModeLinkedCreditsAccepted - CashoutAcceptanceModeUnrecordedCreditsAccepted CashoutBreakdown: type: object required: [mode, accepted_credits_cents, balance_cents, limit_cents, paid_cents, not_paid_cents, policy_revision, freeplay_winnings_percent] description: Frozen cashout audit facts. paid_cents and not_paid_cents are actual wallet payout and forfeit. Historical rows derive these from issued approval and immutable transfer freeplay source; new rows use frozen actual audit fields. Never recomputed from current policy or balance. properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only source terms and server-calculated cash-out progress.} paid_load_cents: {type: integer, format: int64, minimum: 0} deposit_bonus_load_cents: {type: integer, format: int64, minimum: 0} mode: {"$ref": "#/components/schemas/CashoutAcceptanceMode"} accepted_credits_cents: {type: integer, format: int64, minimum: 0, description: Whole USD cents accepted from existing credits outside the current recorded-load policy. Frozen for an issued audit; zero in normal mode.} balance_cents: {type: integer, format: int64} limit_cents: {type: integer, format: int64} paid_cents: {type: integer, format: int64} not_paid_cents: {type: integer, format: int64} policy_revision: {type: integer, format: int64} freeplay_winnings_percent: {type: integer, format: int64, nullable: true} ProviderLoadConflict: type: object additionalProperties: false required: [error] properties: error: {"$ref": "#/components/schemas/APIError"} AdminWalletLoadReasonCode: type: string enum: [staff_load, player_request, support_assistance, account_correction, other] description: Private staff audit reason; never exposed in player history. StaffAccountCreateOptions: type: object additionalProperties: false required: [options] properties: options: type: array items: {"$ref": "#/components/schemas/StaffAccountCreateOption"} StaffAccountCreateOption: type: object additionalProperties: false required: [game_id, game_name, provider_code, expected_slot, action] properties: game_id: {type: string} game_name: {type: string} provider_code: {"$ref": "#/components/schemas/ProviderCode"} expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} action: {"$ref": "#/components/schemas/InteractionAction"} StaffAccountCreateRequest: type: object additionalProperties: false required: [game_id, expected_slot] properties: game_id: {type: string, minLength: 1} expected_slot: {"$ref": "#/components/schemas/ProviderSlotExpected"} StaffAccountCreateResult: type: object additionalProperties: false required: [id, user_id, provisioning_id, provider_code, state, account_id, username, credential_saved, replayed, poll_interval_ms, effects] properties: id: {type: string, format: uuid} user_id: {type: string, format: uuid} provisioning_id: {type: string, format: uuid} provider_code: {"$ref": "#/components/schemas/ProviderCode"} state: {"$ref": "#/components/schemas/ProviderAccountProvisioningState"} account_id: {type: string, format: uuid, nullable: true} username: {type: string} credential_saved: {type: boolean, description: True only when the current native-created credential is stored in the vault. Does not expose the credential.} replayed: {type: boolean} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} poll_interval_ms: {type: integer, format: int32, minimum: 0} StaffWalletUnloadRequest: type: object additionalProperties: false required: [preview_token, expected_balance_credits] properties: preview_token: {type: string, format: uuid} expected_balance_credits: {type: integer, format: int64, minimum: 1} AdminWalletGameLoadRequest: type: object required: [amount_cents, preflight_token, reason_code, note] properties: amount_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} preflight_token: {type: string, format: uuid} reason_code: {"$ref": "#/components/schemas/AdminWalletLoadReasonCode"} note: {type: string, minLength: 3, maxLength: 500} AdminWalletGameLoadOptions: type: object required: [user_id, player_label, provider_account_id, provider_code, playable_cash, freeplay, withdrawable_cash, deposit_bonus, load_increment_cents, can_load] properties: user_id: {type: string, format: uuid} player_label: {type: string} provider_account_id: {type: string, format: uuid} provider_code: {"$ref": "#/components/schemas/ProviderCode"} playable_cash: {"$ref": "#/components/schemas/MoneyAmount"} freeplay: {"$ref": "#/components/schemas/MoneyAmount"} withdrawable_cash: {"$ref": "#/components/schemas/MoneyAmount"} deposit_bonus: {"$ref": "#/components/schemas/MoneyAmount"} load_increment_cents: {type: integer, format: int64, minimum: 1} can_load: {type: boolean} disabled_reason: {type: string} MixedLoadDialogObservation: type: object additionalProperties: false required: [event, preview_id, view_id, sequence] properties: event: type: string enum: [mixed_load_dialog_shown, mixed_load_dialog_choice] preview_id: type: string format: uuid view_id: type: string format: uuid sequence: type: integer minimum: 0 maximum: 60 choice: type: string enum: [give_up, cash_out, cancel, other_game] oneOf: - properties: event: {enum: [mixed_load_dialog_shown]} sequence: {maximum: 0} not: {required: [choice]} - required: [choice] properties: event: {enum: [mixed_load_dialog_choice]} sequence: {minimum: 1} LoadPreflightRequest: type: object additionalProperties: false required: [provider_account_id, amount_cents] properties: prefer_freeplay: {type: boolean, description: "Explicitly select the existing Free Play path instead of new Bonus-only funding when both are available. Never mixes Free Play with Deposit bonus; the issued token freezes the selected source."} bonus_only_consent: {type: boolean, description: "Consent to exactly the shown Bonus-only principal, minimum, maximum and terminal forfeiture terms. Separate from Free Play consent; confirmation returns an immutable consented token."} preflight_token: {type: string, format: uuid, description: Shown token required when confirming freeplay consent.} freeplay_consent: {type: boolean, description: True confirms exactly the unchanged terms of the shown token and mints a new immutable consented token.} provider_account_id: {type: string, format: uuid} amount_cents: {type: integer, format: int64, minimum: 1} ClearBalanceRequest: type: object additionalProperties: false required: [provider_account_id, preflight_token] properties: provider_account_id: {type: string, format: uuid} preflight_token: {type: string, format: uuid} ProviderLoadReason: type: string description: Stable load-admission reason. For transfer_in_progress, error.message or refusal_reason describes the existing work. An outcome-unknown load states that confirmation is pending, includes its proven original reserved amount, and asks the player not to submit another load; clients preserve this message rather than replacing it with generic wait-and-retry copy. enum: [ok, bonus_recovery_required, bonus_requires_paid_cash, insufficient_cash, insufficient_freeplay, freeplay_in_game, real_in_game, withdrawable_not_loadable, invalid_increment, load_preflight_stale, bonus_only_consent_required, insufficient_bonus, bonus_interval, bonus_elsewhere, freeplay_consent_required, load_preflight_required, freeplay_resolution_required, transfer_in_progress, first_unload_review_pending, balance_read_canceled, balance_read_timeout, balance_read_deferred, balance_read_configuration, balance_read_unsupported, balance_read_database, balance_read_stale, balance_read_conflict, balance_read_decode, balance_read_auth, balance_read_transport, balance_read_upstream, balance_read_invalid_account, balance_read_credentials_rejected, balance_read_unknown] x-enum-varnames: - ProviderLoadReasonOk - ProviderLoadReasonBonusRecoveryRequired - ProviderLoadReasonBonusRequiresPaidCash - ProviderLoadReasonInsufficientCash - ProviderLoadReasonInsufficientFreeplay - ProviderLoadReasonFreeplayInGame - ProviderLoadReasonRealInGame - ProviderLoadReasonWithdrawableNotLoadable - ProviderLoadReasonInvalidIncrement - ProviderLoadReasonLoadPreflightStale - ProviderLoadReasonBonusOnlyConsentRequired - ProviderLoadReasonInsufficientBonus - ProviderLoadReasonBonusInterval - ProviderLoadReasonBonusElsewhere - ProviderLoadReasonFreeplayConsentRequired - ProviderLoadReasonLoadPreflightRequired - ProviderLoadReasonFreeplayResolutionRequired - ProviderLoadReasonTransferInProgress - ProviderLoadReasonFirstUnloadReviewPending - ProviderLoadReasonBalanceReadCanceled - ProviderLoadReasonBalanceReadTimeout - ProviderLoadReasonBalanceReadDeferred - ProviderLoadReasonBalanceReadConfiguration - ProviderLoadReasonBalanceReadUnsupported - ProviderLoadReasonBalanceReadDatabase - ProviderLoadReasonBalanceReadStale - ProviderLoadReasonBalanceReadConflict - ProviderLoadReasonBalanceReadDecode - ProviderLoadReasonBalanceReadAuth - ProviderLoadReasonBalanceReadTransport - ProviderLoadReasonBalanceReadUpstream - ProviderLoadReasonBalanceReadInvalidAccount - ProviderLoadReasonBalanceReadCredentialsRejected - ProviderLoadReasonBalanceReadUnknown FreeplayBalanceQuote: type: object additionalProperties: false required: [winnings_cents, payout_cents] properties: winnings_cents: {type: integer, format: int64} payout_cents: {type: integer, format: int64} PendingProviderLoad: type: object additionalProperties: false description: Current-player pending load that blocks another load; original amount and time, never the new draft. Display metadata grants no settlement authority. required: [transfer_id, provider_account_id, provider_code, game_name, amount_cents, created_at, state, explanation, next_step] properties: transfer_id: {type: string, format: uuid} provider_account_id: {type: string, format: uuid} provider_code: {$ref: "#/components/schemas/ProviderCode"} game_name: {type: string} amount_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} created_at: {type: string, format: date-time} state: {$ref: "#/components/schemas/ProviderTransferState"} explanation: {type: string, description: Server-owned explanation of the original pending load.} next_step: {type: string, description: Server-owned next step; never authority to repeat or settle a load.} WalletSourceReview: type: object additionalProperties: false required: [source, before_cents, amount_cents, after_cents] properties: source: {type: string, enum: [cash, withdrawable_cash, deposit_bonus, freeplay]} before_cents: {type: integer, format: int64} amount_cents: {type: integer, format: int64, description: Signed wallet debit; negative means wallet credit.} after_cents: {type: integer, format: int64} LoadPreflight: type: object additionalProperties: false required: [refusal_reason,deposit_bonus_dust_cents,deposit_bonus_cents, deposit_bonus_balance_cents, paid_load_cents, max_redemption_after_load_cents, withdrawable_cents, block_withdrawable_loads, amount_cents, cash_balance_cents, campaign_bonus_cents, game_load_cents, preflight_token, freeplay_in_game, balance_credits, cashout_eligible, min_cashout_cents, policy_revision, expires_at, allowed, reason, threshold_cents, cash_cents, freeplay_cents, cycle_kind, freeplay_usable, freeplay_unusable_reason, uses_freeplay, requires_confirmation, percent_bps, cash_only_load_cents, quote, cashout_confirm_token, clear_balance_token, freeplay_consent] properties: bonus_only_available_cents: {type: integer, format: int64, minimum: 0, description: "Server-calculated whole-credit Bonus amount available for the permitted load path. The client never rounds wallet Bonus itself."} bonus_only_consent: {type: boolean, description: "Consent to exactly the shown Bonus-only principal, minimum, maximum and terminal forfeiture terms. Separate from Free Play consent; confirmation returns an immutable consented token."} bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only source terms and server-calculated cash-out progress.} wallet_review: {type: array, items: {"$ref": "#/components/schemas/WalletSourceReview"}} refusal_reason: {type: string, description: Server-owned safe refusal explanation, including SQL-computed paid-cash shortfall and valid load alternative. Empty when allowed.} pending_load: {$ref: "#/components/schemas/PendingProviderLoad"} deposit_bonus_dust_cents: {type: integer, format: int64, minimum: 0, description: Un-loadable remainder consumed by the final paid load; separately audited and refunded on a failed load.} deposit_bonus_cents: {type: integer, format: int64, minimum: 0, description: Exact deposit-bonus allocation, excluded from paid minimum and cap bases.} deposit_bonus_balance_cents: {type: integer, format: int64, minimum: 0} paid_load_cents: {type: integer, format: int64, minimum: 0, description: Paid cash plus allowed withdrawable allocation.} max_redemption_after_load_cents: {type: integer, format: int64, minimum: 0, description: SQL-computed base limit after this allocation, based only on paid cycle principal.} deposit_bonus_load_share_bps: {type: integer, format: int64, minimum: 0, maximum: 9900, description: "Bonus share per load of the policy revision this preview used (ADR 0066); 0 when the limit is off. The player sheet shows the base-limit note only when this is positive and Deposit bonus is used."} withdrawable_cents: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991, description: Exact Cash out Amount funding selected after Playable Cash.} block_withdrawable_loads: {type: boolean, description: Frozen audited load policy for this preview.} allowed: {type: boolean} emulation_reason: {"$ref": "#/components/schemas/EmulationRefusalReason"} reason: {"$ref": "#/components/schemas/ProviderLoadReason"} threshold_cents: {type: integer, format: int64, minimum: 0} cash_cents: {type: integer, format: int64, minimum: 0} freeplay_cents: {type: integer, format: int64, minimum: 0, description: Wallet freeplay allocation excluding campaign bonus.} cycle_kind: {$ref: "#/components/schemas/CycleKind"} freeplay_usable: {type: boolean} freeplay_unusable_reason: {type: string, nullable: true, enum: [cash_at_or_above_threshold]} uses_freeplay: {type: boolean} requires_confirmation: {type: boolean} freeplay_consent: {type: boolean} percent_bps: {type: integer, format: int64, minimum: 0, maximum: 10000} cash_only_load_cents: {type: integer, format: int64, nullable: true, description: SQL-computed valid whole-credit cash-only alternative without wallet freeplay or campaign bonus. Request a fresh preflight for this amount.} quote: {"$ref": "#/components/schemas/FreeplayBalanceQuote"} cashout_confirm_token: {type: string, format: uuid, nullable: true} clear_balance_token: {type: string, format: uuid, nullable: true} cycle_conflict: {$ref: "#/components/schemas/LoadCycleConflict", description: "ADR 0059. Omitted unless the load is refused because its payout rules differ from the game's current cycle. Frozen with this preflight token."} amount_cents: {type: integer, format: int64} cash_balance_cents: {type: integer, format: int64, description: Actual Cash Balance, excluding freeplay and Withdrawable Cash.} campaign_bonus_cents: {type: integer, format: int64} game_load_cents: {type: integer, format: int64, description: Total game load including campaign bonus.} preflight_token: {type: string, format: uuid} freeplay_in_game: {type: boolean, description: "Positive unresolved freeplay or imported mixed principal that blocks this load; guided cashout or Clear Balance must resolve it. False for a free-play top-up of the same free-play cycle (the player has usable wallet free play), including one refused for another reason."} balance_credits: {type: integer, format: int64} cashout_eligible: {type: boolean} min_cashout_cents: {type: integer, format: int64} policy_revision: {type: integer, format: int64} expires_at: {type: string, format: date-time} LoadCycleConflict: type: object additionalProperties: false description: "ADR 0059. Server-computed facts for the conflict explainer: what is in this game, under which rule, and the ways forward. Clients do no money arithmetic." required: [current_kind, incoming_kind, game_name, balance_cents, cash_out, give_up, other_games] properties: current_kind: {$ref: "#/components/schemas/CycleKind", description: Payout rule of the money already in this game.} incoming_kind: {$ref: "#/components/schemas/CycleKind", description: "Payout rule of the refused load, including a Bonus-only start (ADR 0059 amendment 2026-11-16)."} game_name: {type: string} balance_cents: {type: integer, format: int64, minimum: 1, description: Verified game balance in cents.} cash_out: {$ref: "#/components/schemas/LoadCycleConflictCashOut"} give_up: {$ref: "#/components/schemas/LoadCycleConflictGiveUp"} other_games: {type: array, maxItems: 6, description: "Games the player already has an account in that should take this money now, empty games first. When this is empty, offer games without an account from GET /api/v1/games (actions.add.enabled).", items: {$ref: "#/components/schemas/LoadCycleConflictGame"}} LoadCycleConflictCashOut: type: object additionalProperties: false description: The existing cash-out quote for this game, frozen with the preflight. The cash-out itself runs through the ordinary cash-out flow and its own fresh quote. required: [eligible, pays_cents, not_paid_cents, minimum_cents, needs_more_cents, needs_more_basis, review_applies] properties: eligible: {type: boolean} pays_cents: {type: integer, format: int64, minimum: 0, description: Paid to Cash out Amount when eligible; zero otherwise.} not_paid_cents: {type: integer, format: int64, minimum: 0} minimum_cents: {type: integer, format: int64, minimum: 0, description: "Minimum balance for paid cash and Free Play; minimum net winnings for Bonus-only."} needs_more_cents: {type: integer, format: int64, minimum: 0, description: "How much more balance (paid cash, Free Play) or net winnings (Bonus-only) cash-out needs. Zero when eligible."} needs_more_basis: {$ref: "#/components/schemas/CycleConflictNeedsMoreBasis"} review_applies: {type: boolean, description: Staff review holds the payout before it reaches Cash out Amount.} CycleKind: type: string description: Payout rule of a game cycle (ADR 0027, ADR 0051). enum: [cash, freeplay, bonus_only] x-enum-varnames: [CycleKindCash, CycleKindFreeplay, CycleKindBonusOnly] CycleConflictNeedsMoreBasis: type: string description: "What needs_more_cents measures: more game balance (paid cash, Free Play) or more net winnings (Bonus-only)." enum: [balance, net_winnings] x-enum-varnames: [CycleConflictNeedsMoreBasisBalance, CycleConflictNeedsMoreBasisNetWinnings] LoadCycleConflictGiveUp: type: object additionalProperties: false description: "A give-up never waits for staff review and never starts the Bonus interval (ADR 0059)." required: [allowed, gives_up_cents, clear_balance_token] properties: allowed: {type: boolean, description: "False whenever cash-out is eligible; then offer cash-out, keep playing or another game. Send clear_balance_token to POST /api/v1/provider-transfers/clear-balance."} gives_up_cents: {type: integer, format: int64, minimum: 1, description: The whole game balance; nothing is paid.} clear_balance_token: {type: string, format: uuid, nullable: true} LoadCycleConflictGame: type: object additionalProperties: false required: [provider_account_id, provider_code, game_name, empty] properties: provider_account_id: {type: string, format: uuid} provider_code: {$ref: "#/components/schemas/ProviderCode"} game_name: {type: string} empty: {type: boolean, description: "True when the game's last observed balance is zero; false for a game already playing paid cash outside a Bonus-only cycle. The one-tap load runs the ordinary fresh preflight."} ProviderTransfer: type: object required: - cashout_breakdown - id - user_id - provider_account_id - provider_code - direction - direction_label - state - state_label - cash_amount - provider_credits - external_order_id - reconciliation_required - poll - created_at - updated_at properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only source terms and server-calculated cash-out progress.} loaded_by_staff: {type: boolean, description: Staff initiated this normal player-wallet load. Private reason and note are never exposed.} failure_reason: {type: string, enum: [agent_balance_low], nullable: true, description: Typed definite load refusal; no inference from timeouts.} source_deposit_bonus_dust_cents: {type: integer, format: int64, minimum: 0} source_deposit_bonus_cents: {type: integer, format: int64, minimum: 0} paid_load_cents: {type: integer, format: int64, minimum: 0} restores_cashout_id: type: string format: uuid nullable: true description: Original cash-out whose credits this holding-funded load restores. It does not debit a wallet. cashout_withdrawable_cents: type: integer format: int64 nullable: true description: Quoted withdrawable allocation while unsettled; actual ledger-posted withdrawable amount once completed or approved. Pending review is not spendable. source_cash_cents: {type: integer, format: int64} source_freeplay_cents: {type: integer, format: int64, description: Freeplay debited from the player wallet; excludes campaign bonus.} campaign_bonus_cents: {type: integer, format: int64} game_load_cents: {type: integer, format: int64, description: Total game load including campaign bonus.} cashout_breakdown: nullable: true allOf: - "$ref": "#/components/schemas/CashoutBreakdown" id: type: string format: uuid user_id: type: string format: uuid provider_account_id: type: string format: uuid provider_code: "$ref": "#/components/schemas/ProviderCode" direction: "$ref": "#/components/schemas/TransferDirection" direction_label: type: string state: "$ref": "#/components/schemas/ProviderTransferState" state_label: type: string cash_amount: "$ref": "#/components/schemas/MoneyAmount" campaign_bonus_amount: "$ref": "#/components/schemas/MoneyAmount" player_paid_amount: "$ref": "#/components/schemas/MoneyAmount" provider_credits: description: API presentation value normalized from DB-owned numeric(22,4) provider_credits. type: integer format: int64 external_order_id: type: string evidence: nullable: true allOf: - "$ref": "#/components/schemas/RedactedEvidenceSummary" reconciliation_required: type: boolean operator_load_resolution_available: type: boolean description: Candidate for superadmin not-applied resolution. The command still validates the locked state and original source reservation; this flag is not evidence of a provider failure. poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" created_at: type: string format: date-time updated_at: type: string format: date-time ProviderTransferResponse: type: object required: - transfer - effects properties: transfer: "$ref": "#/components/schemas/ProviderTransfer" wallet: description: Authoritative post-op wallet snapshot (cash balance) for optimistic cache apply; present once the transfer settles synchronously. nullable: true allOf: - "$ref": "#/components/schemas/WalletSnapshot" provider_account: description: Authoritative post-op provider-account snapshot (fresh balance + cashout sub-object) for optimistic cache apply. nullable: true allOf: - "$ref": "#/components/schemas/ProviderAccount" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" RedemptionLogStatus: type: string enum: [completed, held_for_review, approved, rejected, failed, unknown] x-enum-varnames: [RedemptionLogCompleted, RedemptionLogHeld, RedemptionLogApproved, RedemptionLogRejected, RedemptionLogFailed, RedemptionLogUnknown] RedemptionForfeitReason: type: string enum: [cap, freeplay, cap_and_freeplay, clear_balance, operator_override, recorded_forfeit] x-enum-varnames: [RedemptionForfeitCap, RedemptionForfeitFreeplay, RedemptionForfeitCapAndFreeplay, RedemptionForfeitClearBalance, RedemptionForfeitOverride, RedemptionForfeitRecorded] RedemptionLogRow: type: object required: [transfer_id, created_at, user_id, player_name, player_email, provider_code, provider_credits, credited_cents, forfeited_cents, forfeit_reason, percent_bps, status, reviewed_by, decision_reason] properties: transfer_id: {type: string, format: uuid} created_at: {type: string, format: date-time} user_id: {type: string, format: uuid} player_name: {type: string} player_email: {type: string} provider_code: {"$ref": "#/components/schemas/ProviderCode"} provider_credits: {type: integer, format: int64, minimum: 0, nullable: true, description: Known removed game credits; null for unresolved provider outcomes. Rejected rows retain the initial removal; restoration is identified by status and detail.} credited_cents: {type: integer, format: int64, minimum: 0, description: Recorded spendable wallet credit from the settlement journal; zero while held or unresolved.} forfeited_cents: {type: integer, format: int64, minimum: 0, description: Recorded system forfeit posting; zero before final settlement.} forfeit_reason: nullable: true allOf: [{"$ref": "#/components/schemas/RedemptionForfeitReason"}] percent_bps: {type: integer, format: int64, minimum: 0, maximum: 10000, nullable: true, description: Frozen free-play winnings share; never current policy or an assumed percentage.} status: {"$ref": "#/components/schemas/RedemptionLogStatus"} reviewed_by: {type: string, nullable: true} decision_reason: {type: string, nullable: true} RedemptionLogTotals: type: object required: [count, provider_credits, credited_cents, forfeited_cents, unresolved_count] properties: count: {type: integer, format: int64, minimum: 0} provider_credits: {type: integer, format: int64, minimum: 0, description: Sum of known removed credits; unresolved values excluded.} credited_cents: {type: integer, format: int64, minimum: 0} forfeited_cents: {type: integer, format: int64, minimum: 0} unresolved_count: {type: integer, format: int64, minimum: 0} RedemptionGameTotals: type: object required: [provider_code, totals] properties: provider_code: {"$ref": "#/components/schemas/ProviderCode"} totals: {"$ref": "#/components/schemas/RedemptionLogTotals"} PlayerRedemptionSummary: type: object required: [lifetime, last_30_days, top_games] properties: lifetime: {"$ref": "#/components/schemas/RedemptionLogTotals"} last_30_days: {"$ref": "#/components/schemas/RedemptionLogTotals"} top_games: {type: array, items: {"$ref": "#/components/schemas/RedemptionGameTotals"}} RedemptionLogPage: type: object required: [rows, totals, next_cursor, games] properties: player_summary: {"$ref": "#/components/schemas/PlayerRedemptionSummary"} rows: {type: array, items: {"$ref": "#/components/schemas/RedemptionLogRow"}} totals: {"$ref": "#/components/schemas/RedemptionLogTotals"} next_cursor: {type: string, nullable: true} games: {type: array, items: {"$ref": "#/components/schemas/ProviderCode"}} ProviderTransfersResponse: type: object required: - transfers - pagination properties: redemption_log: "$ref": "#/components/schemas/RedemptionLogPage" transfers: type: array items: "$ref": "#/components/schemas/ProviderTransfer" pagination: "$ref": "#/components/schemas/Pagination" PaymentDepositState: type: string enum: - requested - player_pending - kyc_required - checkout_created - provider_created - succeeded - failed - stale_pending - unknown_requires_reconcile - failed_internal - voided - reversed - superseded - abandoned PaymentDepositTier: description: 'Operator triage classification of how far a deposit progressed: completed (money landed), in_progress (player acted past checkout), needs_review (failed or requires reconciliation), abandoned (never progressed past checkout creation). ' type: string enum: - completed - in_progress - needs_review - abandoned PaymentDepositProviderCode: type: string enum: - thesolar - mockpay - dollarpay - xxpay - finix - nowpayments - rocketramp - manual PaymentAccountSetupState: type: string enum: - not_created - active - pending - kyc_required - blocked - rejected - inactive - review_required PaymentFlow: type: string enum: - hosted_checkout - direct_saved_method x-enum-varnames: - PaymentFlowHostedCheckout - PaymentFlowDirectSavedMethod PaymentTokenizationEnvironment: type: string enum: - sandbox - prod x-enum-varnames: - PaymentTokenizationEnvironmentSandbox - PaymentTokenizationEnvironmentProd PaymentTokenizationConfig: type: object required: - environment - application_id - sdk_url - sdk_version properties: environment: "$ref": "#/components/schemas/PaymentTokenizationEnvironment" application_id: type: string minLength: 1 sdk_url: type: string format: uri sdk_version: type: string minLength: 1 SavedPaymentSource: type: object required: - kind - payment_method_id additionalProperties: false properties: kind: type: string enum: - saved_payment_method x-enum-varnames: - SavedPaymentSourceKindSavedPaymentMethod payment_method_id: type: string format: uuid NewPaymentMethodSource: type: object required: - kind - provider_token additionalProperties: false properties: kind: type: string enum: - new_payment_method x-enum-varnames: - NewPaymentMethodSourceKindNewPaymentMethod provider_token: type: string minLength: 3 writeOnly: true PaymentSource: discriminator: propertyName: kind mapping: saved_payment_method: "#/components/schemas/SavedPaymentSource" new_payment_method: "#/components/schemas/NewPaymentMethodSource" oneOf: - "$ref": "#/components/schemas/SavedPaymentSource" - "$ref": "#/components/schemas/NewPaymentMethodSource" CreatePaymentDepositRequest: type: object required: - provider_code - amount_option_ref - payment_method_ref additionalProperties: false properties: provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" amount_option_ref: type: string minLength: 1 payment_method_ref: type: string minLength: 1 payment_source: "$ref": "#/components/schemas/PaymentSource" PaymentMethodState: type: string enum: - active - removal_pending - removed x-enum-varnames: - PaymentMethodStateActive - PaymentMethodStateRemovalPending - PaymentMethodStateRemoved PaymentMethodKind: type: string enum: - card x-enum-varnames: - PaymentMethodKindCard PaymentMethod: type: object required: - id - provider_code - kind - brand - last_four - expiration_month - expiration_year - state - created_at - updated_at properties: id: type: string format: uuid provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" kind: "$ref": "#/components/schemas/PaymentMethodKind" brand: type: string minLength: 1 last_four: type: string pattern: '^[0-9]{4}$' expiration_month: type: integer minimum: 1 maximum: 12 expiration_year: type: integer minimum: 1 cardholder_name: type: string nullable: true state: "$ref": "#/components/schemas/PaymentMethodState" last_used_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time PaymentMethodsResponse: type: object required: - payment_methods properties: payment_methods: type: array items: "$ref": "#/components/schemas/PaymentMethod" PaymentMethodResponse: type: object required: - payment_method - effects properties: payment_method: "$ref": "#/components/schemas/PaymentMethod" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" PaymentDepositFailure: type: object required: [reason, provider_status, provider_message, message] properties: reason: type: string enum: [card_declined, insufficient_funds, authentication_failed, provider_rejected] x-enum-varnames: [DepositFailureCardDeclined, DepositFailureInsufficientFunds, DepositFailureAuthenticationFailed, DepositFailureProviderRejected] provider_status: {type: string, description: Redacted documented provider status code.} provider_message: {type: string, description: Safe canonical provider diagnostic; never raw payload text.} message: {type: string, description: Server-owned plain player guidance.} PaymentDeposit: type: object required: - id - user_id - provider_code - state - amount - currency_code - amount_option_ref - payment_method_ref - created_at - updated_at properties: failure: nullable: true allOf: - "$ref": "#/components/schemas/PaymentDepositFailure" id: type: string format: uuid user_id: type: string format: uuid provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" state: "$ref": "#/components/schemas/PaymentDepositState" amount: description: API presentation cents derived from DB numeric(22,4) payment amount. type: integer format: int64 credited_amount: description: Actual cash credit in integer cents from the immutable settlement journal. Included by the player detail endpoint after a wallet credit exists; includes any house subsidy. type: integer format: int64 nullable: true currency_code: "$ref": "#/components/schemas/CurrencyCode" amount_option_ref: type: string payment_method_ref: type: string checkout_url: type: string nullable: true kyc_link: type: string nullable: true provider_transaction_id: type: string nullable: true stale_after: type: string format: date-time nullable: true wallet_credit_transaction_id: type: string format: uuid nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time PaymentDepositAmountOption: type: object required: - ref - amount - credited_amount - currency_code - label properties: ref: type: string amount: type: integer format: int64 description: Paid deposit principal in USD cents. credited_amount: type: integer format: int64 minimum: 1 description: Backend-computed wallet credit in USD cents, including any house subsidy. currency_code: "$ref": "#/components/schemas/CurrencyCode" label: type: string DepositMethodKind: type: string enum: - cash_app - chime - card - apple_pay - google_pay - crypto - wallet x-enum-varnames: - DepositMethodKindCashApp - DepositMethodKindChime - DepositMethodKindCard - DepositMethodKindApplePay - DepositMethodKindGooglePay - DepositMethodKindCrypto - DepositMethodKindWallet PaymentDepositMethodOption: type: object required: - id - display_name - method_kinds - recommended - minimum_amount - amounts - account_setup_state - flow - routing - automatic_routing properties: automatic_routing: type: boolean description: Server-owned eligibility for combining this option with other automatically routed options for the selected method. False options retain ordinary provider selection. id: type: string minLength: 1 display_name: type: string method_kinds: description: User-facing deposit methods this provider option supports. Consumers must use these values instead of inferring methods from labels, routing codes, or amount minimums. type: array minItems: 1 uniqueItems: true items: "$ref": "#/components/schemas/DepositMethodKind" recommended: description: Backend-owned preferred option when multiple provider options support the same method kind. Consumers should not display preference UI when there is no overlap. type: boolean default: false featured: type: boolean default: false minimum_amount: type: integer format: int64 minimum: 1 amounts: type: array minItems: 1 items: "$ref": "#/components/schemas/PaymentDepositAmountOption" amount_range: description: Optional whole-dollar amount range accepted in addition to quick picks. "$ref": "#/components/schemas/PaymentDepositAmountRange" account_setup_state: "$ref": "#/components/schemas/PaymentAccountSetupState" flow: "$ref": "#/components/schemas/PaymentFlow" tokenization: nullable: true allOf: - "$ref": "#/components/schemas/PaymentTokenizationConfig" routing: "$ref": "#/components/schemas/PaymentDepositRouting" PaymentDepositAmountRange: type: object required: [minimum_amount, maximum_amount, step_amount] properties: minimum_amount: type: integer format: int64 minimum: 1 maximum_amount: type: integer format: int64 minimum: 1 step_amount: type: integer format: int64 minimum: 1 PaymentDepositRouting: type: object required: - provider_code - payment_method_ref properties: provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" payment_method_ref: type: string minLength: 1 PaymentDepositOptionsResponse: type: object required: - methods properties: automatic_routing: type: boolean description: Whether shared methods use server-selected provider amount bands. methods: type: array items: "$ref": "#/components/schemas/PaymentDepositMethodOption" PaymentDepositQuoteRequest: type: object additionalProperties: false required: [provider_code, payment_method_ref, amount] properties: provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" payment_method_ref: type: string minLength: 1 amount: type: integer format: int64 minimum: 1 description: Paid principal in USD cents; must be available for the selected method. PaymentDepositQuoteResponse: type: object additionalProperties: false required: [amount, credited_amount, currency_code, amount_option_ref] properties: amount: type: integer format: int64 minimum: 1 credited_amount: type: integer format: int64 minimum: 1 description: Wallet credit computed by the same SQL rule as presets, including the house subsidy. currency_code: "$ref": "#/components/schemas/CurrencyCode" amount_option_ref: type: string minLength: 1 description: Current provider amount reference to use when creating the deposit. PaymentDepositMinimumRequest: type: object additionalProperties: false required: [payment_method_ref] properties: payment_method_ref: type: string minLength: 1 PaymentDepositMinimumResponse: type: object additionalProperties: false required: [minimum_amount, currency_code, cached_until] properties: minimum_amount: type: integer format: int64 minimum: 1 currency_code: "$ref": "#/components/schemas/CurrencyCode" cached_until: type: string format: date-time PaymentDepositResponse: type: object required: - payment - poll - effects properties: payment: "$ref": "#/components/schemas/PaymentDeposit" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" wallet: description: Authoritative wallet snapshot for optimistic cache apply. nullable: true allOf: - "$ref": "#/components/schemas/WalletSnapshot" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" CreatePaymentDepositResponse: type: object required: - payment - poll - effects properties: payment: "$ref": "#/components/schemas/PaymentDeposit" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" wallet: description: Authoritative wallet snapshot for optimistic cache apply. nullable: true allOf: - "$ref": "#/components/schemas/WalletSnapshot" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" payment_link: type: string nullable: true PaymentDepositsResponse: type: object required: - payments - pagination properties: payments: type: array items: "$ref": "#/components/schemas/PaymentDeposit" pagination: "$ref": "#/components/schemas/Pagination" AdminPaymentDeposit: description: 'Admin projection of a payment deposit: the player-facing deposit plus operator triage fields (progression tier and payer identity). ' allOf: - "$ref": "#/components/schemas/PaymentDeposit" - type: object required: - tier - user_email - user_is_system_account properties: tier: "$ref": "#/components/schemas/PaymentDepositTier" user_email: type: string format: email user_alias: type: string nullable: true user_is_system_account: description: True when the payer is a provider-health system canary account. type: boolean off_app: nullable: true allOf: - "$ref": "#/components/schemas/AdminOffAppDepositMetadata" AdminPaymentDepositsResponse: type: object required: - payments - pagination properties: payments: type: array items: "$ref": "#/components/schemas/AdminPaymentDeposit" pagination: "$ref": "#/components/schemas/Pagination" OffAppDepositPaymentMethod: type: string enum: [cash_app, chime, paypal, card, bank, crypto, other] AdminOffAppDepositMetadata: type: object required: [payment_method, received_at, internal_note, created_by, created_at, updated_at] properties: payment_method: {"$ref": "#/components/schemas/OffAppDepositPaymentMethod"} other_label: {type: string, nullable: true} payer_reference: {type: string, nullable: true} external_reference: {type: string, nullable: true} received_at: {type: string, format: date-time} internal_note: {type: string} created_by: {type: string, format: uuid} settled_by: {type: string, format: uuid, nullable: true} settled_at: {type: string, format: date-time, nullable: true} voided_by: {type: string, format: uuid, nullable: true} voided_at: {type: string, format: date-time, nullable: true} void_reason: {type: string, nullable: true} reversed_by: {type: string, format: uuid, nullable: true} reversed_at: {type: string, format: date-time, nullable: true} reversal_reason: {type: string, nullable: true} supersedes_payment_id: type: string format: uuid nullable: true description: The stuck provider deposit this off-app deposit replaced; that deposit is now superseded. supersede_reason: {type: string, nullable: true} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} AdminWalletAdjustmentResource: type: string enum: [cash, withdrawable_cash, freeplay, xp, diamonds, spin_tokens] x-enum-varnames: [WalletAdjustmentResourceCash, WalletAdjustmentResourceWithdrawableCash, WalletAdjustmentResourceFreeplay, WalletAdjustmentResourceXP, WalletAdjustmentResourceDiamonds, WalletAdjustmentResourceSpinTokens] AdminWalletAdjustmentUnit: type: string enum: [cents, points, tokens] x-enum-varnames: [WalletAdjustmentUnitCents, WalletAdjustmentUnitPoints, WalletAdjustmentUnitTokens] AdminWalletAdjustmentInputItem: type: object additionalProperties: false required: [resource, amount] properties: resource: {"$ref": "#/components/schemas/AdminWalletAdjustmentResource"} amount: type: integer format: int64 minimum: 1 AdminWalletAdjustmentCASItem: type: object additionalProperties: false required: [resource, amount, expected_balance] properties: resource: {"$ref": "#/components/schemas/AdminWalletAdjustmentResource"} amount: {type: integer, format: int64, minimum: 1} expected_balance: type: integer format: int64 minimum: 0 AdminWalletAdjustmentPreviewRequest: type: object additionalProperties: false required: [player_id] properties: player_id: {type: string, format: uuid} entire_wallet: type: boolean description: Preview all current deposited cash, withdrawable cash and freeplay; cannot be combined with items or a source deposit. source_payment_id: {type: string, format: uuid} items: type: array minItems: 1 maxItems: 6 uniqueItems: true items: {"$ref": "#/components/schemas/AdminWalletAdjustmentInputItem"} AdminWalletAdjustmentReason: type: string description: Why an admin takes money or freeplay away from a player. enum: [credited_by_mistake, duplicate_payment, deposit_reversed, promotion_abuse, test_cleanup, player_request, other] x-enum-varnames: - AdminWalletAdjustmentReasonCreditedByMistake - AdminWalletAdjustmentReasonDuplicatePayment - AdminWalletAdjustmentReasonDepositReversed - AdminWalletAdjustmentReasonPromotionAbuse - AdminWalletAdjustmentReasonTestCleanup - AdminWalletAdjustmentReasonPlayerRequest - AdminWalletAdjustmentReasonOther AdminCreateWalletAdjustmentRequest: type: object additionalProperties: false required: [player_id, reference, reason_code, items] properties: player_id: {type: string, format: uuid} entire_wallet: type: boolean description: Require the reviewed items to still equal the entire current cash and freeplay wallet, including detecting newly funded resources. source_payment_id: {type: string, format: uuid} reference: {type: string, minLength: 1, maxLength: 255} reason_code: "$ref": "#/components/schemas/AdminWalletAdjustmentReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. items: type: array minItems: 1 maxItems: 6 uniqueItems: true items: {"$ref": "#/components/schemas/AdminWalletAdjustmentCASItem"} AdminWalletAdjustmentItem: type: object required: [resource, unit, amount, balance_before, balance_after, available] properties: resource: {"$ref": "#/components/schemas/AdminWalletAdjustmentResource"} unit: {"$ref": "#/components/schemas/AdminWalletAdjustmentUnit"} amount: {type: integer, format: int64, minimum: 1} balance_before: {type: integer, format: int64, minimum: 0} balance_after: {type: integer, format: int64, minimum: 0} available: {type: boolean} AdminWalletAdjustmentBlocker: type: object required: [code, message] properties: code: type: string enum: [insufficient_balance, source_not_reversible, source_items_mismatch] x-enum-varnames: [WalletAdjustmentBlockerInsufficientBalance, WalletAdjustmentBlockerSourceNotReversible, WalletAdjustmentBlockerSourceItemsMismatch] message: {type: string} resource: {"$ref": "#/components/schemas/AdminWalletAdjustmentResource"} AdminWalletAdjustmentPreview: type: object required: [player_id, items, blockers, executable, exact_deposit_reversal] properties: player_id: {type: string, format: uuid} source_payment_id: {type: string, format: uuid} source_reference: {type: string} items: type: array maxItems: 6 items: {"$ref": "#/components/schemas/AdminWalletAdjustmentItem"} blockers: type: array items: {"$ref": "#/components/schemas/AdminWalletAdjustmentBlocker"} executable: {type: boolean} exact_deposit_reversal: {type: boolean} AdminWalletAdjustment: type: object required: [id, player_id, actor_id, reference, reason, currency_code, payment_reversed, items, created_at, replayed] properties: id: {type: string, format: uuid} player_id: {type: string, format: uuid} actor_id: {type: string, format: uuid} source_payment_id: {type: string, format: uuid} reference: {type: string} reason: {type: string} currency_code: {"$ref": "#/components/schemas/CurrencyCode"} ledger_transaction_id: {type: string, format: uuid} reward_event_id: {type: string, format: uuid} payment_reversed: {type: boolean} items: type: array minItems: 1 maxItems: 6 items: {"$ref": "#/components/schemas/AdminWalletAdjustmentItem"} created_at: {type: string, format: date-time} replayed: {type: boolean} AdminWalletAdjustmentResponse: type: object required: [adjustment] properties: adjustment: {"$ref": "#/components/schemas/AdminWalletAdjustment"} AdminWalletAdjustmentConflictCode: type: string enum: [insufficient_balance, balance_changed, source_mismatch, operation_in_progress, command_conflict] x-enum-varnames: [WalletAdjustmentConflictInsufficientBalance, WalletAdjustmentConflictBalanceChanged, WalletAdjustmentConflictSourceMismatch, WalletAdjustmentConflictOperationInProgress, WalletAdjustmentConflictCommandConflict] AdminWalletAdjustmentConflictResponse: type: object required: [error, adjustment_code] properties: error: {"$ref": "#/components/schemas/APIError"} adjustment_code: {"$ref": "#/components/schemas/AdminWalletAdjustmentConflictCode"} AdminCreateOffAppDepositRequest: type: object additionalProperties: false required: [player_id, amount_cents, payment_method, received_at, internal_note] properties: player_id: {type: string, format: uuid} amount_cents: {type: integer, format: int64, minimum: 1, description: "A whole dollar or an amount ending in 99 cents (ADR 0015). Other cents are refused with field amount_cents, reason amount_not_creditable."} payment_method: {"$ref": "#/components/schemas/OffAppDepositPaymentMethod"} other_label: {type: string, minLength: 1, maxLength: 120, nullable: true} payer_reference: {type: string, minLength: 1, maxLength: 255, nullable: true} external_reference: {type: string, minLength: 1, maxLength: 255, nullable: true} received_at: {type: string, format: date-time} internal_note: {type: string, maxLength: 2000} settle_now: type: boolean default: false description: Any active admin. Create and settle (credit the wallet) in one audited transaction that records the acting admin as both creator and settler. reason_code: "$ref": "#/components/schemas/AdminOffAppSettleNowReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail for reason_code. Required (at least 3 characters) when reason_code is other. AdminUpdateOffAppDepositRequest: type: object additionalProperties: false required: [expected_state, player_id, amount_cents, payment_method, received_at, internal_note] properties: expected_state: type: string enum: [requested] player_id: {type: string, format: uuid} amount_cents: {type: integer, format: int64, minimum: 1, description: "A whole dollar or an amount ending in 99 cents (ADR 0015). Other cents are refused with field amount_cents, reason amount_not_creditable."} payment_method: {"$ref": "#/components/schemas/OffAppDepositPaymentMethod"} other_label: {type: string, minLength: 1, maxLength: 120, nullable: true} payer_reference: {type: string, minLength: 1, maxLength: 255, nullable: true} external_reference: {type: string, minLength: 1, maxLength: 255, nullable: true} received_at: {type: string, format: date-time} internal_note: {type: string, maxLength: 2000} AdminSettleOffAppDepositRequest: type: object additionalProperties: false required: [expected_state] properties: expected_state: type: string enum: [requested] reason_code: "$ref": "#/components/schemas/AdminOffAppSettleNowReason" note: {type: string, maxLength: 500} proof_asset_id: {type: string, format: uuid, nullable: true} AdminOffAppDepositVoidReason: type: string description: Why an unsettled off-app deposit draft is voided. enum: [entered_in_error, duplicate_entry, payment_not_received, player_cancelled, test_cleanup, other] x-enum-varnames: - AdminOffAppDepositVoidReasonEnteredInError - AdminOffAppDepositVoidReasonDuplicateEntry - AdminOffAppDepositVoidReasonPaymentNotReceived - AdminOffAppDepositVoidReasonPlayerCancelled - AdminOffAppDepositVoidReasonTestCleanup - AdminOffAppDepositVoidReasonOther AdminOffAppSettleNowReason: type: string description: Why an admin records and credits an off-app deposit in one step. enum: [payment_received, receipt_verified, test_credit, other] x-enum-varnames: - AdminOffAppSettleNowReasonPaymentReceived - AdminOffAppSettleNowReasonReceiptVerified - AdminOffAppSettleNowReasonTestCredit - AdminOffAppSettleNowReasonOther AdminDepositConvertReason: type: string description: Why a stuck provider deposit is converted to an off-app deposit. enum: [paid_off_app, provider_checkout_failed, test_cleanup, other] x-enum-varnames: - AdminDepositConvertReasonPaidOffApp - AdminDepositConvertReasonProviderCheckoutFailed - AdminDepositConvertReasonTestCleanup - AdminDepositConvertReasonOther AdminConvertDepositToOffAppRequest: type: object additionalProperties: false required: [amount_cents, payment_method, external_reference, received_at, reason_code] properties: amount_cents: {type: integer, format: int64, minimum: 1, description: "A whole dollar or an amount ending in 99 cents (ADR 0015). Other cents are refused with field amount_cents, reason amount_not_creditable."} payment_method: {"$ref": "#/components/schemas/OffAppDepositPaymentMethod"} other_label: {type: string, minLength: 1, maxLength: 120, nullable: true} payer_reference: {type: string, minLength: 1, maxLength: 255, nullable: true} external_reference: type: string minLength: 1 maxLength: 255 description: The reference of the payment that arrived another way; it is the evidence for the conversion. received_at: {type: string, format: date-time} internal_note: {type: string, maxLength: 2000} reason_code: "$ref": "#/components/schemas/AdminDepositConvertReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. AdminVoidOffAppDepositRequest: type: object additionalProperties: false required: [expected_state, reason_code] properties: expected_state: type: string enum: [requested] reason_code: "$ref": "#/components/schemas/AdminOffAppDepositVoidReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. AdminOffAppDepositReversalReason: type: string description: Why a settled off-app deposit is reversed. enum: [payment_reversed, payment_not_received, duplicate_payment, credited_by_mistake, test_cleanup, other] x-enum-varnames: - AdminOffAppDepositReversalReasonPaymentReversed - AdminOffAppDepositReversalReasonPaymentNotReceived - AdminOffAppDepositReversalReasonDuplicatePayment - AdminOffAppDepositReversalReasonCreditedByMistake - AdminOffAppDepositReversalReasonTestCleanup - AdminOffAppDepositReversalReasonOther AdminReverseOffAppDepositRequest: type: object additionalProperties: false required: [expected_state, reason_code] properties: expected_state: type: string enum: [succeeded] reason_code: "$ref": "#/components/schemas/AdminOffAppDepositReversalReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. AdminOffAppDepositCommandResponse: type: object required: [payment, replayed] properties: payment: {"$ref": "#/components/schemas/AdminPaymentDeposit"} replayed: {type: boolean} OffAppDepositReversalBlockerCode: type: string enum: - not_off_app_deposit - invalid_state - principal_already_spent - deposit_reward_effect - daily_bonus_effect - referral_effect - mission_effect AdminOffAppDepositReversalBlocker: type: object required: [code, message] properties: code: {"$ref": "#/components/schemas/OffAppDepositReversalBlockerCode"} message: {type: string} related_id: {type: string, format: uuid, nullable: true} AdminOffAppDepositReversalPreview: type: object required: [payment_id, expected_state, principal_cents, wallet_credit_cents, house_subsidy_cents, reversible, blockers] properties: payment_id: {type: string, format: uuid} expected_state: {"$ref": "#/components/schemas/PaymentDepositState"} principal_cents: {type: integer, format: int64, minimum: 1, description: 'Actual paid principal, excluding house funding.'} wallet_credit_cents: {type: integer, format: int64, minimum: 0, description: 'Cash removed by reversal, from the original immutable ledger posting.'} house_subsidy_cents: {type: integer, format: int64, minimum: 0, description: 'House funding returned by reversal, separate from the paid receipt.'} reversible: {type: boolean} blockers: type: array items: {"$ref": "#/components/schemas/AdminOffAppDepositReversalBlocker"} AdminOffAppDepositReversalAttempt: type: object required: [id, actor_id, reason, outcome, blockers, created_at] properties: id: {type: string, format: uuid} actor_id: {type: string, format: uuid} reason: {type: string} outcome: type: string enum: [blocked, succeeded] blockers: type: array items: {"$ref": "#/components/schemas/AdminOffAppDepositReversalBlocker"} ledger_transaction_id: {type: string, format: uuid, nullable: true} created_at: {type: string, format: date-time} AdminOffAppDepositReversalConflictResponse: type: object required: [error, preview] properties: error: {"$ref": "#/components/schemas/ErrorResponse"} preview: {"$ref": "#/components/schemas/AdminOffAppDepositReversalPreview"} PaymentWithdrawalState: type: string enum: - awaiting_approval - dispatch_queued - action_required - provider_created - succeeded - failed - rejected - canceled - expired - unknown_requires_reconcile - failed_internal x-enum-varnames: - PaymentWithdrawalStateAwaitingApproval - PaymentWithdrawalStateDispatchQueued - PaymentWithdrawalStateActionRequired - PaymentWithdrawalStateProviderCreated - PaymentWithdrawalStateSucceeded - PaymentWithdrawalStateFailed - PaymentWithdrawalStateRejected - PaymentWithdrawalStateCanceled - PaymentWithdrawalStateExpired - PaymentWithdrawalStateUnknownRequiresReconcile - PaymentWithdrawalStateFailedInternal RewardCampaign: type: object required: [id, title, body, timezone, starts_at, ends_at, enabled, reward_kind, frequency, reward_value, reward_cap_cents, claimed, redeemed, popup_dismissed, created_at] properties: enabled_readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true, description: Effective readiness if this campaign is switched on now.} readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} id: {type: string, format: uuid} title: {type: string} body: {type: string} timezone: {type: string} starts_at: {type: string, format: date-time} ends_at: {type: string, format: date-time} enabled: {type: boolean} reward_kind: type: string enum: [next_deposit_bonus, game_load_bonus, xp, freeplay, diamonds, spin_tokens] frequency: type: string enum: [once, every] reward_value: {type: integer, format: int32, description: "Reward size: a percent for next_deposit_bonus and game_load_bonus; whole USD cents for freeplay (the same unit as reward grants and wallet adjustments); whole points or tokens for xp, diamonds and spin_tokens."} reward_cap_cents: {type: integer, format: int64} remaining_cap_cents: {type: integer, format: int64, description: "Player's remaining percentage bonus cap, including in-flight game loads"} poster_data_url: {type: string, nullable: true} claimed: {type: boolean} redeemed: {type: boolean, description: "True when a one-time percentage campaign has been used"} popup_dismissed: {type: boolean} created_at: {type: string, format: date-time} RewardCampaignResponse: type: object required: [campaign] properties: campaign: {"$ref": "#/components/schemas/RewardCampaign"} RewardCampaignsResponse: type: object required: [campaigns] properties: campaigns: type: array items: {"$ref": "#/components/schemas/RewardCampaign"} CreateRewardCampaignRequest: type: object required: [title, body, timezone, starts_local, ends_local, reward_kind, frequency, reward_value, reward_cap_cents] properties: title: {type: string, minLength: 1, maxLength: 120} body: {type: string, minLength: 1, maxLength: 1000} timezone: {type: string, default: America/Chicago} starts_local: {type: string, description: "Local YYYY-MM-DDTHH:mm time in the selected IANA timezone"} ends_local: {type: string, description: "Local YYYY-MM-DDTHH:mm time in the selected IANA timezone"} reward_kind: type: string enum: [next_deposit_bonus, game_load_bonus, xp, freeplay, diamonds, spin_tokens] frequency: type: string enum: [once, every] reward_value: {type: integer, format: int32, minimum: 1, description: "Reward size: a percent for next_deposit_bonus and game_load_bonus; whole USD cents for freeplay (the same unit as reward grants and wallet adjustments); whole points or tokens for xp, diamonds and spin_tokens."} reward_cap_cents: {type: integer, format: int64, minimum: 0} poster_base64: {type: string, description: "Optional JPEG/PNG bytes encoded as base64; 384 KiB maximum"} RewardCampaignEnabledRequest: type: object required: [enabled] properties: enabled: {type: boolean} PlayerNotificationKind: type: string enum: - withdrawal_submitted - withdrawal_approved - withdrawal_action_required - withdrawal_paid - withdrawal_rejected - withdrawal_canceled - withdrawal_expired - support_reply - campaign_available - cashout_pending_review - cashout_approved - cashout_rejected - game_password_reset - welcome_freeplay PlayerNotification: type: object required: [id, kind, title, body, resource_type, resource_id, created_at] properties: id: {type: string, format: uuid} kind: {"$ref": "#/components/schemas/PlayerNotificationKind"} title: {type: string} body: {type: string} resource_type: type: string enum: [payment_withdrawal, support_conversation, reward_campaign, provider_transfer, provider_account, reward_event] resource_id: {type: string, format: uuid} action_url: {type: string, nullable: true} read_at: {type: string, format: date-time, nullable: true} created_at: {type: string, format: date-time} PlayerNotificationsResponse: type: object required: [notifications, pagination, unread_count, as_of] properties: as_of: {type: string, format: date-time, description: "Database time bounding this notification snapshot and arrival baseline."} unread_count: {type: integer, format: int64, minimum: 0, description: "Unread notifications across every page."} notifications: type: array items: {"$ref": "#/components/schemas/PlayerNotification"} pagination: {"$ref": "#/components/schemas/Pagination"} PlayerNotificationsReadAllResponse: type: object required: [marked_count, effects] properties: marked_count: {type: integer, format: int64, minimum: 0} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} PlayerNotificationResponse: type: object required: [notification] properties: notification: {"$ref": "#/components/schemas/PlayerNotification"} PaymentWithdrawalProviderCode: type: string enum: - thesolar - mockpay - dollarpay - finix - nowpayments - manual CreatePaymentWithdrawalRequest: type: object required: - amount - provider_code - payment_method_ref additionalProperties: false properties: amount: type: integer format: int64 minimum: 1 provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" amount_option_ref: type: string minLength: 1 payment_method_ref: type: string minLength: 1 destination: "$ref": "#/components/schemas/PaymentWithdrawalDestination" PaymentWithdrawalDestinationKind: type: string enum: [cash_app, chime, paypal, crypto, provider_managed, manual] x-enum-varnames: - PaymentWithdrawalDestinationKindCashApp - PaymentWithdrawalDestinationKindChime - PaymentWithdrawalDestinationKindPayPal - PaymentWithdrawalDestinationKindCrypto - PaymentWithdrawalDestinationKindProviderManaged - PaymentWithdrawalDestinationKindManual PaymentWithdrawalDestination: type: object additionalProperties: false required: [kind] properties: expected_house_policy_version: {type: integer, format: int64, minimum: 0, description: Policy revision whose house payout account the player saw; changed settings require a refreshed review.} receipt_attachment_id: {type: string, format: uuid, description: "Existing Support screenshot reservation, bound atomically to this request. Required when the method option says receipt_required (hand-paid cash-outs): the player's screenshot of their payment app showing their tag and name."} input: {type: string, maxLength: 2048, description: Player-owned receiving tag or profile link, parsed by the shared smart-input parser.} manual_kind: {$ref: "#/components/schemas/ManualPaymentInputMethod", readOnly: true} manual_tag: {type: string, readOnly: true} payment_link: {type: string, readOnly: true} method_name: {type: string, readOnly: true} house_payment_link: {type: string, readOnly: true} house_qr_payload: {type: string, readOnly: true} house_policy_version: {type: integer, format: int64, readOnly: true} tip_cents: {type: integer, format: int64, minimum: 0, maximum: 100000000, description: Absent means zero. Optional staff tip deducted from the manual cash-out net.} tip_note: {type: string, maxLength: 500} mode: {$ref: "#/components/schemas/HousePayoutMode", description: Selected manual payout mode; absent uses the method default.} house_tag: {type: string, maxLength: 2048, description: Operator tag from the options catalog, validated and preserved with the request.} kind: "$ref": "#/components/schemas/PaymentWithdrawalDestinationKind" cash_app_tag: {type: string, minLength: 2, maxLength: 2048} chime_tag: type: string minLength: 2 maxLength: 2048 description: Chime $ChimeSign used for new Chime withdrawals. paypal_email: type: string format: email minLength: 3 maxLength: 254 chime_account: type: string minLength: 1 maxLength: 128 readOnly: true deprecated: true description: Legacy stored Chime destination returned for read compatibility; new requests must use chime_tag. network: {type: string, minLength: 1, maxLength: 64} address: {type: string, minLength: 1, maxLength: 256} memo: {type: string, maxLength: 256} PaymentWithdrawalActionKind: type: string enum: [kyc, payout_setup] x-enum-varnames: - PaymentWithdrawalActionKindKYC - PaymentWithdrawalActionKindPayoutSetup PaymentWithdrawal: type: object required: - id - user_id - provider_code - state - amount - currency_code - amount_option_ref - payment_method_ref - created_at - updated_at properties: payment_in_progress: {type: boolean, description: Staff holds this hand-paid cash-out and cancellation is unavailable.} id: type: string format: uuid user_id: type: string format: uuid provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" state: "$ref": "#/components/schemas/PaymentWithdrawalState" amount: type: integer format: int64 currency_code: "$ref": "#/components/schemas/CurrencyCode" amount_option_ref: type: string payment_method_ref: type: string destination: nullable: true allOf: - "$ref": "#/components/schemas/PaymentWithdrawalDestination" provider_transaction_id: type: string nullable: true kyc_link: type: string nullable: true deprecated: true action_url: type: string nullable: true action_kind: nullable: true allOf: - "$ref": "#/components/schemas/PaymentWithdrawalActionKind" wallet_debit_transaction_id: type: string format: uuid nullable: true release_transaction_id: type: string format: uuid nullable: true settlement_transaction_id: type: string format: uuid nullable: true estimated_fee: type: integer format: int64 estimated_net: type: integer format: int64 actual_fee: type: integer format: int64 nullable: true actual_net: type: integer format: int64 nullable: true approval_expires_at: type: string format: date-time nullable: true action_required_expires_at: type: string format: date-time nullable: true rejection_category: "$ref": "#/components/schemas/PaymentWithdrawalRejectionCategory" created_at: type: string format: date-time updated_at: type: string format: date-time PaymentWithdrawalAmountOption: type: object required: - ref - amount - currency_code - label properties: ref: type: string amount: type: integer format: int64 currency_code: "$ref": "#/components/schemas/CurrencyCode" label: type: string PaymentWithdrawalMethodOption: type: object required: - ref - provider_code - display_name - minimum_amount - destination_required - destination_label - destination_kind - memo_required - receipt_required properties: house_payment_link: {type: string} house_qr_payload: {type: string} default_payout_mode: {$ref: "#/components/schemas/HousePayoutMode"} payout_modes: type: array items: {$ref: "#/components/schemas/HousePayoutMode"} input_kind: {$ref: "#/components/schemas/ManualPaymentInputMethod"} method_icon: {$ref: "#/components/schemas/HouseMethodIcon"} method_logo_data_url: {type: string, maxLength: 22000} policy_version: {type: integer, format: int64} allow_tips: {type: boolean, description: Whether this method accepts a manual staff tip.} house_tag: {type: string, description: Operator tag available for payment requests.} ref: type: string provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" display_name: type: string minimum_amount: description: Known per-method minimum in USD cents. Zero means the crypto minimum is not warmed yet; the method remains selectable and the selected-coin minimum endpoint resolves its live limit. Crypto quote and submission always enforce a known per-coin minimum. type: integer format: int64 maximum_amount: type: integer format: int64 nullable: true destination_required: type: boolean destination_label: type: string destination_kind: "$ref": "#/components/schemas/PaymentWithdrawalDestinationKind" network: type: string nullable: true memo_required: type: boolean receipt_required: type: boolean description: The cash-out request must carry destination.receipt_attachment_id, the player's screenshot of their payment app showing their tag and name (hand-paid methods); without it the request is refused with field receipt_attachment_id, reason receipt_required. PaymentWithdrawalProviderOptions: type: object required: - provider_code - amounts - payment_methods - account_setup_state - destination_required - destination_label properties: provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" account_setup_state: "$ref": "#/components/schemas/PaymentAccountSetupState" destination_required: type: boolean destination_label: type: string amounts: type: array items: "$ref": "#/components/schemas/PaymentWithdrawalAmountOption" payment_methods: type: array items: "$ref": "#/components/schemas/PaymentWithdrawalMethodOption" PaymentWithdrawalOptionsResponse: type: object required: - amounts - payment_methods properties: method_display_order: {type: array, items: {type: string}, description: Audited card-key ordering; unlisted cards retain their existing relative order.} amounts: type: array items: "$ref": "#/components/schemas/PaymentWithdrawalAmountOption" payment_methods: type: array items: "$ref": "#/components/schemas/PaymentWithdrawalMethodOption" PaymentWithdrawalsResponse: type: object required: - payments - pagination properties: payments: type: array items: "$ref": "#/components/schemas/PaymentWithdrawal" pagination: "$ref": "#/components/schemas/Pagination" PaymentWithdrawalResponse: type: object required: - payment - poll - effects properties: payment: "$ref": "#/components/schemas/PaymentWithdrawal" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" CreatePaymentWithdrawalResponse: type: object required: - payment - poll - effects properties: payment: "$ref": "#/components/schemas/PaymentWithdrawal" poll: nullable: true allOf: - "$ref": "#/components/schemas/PollHint" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" PaymentWithdrawalQuoteRequest: type: object additionalProperties: false required: [amount, provider_code, payment_method_ref] properties: amount: type: integer format: int64 minimum: 1 provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" payment_method_ref: type: string minLength: 1 destination: "$ref": "#/components/schemas/PaymentWithdrawalDestination" PaymentWithdrawalQuoteResponse: type: object required: [amount, estimated_fee, estimated_net, currency_code, quote_version] properties: amount: {type: integer, format: int64} estimated_fee: {type: integer, format: int64} estimated_net: {type: integer, format: int64} tip_cents: {type: integer, format: int64, minimum: 0, description: Absent means zero.} currency_code: {"$ref": "#/components/schemas/CurrencyCode"} quote_version: {type: string} PaymentWithdrawalMinimumRequest: type: object additionalProperties: false required: [provider_code, payment_method_ref] properties: provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" payment_method_ref: type: string minLength: 1 PaymentWithdrawalMinimumResponse: type: object additionalProperties: false required: [minimum_amount, currency_code, cached_until] properties: minimum_amount: type: integer format: int64 minimum: 1 currency_code: "$ref": "#/components/schemas/CurrencyCode" cached_until: type: string format: date-time PaymentWithdrawalRejectionCategory: type: string nullable: true enum: - verification_failed - destination_issue - policy_restriction - provider_unavailable - other x-enum-varnames: - WithdrawalRejectionVerificationFailed - WithdrawalRejectionDestinationIssue - WithdrawalRejectionPolicyRestriction - WithdrawalRejectionProviderUnavailable - WithdrawalRejectionOther PaymentWebhookAckResponse: type: object required: - status properties: status: type: string enum: - success - failed x-enum-varnames: - PaymentWebhookAckResponseStatusSuccess - PaymentWebhookAckResponseStatusFailed UpdateProviderCapabilityRequest: type: object required: - expected_status - next_status - reason additionalProperties: false properties: expected_status: "$ref": "#/components/schemas/ProviderCapabilityStatus" next_status: "$ref": "#/components/schemas/ProviderCapabilityStatus" reason: type: string minLength: 1 GameLaunchFallbackRevisionState: type: string enum: - draft - active - cleared AdminGameLaunchFallbackWriteState: type: string enum: - active - cleared AdminGameLaunchFallbackRevision: type: object additionalProperties: false required: - revision_id - state - fallback_url - source_url - reason - actor_id - actor_ref - created_at properties: revision_id: type: integer format: int64 minimum: 1 state: "$ref": "#/components/schemas/GameLaunchFallbackRevisionState" fallback_url: type: string format: uri maxLength: 2048 nullable: true source_url: type: string format: uri maxLength: 2048 nullable: true reason: type: string minLength: 1 maxLength: 500 actor_id: type: string format: uuid nullable: true actor_ref: type: string minLength: 1 maxLength: 200 created_at: type: string format: date-time AdminGameLaunchFallback: type: object additionalProperties: false required: - game_id - provider_code - game_name - built_in_fallback_url - effective_fallback_url - override_active - latest_revision properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} game_id: type: string provider_code: "$ref": "#/components/schemas/ProviderCode" game_name: type: string built_in_fallback_url: type: string format: uri nullable: true effective_fallback_url: type: string format: uri nullable: true override_active: type: boolean latest_revision: nullable: true allOf: - "$ref": "#/components/schemas/AdminGameLaunchFallbackRevision" AdminGameLaunchFallbacksResponse: type: object additionalProperties: false required: - fallbacks properties: fallbacks: type: array items: "$ref": "#/components/schemas/AdminGameLaunchFallback" AdminGameLaunchFallbackResponse: type: object additionalProperties: false required: - fallback properties: fallback: "$ref": "#/components/schemas/AdminGameLaunchFallback" PutAdminGameLaunchFallbackRequest: type: object additionalProperties: false required: - state - reason properties: state: "$ref": "#/components/schemas/AdminGameLaunchFallbackWriteState" fallback_url: description: Absolute HTTP or HTTPS URL without embedded credentials, opened as top-level navigation. Explicit ports are allowed. HTTP links show a not secure note in admin. type: string format: uri maxLength: 2048 nullable: true reason: type: string minLength: 1 maxLength: 500 AdminAccountRole: description: Admin-management command role. Intentionally excludes player; public user projections use UserRole. type: string enum: - admin - super_admin AdminAccountStatus: description: Admin-management command status. Intentionally excludes pending_email_verification because admin accounts are operator-created. type: string enum: - active - suspended - banned CreateAdminAccountRequest: type: object required: - email - password - role additionalProperties: false properties: email: type: string format: email password: type: string minLength: 8 display_name: type: string minLength: 1 nullable: true role: "$ref": "#/components/schemas/AdminAccountRole" UpdateAdminAccountRequest: type: object minProperties: 1 additionalProperties: false properties: role: "$ref": "#/components/schemas/AdminAccountRole" status: "$ref": "#/components/schemas/AdminAccountStatus" AdminAccountResponse: type: object required: - user properties: user: "$ref": "#/components/schemas/AdminUser" AdminPasswordResetRequest: type: object required: - new_password additionalProperties: false properties: new_password: type: string minLength: 8 maxLength: 256 format: password AdminPasswordResetResponse: type: object required: - ok - requires_relogin - replayed additionalProperties: false properties: ok: type: boolean requires_relogin: type: boolean replayed: type: boolean AdminUser: type: object required: - id - email - display_name - role - status - is_system_account - created_at - provider_account_count - payment_count - provider_transfer_count - last_successful_deposit_at - last_successful_game_load_at properties: is_tester: {type: boolean, description: Backend tester marker.} id: type: string format: uuid email: type: string format: email display_name: type: string minLength: 1 role: "$ref": "#/components/schemas/UserRole" status: "$ref": "#/components/schemas/UserStatus" is_system_account: description: True for provider-health system canary accounts (operational, not a real player). type: boolean created_at: type: string format: date-time wallet_cash_balance: nullable: true allOf: - "$ref": "#/components/schemas/MoneyAmount" provider_account_count: type: integer format: int64 minimum: 0 payment_count: type: integer format: int64 minimum: 0 provider_transfer_count: type: integer format: int64 minimum: 0 latest_activity_at: type: string format: date-time nullable: true last_successful_deposit_at: description: Newest successful wallet deposit (succeeded payment intent, including manual off-app settlements; reversed, failed, pending and voided deposits never count). null means the player has never made one. type: string format: date-time nullable: true last_successful_game_load_at: description: Newest completed wallet-to-game load (a recharge signal, not gameplay; provider-health canary loads excluded). null means never. type: string format: date-time nullable: true AdminRechargeRecencyFilter: type: string description: never = no successful event at all; inactive_Nd = at least one success and the newest is N or more rolling 24-hour days old (cumulative across 2/3/7 days, disjoint from never). enum: [never, inactive_2d, inactive_3d, inactive_7d] AdminRechargeCohortBuckets: type: object additionalProperties: false required: [never, inactive_2d, inactive_3d, inactive_7d] properties: never: {type: integer, format: int64, minimum: 0} inactive_2d: {type: integer, format: int64, minimum: 0} inactive_3d: {type: integer, format: int64, minimum: 0} inactive_7d: {type: integer, format: int64, minimum: 0} AdminRechargeCohorts: type: object description: Point-in-time recharge recency over active external player accounts, independent of the report window. Successful wallet deposits and completed game loads only; never a gameplay measure. additionalProperties: false required: [as_of, eligible_players, deposits, game_loads] properties: as_of: {type: string, format: date-time} eligible_players: {type: integer, format: int64, minimum: 0} deposits: {"$ref": "#/components/schemas/AdminRechargeCohortBuckets"} game_loads: {"$ref": "#/components/schemas/AdminRechargeCohortBuckets"} AdminUsersResponse: type: object required: - users - pagination properties: users: type: array items: "$ref": "#/components/schemas/AdminUser" pagination: "$ref": "#/components/schemas/Pagination" AdminUserDetailResponse: type: object required: - user - wallet - provider_accounts - recent_provider_transfers - recent_payment_deposits - recent_wallet_transactions properties: user: "$ref": "#/components/schemas/AdminUser" wallet: "$ref": "#/components/schemas/WalletSnapshot" provider_accounts: type: array items: "$ref": "#/components/schemas/ProviderAccount" recent_provider_transfers: type: array items: "$ref": "#/components/schemas/ProviderTransfer" recent_payment_deposits: type: array items: "$ref": "#/components/schemas/AdminPaymentDeposit" recent_wallet_transactions: type: array items: "$ref": "#/components/schemas/WalletTransaction" AdminReportingGranularity: type: string enum: - day - month AdminReportingWindow: type: object required: - from - to properties: from: type: string format: date-time description: Inclusive reporting instant. to: type: string format: date-time description: Exclusive reporting instant. AdminReportingOutcomeCounts: type: object description: >- Current outcomes for records created in the reporting window. Success rate is success_count / resolved_count in integer basis points, truncated toward zero; unresolved and pending records are excluded from resolved_count. The rate is zero when resolved_count is zero. required: - total_count - success_count - terminal_failure_count - pending_count - unresolved_count - resolved_count - success_rate_bps properties: total_count: type: integer format: int64 minimum: 0 success_count: type: integer format: int64 minimum: 0 terminal_failure_count: type: integer format: int64 minimum: 0 pending_count: type: integer format: int64 minimum: 0 unresolved_count: type: integer format: int64 minimum: 0 resolved_count: type: integer format: int64 minimum: 0 success_rate_bps: type: integer format: int64 minimum: 0 maximum: 10000 AdminBusinessOutcomeSummary: type: object required: - deposits - withdrawals - provider_transfers properties: deposits: description: Deposit-intent creation cohort; succeeded is success, failed is terminal failure, and unknown_requires_reconcile or failed_internal is unresolved. "$ref": "#/components/schemas/AdminReportingOutcomeCounts" withdrawals: description: Withdrawal-intent creation cohort; succeeded is success; failed, rejected, canceled, or expired is terminal failure; unknown_requires_reconcile or failed_internal is unresolved. "$ref": "#/components/schemas/AdminReportingOutcomeCounts" provider_transfers: description: Provider-transfer creation cohort; completed is success, rejected is terminal failure, and unknown_requires_reconcile or failed_internal is unresolved. "$ref": "#/components/schemas/AdminReportingOutcomeCounts" AdminBusinessFinanceMetrics: type: object required: - settled_deposit_count - settled_deposit_amount - succeeded_withdrawal_count - succeeded_withdrawal_gross_amount - succeeded_withdrawal_actual_net_amount - succeeded_withdrawal_actual_fee_amount - withdrawal_actuals_missing_count - net_cash_flow_proxy properties: settled_deposit_count: type: integer format: int64 minimum: 0 description: Succeeded deposits recognized at linked wallet_credit ledger transaction time. settled_deposit_amount: "$ref": "#/components/schemas/MoneyAmount" succeeded_withdrawal_count: type: integer format: int64 minimum: 0 description: Succeeded withdrawals recognized at linked withdrawal_settle ledger transaction time. succeeded_withdrawal_gross_amount: "$ref": "#/components/schemas/MoneyAmount" succeeded_withdrawal_actual_net_amount: description: Sum of persisted actual_net only; missing actuals contribute zero and are counted separately. "$ref": "#/components/schemas/MoneyAmount" succeeded_withdrawal_actual_fee_amount: description: Sum of persisted actual_fee only; missing actuals contribute zero and are counted separately. "$ref": "#/components/schemas/MoneyAmount" withdrawal_actuals_missing_count: type: integer format: int64 minimum: 0 description: Succeeded withdrawals missing actual_net, actual_fee, or both. net_cash_flow_proxy: description: Settled deposit amount minus succeeded withdrawal gross amount. May be negative. "$ref": "#/components/schemas/MoneyAmount" AdminBusinessExposure: type: object description: Current state of records created in the reporting window; this is operational exposure, not an accounting balance. required: - open_deposit_count - open_deposit_amount - open_provider_transfer_count - open_provider_transfer_amount - open_withdrawal_count - open_withdrawal_amount - total_open_count - total_open_amount - deposit_reconciliation_count - provider_transfer_reconciliation_count - withdrawal_reconciliation_count - total_reconciliation_count properties: open_deposit_count: type: integer format: int64 minimum: 0 open_deposit_amount: "$ref": "#/components/schemas/MoneyAmount" open_provider_transfer_count: type: integer format: int64 minimum: 0 open_provider_transfer_amount: "$ref": "#/components/schemas/MoneyAmount" open_withdrawal_count: type: integer format: int64 minimum: 0 open_withdrawal_amount: "$ref": "#/components/schemas/MoneyAmount" total_open_count: type: integer format: int64 minimum: 0 total_open_amount: "$ref": "#/components/schemas/MoneyAmount" deposit_reconciliation_count: type: integer format: int64 minimum: 0 provider_transfer_reconciliation_count: type: integer format: int64 minimum: 0 withdrawal_reconciliation_count: type: integer format: int64 minimum: 0 total_reconciliation_count: type: integer format: int64 minimum: 0 AdminBusinessAccountingSnapshot: type: object description: >- Current generated_at snapshot of balances owned by included player accounts. These are operational wallet balances/liabilities for reconciliation and are not GAAP financial statements. required: - as_of - player_account_count - cash_balance - withdrawable_cash_balance - pending_withdrawal_balance - freeplay_balance - total_operational_liability properties: as_of: type: string format: date-time player_account_count: type: integer format: int64 minimum: 0 cash_balance: "$ref": "#/components/schemas/MoneyAmount" withdrawable_cash_balance: "$ref": "#/components/schemas/MoneyAmount" pending_withdrawal_balance: "$ref": "#/components/schemas/MoneyAmount" freeplay_balance: "$ref": "#/components/schemas/MoneyAmount" total_operational_liability: description: Sum of the four reported operational balance buckets; not a GAAP liability measurement. "$ref": "#/components/schemas/MoneyAmount" AdminBusinessReportingCaveats: type: object required: - cash_flow_proxy - operational_liabilities properties: cash_flow_proxy: type: string description: Human-readable basis limitation for the cash-flow fields. operational_liabilities: type: string description: Human-readable non-GAAP limitation for the accounting snapshot. AdminBusinessSeriesPoint: type: object description: Finance and outcome counts are additive across returned buckets; bucket boundaries are clipped to the requested half-open window. required: - bucket_start - bucket_end - finance - outcomes properties: bucket_start: type: string format: date-time bucket_end: type: string format: date-time finance: "$ref": "#/components/schemas/AdminBusinessFinanceMetrics" outcomes: "$ref": "#/components/schemas/AdminBusinessOutcomeSummary" AdminBusinessProviderBreakdown: type: object required: - provider_code - finance - outcomes properties: provider_code: type: string minLength: 1 finance: "$ref": "#/components/schemas/AdminBusinessFinanceMetrics" outcomes: "$ref": "#/components/schemas/AdminBusinessOutcomeSummary" AdminBusinessManualMethodBreakdown: type: object description: Read-only house-method activity for the requested half-open window. Approved paid principal is counted at its linked wallet settlement (not the rounded wallet credit); rejected claims at decision time and pending claims at submission time. Approved totals, including staff_recorded, reconcile to the manual provider's settled deposit finance. Rejected claims create no payment intent and are not provider failure counts. required: - method - method_name - approved_count - rejected_count - pending_count - approved_amount - rejected_amount properties: method: type: string minLength: 1 description: Stable house method ID (cash_app, chime, paypal, venmo, or custom UUID ID); staff_recorded identifies settled manual intents with no claim. This is open to configured custom methods, not a closed vendor enum. method_name: type: string minLength: 1 description: Latest nonempty claim label in this window, falling back to the stable method ID for legacy records and staff_recorded. Changing a label does not split a method's totals. approved_count: type: integer format: int64 minimum: 0 rejected_count: type: integer format: int64 minimum: 0 pending_count: type: integer format: int64 minimum: 0 approved_amount: "$ref": "#/components/schemas/MoneyAmount" rejected_amount: "$ref": "#/components/schemas/MoneyAmount" AdminBusinessManualPayoutMethodBreakdown: type: object description: House payout activity keyed by the immutable requested method, excluding internal/tester/staff identities. Requests use creation time; each intent is counted once per approval/rejection type within the window, using event time; paid gross/net/fees use successful withdrawal ledger settlement time. Counts are activity measures, not a funnel or mutually exclusive statuses. Approved does not mean paid. The actual sending rail may differ from the requested method. All windows are half-open. required: - method - method_name - requested_count - requested_amount - approved_count - approved_amount - declined_count - declined_amount - paid_count - paid_gross_amount - paid_net_amount - paid_fee_amount - actuals_missing_count properties: method: type: string minLength: 1 method_name: type: string minLength: 1 description: Latest nonempty frozen destination label among activity in this window, falling back to the method ID. requested_count: type: integer format: int64 minimum: 0 approved_count: type: integer format: int64 minimum: 0 declined_count: type: integer format: int64 minimum: 0 paid_count: type: integer format: int64 minimum: 0 actuals_missing_count: type: integer format: int64 minimum: 0 requested_amount: "$ref": "#/components/schemas/MoneyAmount" approved_amount: "$ref": "#/components/schemas/MoneyAmount" declined_amount: "$ref": "#/components/schemas/MoneyAmount" paid_gross_amount: "$ref": "#/components/schemas/MoneyAmount" paid_net_amount: "$ref": "#/components/schemas/MoneyAmount" paid_fee_amount: "$ref": "#/components/schemas/MoneyAmount" AdminBusinessAnalyticsOverviewResponse: type: object required: - generated_at - window - granularity - timezone - include_internal - finance - outcomes - exposure - accounting - caveats - series - provider_breakdown properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/AdminReportingWindow" granularity: "$ref": "#/components/schemas/AdminReportingGranularity" timezone: type: string enum: - America/New_York include_internal: type: boolean finance: "$ref": "#/components/schemas/AdminBusinessFinanceMetrics" outcomes: "$ref": "#/components/schemas/AdminBusinessOutcomeSummary" exposure: "$ref": "#/components/schemas/AdminBusinessExposure" accounting: "$ref": "#/components/schemas/AdminBusinessAccountingSnapshot" caveats: "$ref": "#/components/schemas/AdminBusinessReportingCaveats" series: type: array description: One entry for every local-calendar bucket intersecting the half-open window, including zero buckets. items: "$ref": "#/components/schemas/AdminBusinessSeriesPoint" provider_breakdown: type: array items: "$ref": "#/components/schemas/AdminBusinessProviderBreakdown" manual_method_breakdown: type: array description: Additive house/manual deposit breakdown for this response's window, excluding internal/tester/system identities exactly as finance does. The existing current and previous window requests both return this field. Present empty array means no activity; an absent field means the server does not supply the breakdown. Includes a separate staff_recorded row when off-app settlement activity exists. Rows are ordered by stable method ID. items: "$ref": "#/components/schemas/AdminBusinessManualMethodBreakdown" manual_payout_method_breakdown: type: array description: Additive house payout activity for the same window and read snapshot as finance and manual_method_breakdown. Always present, empty when no activity. Stable method-ID ordering. items: "$ref": "#/components/schemas/AdminBusinessManualPayoutMethodBreakdown" manual_payout_tips: "$ref": "#/components/schemas/AdminBusinessManualPayoutTips" AdminPlayerStatsSummary: type: object required: - total_player_accounts - active_player_accounts - new_players - business_active_players - depositors - first_time_depositors - game_active_players - withdrawing_players - risk_players - reconciliation_players properties: total_player_accounts: type: integer format: int64 minimum: 0 description: Included player accounts created before window.to. active_player_accounts: type: integer format: int64 minimum: 0 new_players: type: integer format: int64 minimum: 0 business_active_players: type: integer format: int64 minimum: 0 description: Distinct players with a settled deposit, settled withdrawal, or completed provider transfer in the window. depositors: type: integer format: int64 minimum: 0 description: Distinct players with a deposit wallet settlement in the window. first_time_depositors: type: integer format: int64 minimum: 0 description: Distinct players whose earliest deposit wallet settlement is in the window. game_active_players: type: integer format: int64 minimum: 0 description: Distinct players with a successfully completed game_launch idempotency record in the window. withdrawing_players: type: integer format: int64 minimum: 0 description: Distinct players with a succeeded withdrawal settlement in the window. risk_players: type: integer format: int64 minimum: 0 description: Current included players at elevated or high Player360 v1 risk as of generated_at. reconciliation_players: type: integer format: int64 minimum: 0 description: Current included players at high risk because at least one deposit, transfer, or withdrawal requires reconciliation or failed internally. AdminPlayerStatsAccountStatusCount: type: object required: - status - count properties: status: "$ref": "#/components/schemas/UserStatus" count: type: integer format: int64 minimum: 0 AdminPlayerStatsRiskLevelCount: type: object required: - level - count properties: level: "$ref": "#/components/schemas/AdminPlayer360RiskLevel" count: type: integer format: int64 minimum: 0 AdminPlayerStatsSeriesPoint: type: object description: Counts are distinct within each bucket and are not additive across buckets because one player may be active in multiple buckets. required: - bucket_start - bucket_end - new_players - business_active_players - depositors - first_time_depositors - game_active_players - withdrawing_players properties: bucket_start: type: string format: date-time bucket_end: type: string format: date-time new_players: type: integer format: int64 minimum: 0 business_active_players: type: integer format: int64 minimum: 0 depositors: type: integer format: int64 minimum: 0 first_time_depositors: type: integer format: int64 minimum: 0 game_active_players: type: integer format: int64 minimum: 0 withdrawing_players: type: integer format: int64 minimum: 0 AdminPlayerStatsOverviewResponse: type: object required: - generated_at - window - granularity - timezone - include_internal - risk_rule_version - summary - account_status_breakdown - risk_level_breakdown - series properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/AdminReportingWindow" granularity: "$ref": "#/components/schemas/AdminReportingGranularity" timezone: type: string enum: - America/New_York include_internal: type: boolean risk_rule_version: type: string summary: "$ref": "#/components/schemas/AdminPlayerStatsSummary" account_status_breakdown: type: array description: Zero-filled rows for active, suspended, banned, and pending_email_verification player statuses. items: "$ref": "#/components/schemas/AdminPlayerStatsAccountStatusCount" risk_level_breakdown: type: array description: Zero-filled current Player360 v1 risk-level rows that sum to total_player_accounts. items: "$ref": "#/components/schemas/AdminPlayerStatsRiskLevelCount" series: type: array description: One entry for every local-calendar bucket intersecting the half-open window, including zero buckets. items: "$ref": "#/components/schemas/AdminPlayerStatsSeriesPoint" RiskPolicyMode: type: string enum: [info, review] x-enum-varnames: [RiskPolicyModeInfo, RiskPolicyModeReview] AdminRiskPolicyRule: type: object additionalProperties: false required: [key, enabled, mode, threshold, review_threshold] properties: key: {"$ref": "#/components/schemas/AdminPlayer360RiskSignalKey"} enabled: {type: boolean} mode: {"$ref": "#/components/schemas/RiskPolicyMode"} threshold: {type: integer, format: int64, minimum: 1, maximum: 100000} review_threshold: {type: integer, format: int64, minimum: 2, maximum: 100000, nullable: true} AdminRiskPolicyConfig: type: object additionalProperties: false required: [repeat_interval_hours, rules] properties: repeat_interval_hours: {type: integer, format: int64, minimum: 1, maximum: 168} rules: type: array minItems: 7 maxItems: 7 items: {"$ref": "#/components/schemas/AdminRiskPolicyRule"} AdminRiskPolicy: type: object required: [version, config, updated_at, actor_label] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} version: {type: integer, format: int64, minimum: 1} config: {"$ref": "#/components/schemas/AdminRiskPolicyConfig"} updated_at: {type: string, format: date-time} actor_label: {type: string} AdminRiskPolicyChangeReason: type: string enum: [initial_policy, operating_policy, correction, other] x-enum-varnames: [RiskPolicyInitialPolicy, RiskPolicyOperatingPolicy, RiskPolicyCorrection, RiskPolicyOther] AdminRiskPolicyChange: type: object required: [version, config, actor_label, reason_code, reason, created_at] properties: version: {type: integer, format: int64, minimum: 1} config: {"$ref": "#/components/schemas/AdminRiskPolicyConfig"} actor_label: {type: string} reason_code: {"$ref": "#/components/schemas/AdminRiskPolicyChangeReason"} reason: {type: string} created_at: {type: string, format: date-time} AdminRiskPolicyResponse: type: object required: [policy, history, update_action] properties: policy: {"$ref": "#/components/schemas/AdminRiskPolicy"} history: type: array maxItems: 30 items: {"$ref": "#/components/schemas/AdminRiskPolicyChange"} update_action: {"$ref": "#/components/schemas/InteractionAction"} AdminRiskPolicyUpdate: type: object additionalProperties: false required: [expected_version, config, reason_code] properties: expected_version: {type: integer, format: int64, minimum: 1} config: {"$ref": "#/components/schemas/AdminRiskPolicyConfig"} reason_code: {type: string, enum: [operating_policy, correction, other], x-enum-varnames: [RiskPolicyUpdateOperatingPolicy, RiskPolicyUpdateCorrection, RiskPolicyUpdateOther]} note: {type: string, maxLength: 1900} AdminRiskReviewEventDecisionReason: type: string enum: [reviewed_no_issue, known_player, expected_activity, false_positive, awaiting_information, keep_monitoring, other, legacy_unspecified] x-enum-varnames: [RiskEventReviewedNoIssue, RiskEventKnownPlayer, RiskEventExpectedActivity, RiskEventFalsePositive, RiskEventAwaitingInformation, RiskEventKeepMonitoring, RiskEventOther, RiskEventLegacyUnspecified] AdminRiskReviewCategory: type: string enum: [player_risk, provider_operations] AdminRiskReviewView: type: string default: outstanding enum: [outstanding, history, all] AdminRiskReviewStateFilter: type: string default: all description: Operational list filter including all states; expired snoozes appear pending. enum: [all, pending, acknowledged, snoozed, cleared] AdminRiskReviewState: type: string enum: [pending, acknowledged, snoozed, cleared] AdminRiskReviewAction: type: string enum: [note, acknowledge, snooze] AdminRiskReviewAvailableAction: type: object required: [code, label, enabled, disabled_reason] properties: code: "$ref": "#/components/schemas/AdminRiskReviewAction" label: {type: string} enabled: {type: boolean} disabled_reason: {type: string} AdminRiskReview: type: object required: [id, user_id, email, display_name, category, state, fingerprint, evidence, evidence_refreshed_at, updated_at, requires_attention, actions] properties: id: {type: string, format: uuid} user_id: {type: string, format: uuid} email: {type: string} display_name: type: string description: The reviewed player's display name (users.display_name, never empty). category: "$ref": "#/components/schemas/AdminRiskReviewCategory" state: "$ref": "#/components/schemas/AdminRiskReviewState" fingerprint: {type: string} evidence: type: array items: "$ref": "#/components/schemas/AdminPlayer360RiskSignal" evidence_refreshed_at: type: string format: date-time description: When the background refresh took the stored evidence snapshot. Decisions act on this snapshot. updated_at: {type: string, format: date-time} snoozed_until: {type: string, format: date-time} requires_attention: {type: boolean} actions: type: array items: "$ref": "#/components/schemas/AdminRiskReviewAvailableAction" AdminRiskReviewEventSource: type: string description: operator events are decisions by actor_id; system events are state transitions made by the background refresh. enum: [operator, system] x-enum-varnames: [AdminRiskReviewEventSourceOperator, AdminRiskReviewEventSourceSystem] AdminRiskReviewEventAction: type: string enum: [note, acknowledge, snooze, reopen, clear, open] x-enum-varnames: [AdminRiskReviewEventActionNote, AdminRiskReviewEventActionAcknowledge, AdminRiskReviewEventActionSnooze, AdminRiskReviewEventActionReopen, AdminRiskReviewEventActionClear, AdminRiskReviewEventActionOpen] AdminRiskReviewEventReasonCode: type: string description: Why the background refresh moved the review. new_evidence and evidence_returned reopen; evidence_absent and player_excluded clear. enum: [new_evidence, evidence_returned, evidence_absent, player_excluded, evidence_created, routine_repeat, policy_changed, policy_cutover] x-enum-varnames: [AdminRiskReviewEventReasonNewEvidence, AdminRiskReviewEventReasonEvidenceReturned, AdminRiskReviewEventReasonEvidenceAbsent, AdminRiskReviewEventReasonPlayerExcluded, AdminRiskReviewEventReasonEvidenceCreated, AdminRiskReviewEventReasonRoutineRepeat, AdminRiskReviewEventReasonPolicyChanged, AdminRiskReviewEventReasonPolicyCutover] AdminRiskReviewEvent: type: object required: [id, source, action, reason, fingerprint, created_at, evidence] properties: id: {type: string, format: uuid} source: "$ref": "#/components/schemas/AdminRiskReviewEventSource" actor_id: type: string format: uuid description: Present on operator events only. action: "$ref": "#/components/schemas/AdminRiskReviewEventAction" reason: type: string description: Audit text the server composed from the operator decision_reason_code and note; empty on system events, which carry reason_code. decision_reason_code: "$ref": "#/components/schemas/AdminRiskReviewEventDecisionReason" reason_code: "$ref": "#/components/schemas/AdminRiskReviewEventReasonCode" previous_state: "$ref": "#/components/schemas/AdminRiskReviewState" next_state: "$ref": "#/components/schemas/AdminRiskReviewState" fingerprint: {type: string} created_at: {type: string, format: date-time} snoozed_until: {type: string, format: date-time} evidence: description: Immutable snapshot of the evidence reviewed for this decision. type: array items: "$ref": "#/components/schemas/AdminPlayer360RiskSignal" AdminRiskReviewsResponse: type: object required: [reviews, outstanding_count, pagination] properties: reviews: type: array items: "$ref": "#/components/schemas/AdminRiskReview" outstanding_count: {type: integer, format: int64, minimum: 0} pagination: "$ref": "#/components/schemas/Pagination" AdminRiskReviewDetailResponse: type: object required: [review, events] properties: review: "$ref": "#/components/schemas/AdminRiskReview" events: type: array items: "$ref": "#/components/schemas/AdminRiskReviewEvent" AdminRiskDecisionReason: type: string description: Why an operator noted, acknowledged or snoozed a risk review. enum: [reviewed_no_issue, known_player, expected_activity, false_positive, awaiting_information, keep_monitoring, other] x-enum-varnames: - AdminRiskDecisionReasonReviewedNoIssue - AdminRiskDecisionReasonKnownPlayer - AdminRiskDecisionReasonExpectedActivity - AdminRiskDecisionReasonFalsePositive - AdminRiskDecisionReasonAwaitingInformation - AdminRiskDecisionReasonKeepMonitoring - AdminRiskDecisionReasonOther AdminDepositRecheckResponse: type: object required: [payment_id, user_id, state, effects] properties: payment_id: {type: string, format: uuid} user_id: {type: string, format: uuid} state: {"$ref": "#/components/schemas/PaymentDepositState"} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} AdminTransferRecoveryResponse: type: object required: [transfer_id, user_id, state, effects] properties: transfer_id: {type: string, format: uuid} user_id: {type: string, format: uuid} state: {"$ref": "#/components/schemas/ProviderTransferState"} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} AdminPlayerPendingActionKind: type: string enum: [mark_paid, withdrawal_review, financial_case, transfer_reconcile, game_cashout_review, first_withdrawal_review, manual_claim, payment_deposit, account_credentials, account_repair, retry_setup, setup_investigate, risk_review] AdminPlayerPendingAction: type: object required: [key, kind, source_id, source_state, title, message, since, priority, action_label, action_enabled, read_only, requires_confirmation] properties: key: {type: string} kind: {"$ref": "#/components/schemas/AdminPlayerPendingActionKind"} source_id: {type: string, format: uuid} source_state: {type: string} title: {type: string} message: {type: string} since: {type: string, format: date-time} priority: {type: integer, minimum: 1, maximum: 5} amount_cents: {type: integer, format: int64, minimum: 0} expires_at: {type: string, format: date-time} action_label: {type: string} action_enabled: {type: boolean} read_only: {type: boolean} requires_confirmation: {type: boolean} case_kind: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} provider_code: {type: string} provider_label: {type: string} username: {type: string} conversation_id: {type: string, format: uuid} set_password_enabled: {type: boolean} reset_password_enabled: {type: boolean} AdminPlayerPendingActions: type: object required: [user_id, as_of, total, items, poll_interval_ms] properties: user_id: {type: string, format: uuid} as_of: {type: string, format: date-time} total: {type: integer, format: int64, minimum: 0} items: type: array items: {"$ref": "#/components/schemas/AdminPlayerPendingAction"} next_offset: {type: integer, minimum: 0} poll_interval_ms: {type: integer, enum: [15000]} AdminProviderSetupRetryReason: type: string enum: [player_requested, provider_configuration_fixed, temporary_failure_resolved, other] AdminProviderSetupRetryRequest: type: object additionalProperties: false required: [reason_code] properties: reason_code: {"$ref": "#/components/schemas/AdminProviderSetupRetryReason"} note: {type: string, maxLength: 500, description: Required with at least 3 characters for other. Never include passwords.} AdminProviderSetupRetryResponse: type: object required: [provisioning_id, user_id, state, replayed, effects] properties: provisioning_id: {type: string, format: uuid} user_id: {type: string, format: uuid} state: {type: string, enum: [queued, succeeded]} replayed: {type: boolean} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} AdminRiskReviewCommand: type: object required: [action, reason_code, expected_fingerprint] properties: action: "$ref": "#/components/schemas/AdminRiskReviewAction" reason_code: "$ref": "#/components/schemas/AdminRiskDecisionReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. expected_fingerprint: {type: string, minLength: 64, maxLength: 64} snoozed_until: {type: string, format: date-time} PlayerModerationStatus: type: string description: Legal moderation command targets; pending verification is not an activation target. enum: [active, suspended, banned] AdminPlayerModerationCommand: type: object required: [status, expected_status, reason] properties: status: "$ref": "#/components/schemas/PlayerModerationStatus" expected_status: "$ref": "#/components/schemas/UserStatus" reason: {type: string, minLength: 3, maxLength: 2000} AdminPlayerModerationResponse: type: object required: [user_id, status, sessions_revoked, actions] properties: user_id: {type: string, format: uuid} status: "$ref": "#/components/schemas/UserStatus" sessions_revoked: {type: boolean} actions: type: array items: "$ref": "#/components/schemas/AdminPlayerModerationAvailableAction" AdminPlayerModerationAvailableAction: type: object required: [status, label, enabled, disabled_reason] properties: status: "$ref": "#/components/schemas/PlayerModerationStatus" label: {type: string} enabled: {type: boolean} disabled_reason: {type: string} AdminPlayer360RiskLevel: type: string enum: - low - elevated - high x-enum-varnames: - AdminPlayer360RiskLevelLow - AdminPlayer360RiskLevelElevated - AdminPlayer360RiskLevelHigh AdminPlayer360Window: type: string enum: - 24h - 7d - 30d - lifetime AdminPlayer360PlayerSummary: type: object required: - user_id - email - display_name - status - is_system_account - created_at - latest_activity_at - completed_deposit_count - completed_deposit_amount - completed_provider_load_count - completed_provider_load_amount - completed_provider_unload_count - completed_provider_unload_amount - completed_provider_net_amount - payout_count - payout_amount - realized_net_amount - open_exposure_amount - reconciliation_count - failure_count_7d - deposit_velocity_count_24h - provider_transfer_velocity_count_24h - withdrawal_velocity_count_24h - destination_reuse_count - fingerprint_reuse_count - active_risk_signal_count - open_risk_review_ids - risk_level properties: user_id: type: string format: uuid email: type: string format: email display_name: type: string status: "$ref": "#/components/schemas/UserStatus" is_system_account: type: boolean created_at: type: string format: date-time latest_activity_at: type: string format: date-time completed_deposit_count: type: integer format: int64 minimum: 0 completed_deposit_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_load_count: type: integer format: int64 minimum: 0 completed_provider_load_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_unload_count: type: integer format: int64 minimum: 0 completed_provider_unload_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_net_amount: description: Completed provider unload amount minus completed provider load amount. Positive values mean the player returned more from games than they loaded. "$ref": "#/components/schemas/MoneyAmount" payout_count: type: integer format: int64 minimum: 0 payout_amount: "$ref": "#/components/schemas/MoneyAmount" realized_net_amount: description: Completed deposit amount minus successful payment-withdrawal net payout amount. Provider loads and unloads are internal movements and do not change this value. "$ref": "#/components/schemas/MoneyAmount" open_exposure_amount: description: Sum of unresolved deposits, nonterminal provider transfers, and nonterminal payment withdrawals. This is an operational exposure measure, not an accounting balance. "$ref": "#/components/schemas/MoneyAmount" reconciliation_count: type: integer format: int64 minimum: 0 failure_count_7d: type: integer format: int64 minimum: 0 deposit_velocity_count_24h: type: integer format: int64 minimum: 0 provider_transfer_velocity_count_24h: type: integer format: int64 minimum: 0 withdrawal_velocity_count_24h: type: integer format: int64 minimum: 0 destination_reuse_count: description: Count of this player's keyed destination hashes also associated with another player. type: integer format: int64 minimum: 0 fingerprint_reuse_count: description: Count of this player's keyed fingerprint hashes also associated with another player. type: integer format: int64 minimum: 0 active_risk_signal_count: type: integer format: int64 minimum: 0 open_risk_review_ids: description: Risk reviews of this player that currently need attention (pending, or snoozed and due), newest first. Each id opens /admin/flags/reviews/{id}. type: array items: type: string format: uuid risk_level: "$ref": "#/components/schemas/AdminPlayer360RiskLevel" AdminPlayer360PlayersResponse: type: object required: - as_of - rule_version - players - pagination properties: as_of: type: string format: date-time rule_version: type: string players: type: array items: "$ref": "#/components/schemas/AdminPlayer360PlayerSummary" pagination: "$ref": "#/components/schemas/Pagination" AdminPlayer360Aggregate: type: object required: - window - as_of - completed_deposit_count - completed_deposit_amount - completed_provider_load_count - completed_provider_load_amount - completed_provider_unload_count - completed_provider_unload_amount - completed_provider_net_amount - payout_count - payout_gross_amount - payout_net_amount - ledger_transaction_count - realized_net_amount - open_deposit_exposure_amount - open_provider_exposure_amount - open_withdrawal_exposure_amount - open_exposure_amount - payout_to_deposit_ratio - reconciliation_count - failure_count properties: window: "$ref": "#/components/schemas/AdminPlayer360Window" window_start: type: string format: date-time nullable: true as_of: type: string format: date-time completed_deposit_count: type: integer format: int64 minimum: 0 completed_deposit_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_load_count: type: integer format: int64 minimum: 0 completed_provider_load_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_unload_count: type: integer format: int64 minimum: 0 completed_provider_unload_amount: "$ref": "#/components/schemas/MoneyAmount" completed_provider_net_amount: description: Completed provider unload amount minus completed provider load amount for this window. "$ref": "#/components/schemas/MoneyAmount" payout_count: type: integer format: int64 minimum: 0 payout_gross_amount: "$ref": "#/components/schemas/MoneyAmount" payout_net_amount: "$ref": "#/components/schemas/MoneyAmount" ledger_transaction_count: type: integer format: int64 minimum: 0 realized_net_amount: "$ref": "#/components/schemas/MoneyAmount" open_deposit_exposure_amount: "$ref": "#/components/schemas/MoneyAmount" open_provider_exposure_amount: "$ref": "#/components/schemas/MoneyAmount" open_withdrawal_exposure_amount: "$ref": "#/components/schemas/MoneyAmount" open_exposure_amount: "$ref": "#/components/schemas/MoneyAmount" payout_to_deposit_ratio: description: Successful net payout divided by completed deposit amount. Zero when the completed deposit amount is zero. type: number format: double minimum: 0 reconciliation_count: type: integer format: int64 minimum: 0 failure_count: type: integer format: int64 minimum: 0 AdminPlayer360RiskSignalKey: type: string enum: - deposit_velocity_24h - provider_transfer_velocity_24h - withdrawal_velocity_24h - reconciliation_required - failure_velocity_7d - destination_reuse - fingerprint_reuse x-enum-varnames: - DepositVelocity24h - ProviderTransferVelocity24h - WithdrawalVelocity24h - ReconciliationRequired - FailureVelocity7d - DestinationReuse - FingerprintReuse AdminPlayer360RiskSignalSeverity: type: string enum: [elevated, high] x-enum-varnames: - AdminPlayer360RiskSignalSeverityElevated - AdminPlayer360RiskSignalSeverityHigh AdminPlayer360RiskSignal: type: object required: - key - severity - window - observed_count - threshold_count - observed_amount - source_type - source_ids - source_ids_truncated - explanation - rule_version - mode - policy_version properties: mode: {"$ref": "#/components/schemas/RiskPolicyMode"} policy_version: {type: integer, format: int64, minimum: 1} key: "$ref": "#/components/schemas/AdminPlayer360RiskSignalKey" severity: "$ref": "#/components/schemas/AdminPlayer360RiskSignalSeverity" window: "$ref": "#/components/schemas/AdminPlayer360Window" observed_count: type: integer format: int64 minimum: 0 threshold_count: type: integer format: int64 minimum: 1 observed_amount: "$ref": "#/components/schemas/MoneyAmount" source_type: type: string enum: - deposit - provider_transfer - withdrawal source_ids: type: array maxItems: 25 items: type: string format: uuid source_ids_truncated: type: boolean source_membership_hash: description: SHA-256 of the complete unresolved record ID set, preserving change detection when source_ids is truncated. type: string nullable: true pattern: '^[0-9a-f]{64}$' correlation_hash: description: Optional keyed HMAC-SHA256 value. Raw destinations and fingerprints are never returned. type: string pattern: "^[0-9a-f]{64}$" nullable: true correlated_player_count: type: integer format: int64 minimum: 2 nullable: true explanation: type: string rule_version: type: string AdminPlayer360DetailResponse: type: object required: - as_of - rule_version - player - wallet - aggregates - risk_signals properties: bonus_only_cycle: {$ref: "#/components/schemas/BonusOnlyCycle", nullable: true, description: Frozen Bonus-only source terms and server-calculated cash-out progress.} as_of: type: string format: date-time rule_version: type: string player: "$ref": "#/components/schemas/AdminPlayer360PlayerSummary" wallet: "$ref": "#/components/schemas/WalletSnapshot" aggregates: type: array minItems: 4 maxItems: 4 items: "$ref": "#/components/schemas/AdminPlayer360Aggregate" risk_signals: type: array items: "$ref": "#/components/schemas/AdminPlayer360RiskSignal" AdminPlayer360Deposit: type: object required: - id - provider_code - state - amount - reconciliation_required - created_at - updated_at properties: id: type: string format: uuid provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" state: "$ref": "#/components/schemas/PaymentDepositState" amount: "$ref": "#/components/schemas/MoneyAmount" reconciliation_required: type: boolean completed_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time AdminPlayer360DepositsResponse: type: object required: - as_of - deposits - pagination properties: as_of: type: string format: date-time deposits: type: array items: "$ref": "#/components/schemas/AdminPlayer360Deposit" pagination: "$ref": "#/components/schemas/Pagination" AdminPlayer360LedgerBucketChanges: type: object required: - deposit_bonus - cash - withdrawable_cash - pending_withdrawal - forfeit properties: deposit_bonus: "$ref": "#/components/schemas/MoneyAmount" cash: "$ref": "#/components/schemas/MoneyAmount" withdrawable_cash: "$ref": "#/components/schemas/MoneyAmount" pending_withdrawal: "$ref": "#/components/schemas/MoneyAmount" forfeit: "$ref": "#/components/schemas/MoneyAmount" AdminLedgerTransactionKind: type: string enum: - deposit_bonus_grant - deposit_bonus_clawback - deposit_bonus_recovery - deposit_reversal - wallet_credit - wallet_debit - provider_cashout_forfeit - withdrawal_reserve - withdrawal_release - withdrawal_settle - provider_load_reserve - provider_load_refund - provider_cashout_settle - provider_cashout_hold - provider_cashout_restore - provider_reviewed_unload_settle AdminPlayer360LedgerTransaction: type: object required: - id - kind - bucket_changes - created_at properties: id: type: string format: uuid kind: "$ref": "#/components/schemas/AdminLedgerTransactionKind" bucket_changes: "$ref": "#/components/schemas/AdminPlayer360LedgerBucketChanges" created_at: type: string format: date-time AdminPlayer360LedgerResponse: type: object required: - as_of - transactions - pagination properties: as_of: type: string format: date-time transactions: type: array items: "$ref": "#/components/schemas/AdminPlayer360LedgerTransaction" pagination: "$ref": "#/components/schemas/Pagination" AdminPaymentEvent: type: object required: - id - provider_code - event_type - evidence - created_at properties: id: type: string format: uuid payment_intent_id: type: string format: uuid nullable: true provider_code: "$ref": "#/components/schemas/PaymentDepositProviderCode" event_type: type: string provider_transaction_id: type: string nullable: true signature_valid: type: boolean nullable: true content_type: type: string nullable: true evidence: type: object additionalProperties: true actor_id: type: string format: uuid nullable: true source: type: string nullable: true prior_state: "$ref": "#/components/schemas/PaymentDepositState" nullable: true new_state: "$ref": "#/components/schemas/PaymentDepositState" nullable: true reason: type: string nullable: true created_at: type: string format: date-time AdminPaymentDepositDetailResponse: type: object required: - payment - events - proof_assets - reversal_attempts properties: payment: "$ref": "#/components/schemas/AdminPaymentDeposit" events: type: array items: "$ref": "#/components/schemas/AdminPaymentEvent" proof_assets: type: array items: "$ref": "#/components/schemas/AdminDepositProofAsset" reversal_attempts: type: array items: "$ref": "#/components/schemas/AdminOffAppDepositReversalAttempt" AdminPaymentWithdrawalTier: description: Operator triage classification for withdrawal/cashout handling. type: string enum: - pending - needs_review - paid - failed AdminPaymentWithdrawalQueue: description: Stable operator-inbox classification. Unknown and nonterminal lifecycle states remain open. type: string enum: - open - paid - closed x-enum-varnames: - AdminPaymentWithdrawalQueueOpen - AdminPaymentWithdrawalQueuePaid - AdminPaymentWithdrawalQueueClosed PayoutBoardRange: type: string description: How far back done_recent and the paid totals reach. enum: [today, 7d, 30d] default: today x-enum-varnames: - PayoutBoardRangeToday - PayoutBoardRange7d - PayoutBoardRange30d PayoutMode: type: string description: manual when an admin sends the money by hand and marks it paid; automatic when the payment provider sends it. enum: [manual, automatic] x-enum-varnames: - PayoutModeManual - PayoutModeAutomatic PayoutBoardPlayer: type: object required: [id, email, display_name] properties: id: {type: string, format: uuid} email: {type: string} display_name: {type: string} alias: {type: string, nullable: true, description: "The player's first active alias; staff lists show it before the system name."} PayoutRiskSignal: type: object required: [key, severity, observed_count] properties: key: {"$ref": "#/components/schemas/AdminPlayer360RiskSignalKey"} severity: {"$ref": "#/components/schemas/AdminPlayer360RiskSignalSeverity"} observed_count: {type: integer, format: int64, minimum: 0} PayoutRisk: type: object description: Named signals from the player's stored, not cleared risk reviews; level is the highest signal severity. required: [level, signals] properties: level: {"$ref": "#/components/schemas/AdminPlayer360RiskSignalSeverity"} signals: type: array items: {"$ref": "#/components/schemas/PayoutRiskSignal"} PayoutProof: type: object required: [has_proof] properties: has_proof: type: boolean description: A finalized settlement proof is attached. provider_transaction_id: {type: string} PayoutSourceGame: type: object required: [provider_code, label] properties: provider_code: {"$ref": "#/components/schemas/ProviderCode"} label: {type: string} PayoutRow: type: object required: [id, player, provider_code, state, operator_status, mode, amount_cents, since, created_at, late, proof] properties: id: {type: string, format: uuid} player: {"$ref": "#/components/schemas/PayoutBoardPlayer"} provider_code: {"$ref": "#/components/schemas/PaymentWithdrawalProviderCode"} state: {"$ref": "#/components/schemas/PaymentWithdrawalState"} operator_status: {"$ref": "#/components/schemas/AdminPaymentWithdrawalOperatorStatus"} mode: {"$ref": "#/components/schemas/PayoutMode"} can_claim_to_pay: {type: boolean, description: PlayGo allows opening Approve from the board for this pending hand-paid request. The claim is checked again when opened.} method: "$ref": "#/components/schemas/PaymentWithdrawalDestinationKind" destination: "$ref": "#/components/schemas/PaymentWithdrawalDestination" amount_cents: {type: integer, format: int64} fee_cents: type: integer format: int64 description: Actual fee once paid, otherwise the quoted fee. net_cents: type: integer format: int64 description: Actual net once paid, otherwise the quoted net. since: type: string format: date-time description: When the payout last changed state. created_at: {type: string, format: date-time} completed_at: {type: string, format: date-time} expected_by: type: string format: date-time description: When an open payout becomes late under the payout settings. late: {type: boolean} expires_at: type: string format: date-time description: When the approval or the player's provider action expires. risk: {"$ref": "#/components/schemas/PayoutRisk"} proof: {"$ref": "#/components/schemas/PayoutProof"} source_game: {"$ref": "#/components/schemas/PayoutSourceGame"} cycle_loaded_cents: type: integer format: int64 description: Completed load principal on the source game account in the cash-out cycle that funded most of this payout. cycle_won_cents: type: integer format: int64 description: The cash-out that ended that cycle. retried_at: type: string format: date-time description: The provider refused this automatic payout without sending it and it was retried once at this time. A payout that failed again after its retry is a problem. PayoutLane: type: object required: [count, rows, first_cashouts] properties: count: type: integer format: int64 minimum: 0 description: Everything in the lane. In needs_you it also counts the first cash-outs waiting for an admin, so it is the Payouts badge. rows: type: array items: {"$ref": "#/components/schemas/PayoutRow"} first_cashouts: type: array description: needs_you only (empty in the other lanes) - linked game accounts' first cash-outs waiting for an admin, oldest first, at most lane_limit. items: {"$ref": "#/components/schemas/PayoutFirstCashout"} PayoutFirstCashoutState: type: string enum: [pending, approving, settling, reconcile_required] x-enum-varnames: [PayoutFirstCashoutStatePending, PayoutFirstCashoutStateApproving, PayoutFirstCashoutStateSettling, PayoutFirstCashoutStateReconcileRequired] PayoutFirstCashout: type: object description: A linked game account's first cash-out under review; open it with the cash-out review id. required: [review_id, player, game, state, reviewed_credits, reviewed_credits_whole, since] properties: review_id: {type: string, format: uuid} player: {"$ref": "#/components/schemas/PayoutBoardPlayer"} game: {"$ref": "#/components/schemas/PayoutSourceGame"} state: {"$ref": "#/components/schemas/PayoutFirstCashoutState"} reviewed_credits: type: integer format: int64 description: The reviewed game balance in provider credits, 0 unless reviewed_credits_whole (it is never rounded). reviewed_credits_whole: {type: boolean} approved_payout_cents: type: integer format: int64 description: The approved payout, once an admin approved it. since: type: string format: date-time description: When the player asked to cash out. PayoutBoardLanes: type: object required: [needs_you, to_pay, paid, in_flight, problems, done_recent] properties: needs_you: {"$ref": "#/components/schemas/PayoutLane"} to_pay: {"$ref": "#/components/schemas/PayoutLane"} paid: {"$ref": "#/components/schemas/PayoutLane"} in_flight: {"$ref": "#/components/schemas/PayoutLane"} problems: {"$ref": "#/components/schemas/PayoutLane"} done_recent: {"$ref": "#/components/schemas/PayoutLane"} PayoutMethodTotal: type: object required: [method, paid_cents, paid_count] properties: method: {"$ref": "#/components/schemas/PaymentWithdrawalDestinationKind"} paid_cents: {type: integer, format: int64} paid_count: {type: integer, format: int64} PayoutBoardTotals: type: object required: [paid_cents, paid_count, pending_cents, pending_count, by_method] properties: paid_cents: {type: integer, format: int64} paid_count: {type: integer, format: int64} pending_cents: {type: integer, format: int64} pending_count: {type: integer, format: int64} by_method: type: array items: {"$ref": "#/components/schemas/PayoutMethodTotal"} PayoutBoard: type: object required: [range, since, generated_at, settings, lanes, totals] properties: range: {"$ref": "#/components/schemas/PayoutBoardRange"} since: type: string format: date-time description: Start of the range. generated_at: {type: string, format: date-time} settings: {"$ref": "#/components/schemas/PayoutSettings"} lanes: {"$ref": "#/components/schemas/PayoutBoardLanes"} totals: {"$ref": "#/components/schemas/PayoutBoardTotals"} PayoutSettings: type: object required: [manual_late_after_minutes, automatic_late_after_minutes, proof_required, version, updated_at] properties: manual_late_after_minutes: {type: integer, format: int64} automatic_late_after_minutes: {type: integer, format: int64} proof_required: type: boolean description: A manual mark-paid needs a finalized proof upload. version: {type: integer, format: int64} updated_by: {type: string, format: uuid} updated_at: {type: string, format: date-time} PayoutSettingsChangeReason: type: string enum: [operating_policy, correction, other] x-enum-varnames: - PayoutSettingsChangeReasonOperatingPolicy - PayoutSettingsChangeReasonCorrection - PayoutSettingsChangeReasonOther PayoutSettingsChange: type: object required: [version, previous, next, actor_id, reason_code, created_at] properties: version: {type: integer, format: int64} previous: {"$ref": "#/components/schemas/PayoutSettingsValues"} next: {"$ref": "#/components/schemas/PayoutSettingsValues"} actor_id: {type: string, format: uuid} reason_code: {"$ref": "#/components/schemas/PayoutSettingsChangeReason"} note: {type: string} created_at: {type: string, format: date-time} PayoutSettingsValues: type: object required: [manual_late_after_minutes, automatic_late_after_minutes, proof_required] properties: manual_late_after_minutes: {type: integer, format: int64} automatic_late_after_minutes: {type: integer, format: int64} proof_required: {type: boolean} PayoutSettingsResponse: type: object required: [settings, history] properties: settings: {"$ref": "#/components/schemas/PayoutSettings"} history: type: array description: The most recent changes, newest first. items: {"$ref": "#/components/schemas/PayoutSettingsChange"} CloseoutItemKind: type: string description: deposit is a provider checkout; off_app_draft is an unsettled off-app deposit draft. enum: [deposit, off_app_draft] x-enum-varnames: [CloseoutItemKindDeposit, CloseoutItemKindOffAppDraft] CloseoutProviderCheck: type: string description: How a listed item may be closed. provider_unpaid means the provider's status lookup has no payment for the checkout. not_checkable means the provider has no status lookup, or the item is an off-app draft, so it is closeable on age; a late success opens a case. enum: [provider_unpaid, not_checkable] x-enum-varnames: [CloseoutProviderCheckProviderUnpaid, CloseoutProviderCheckNotCheckable] CloseoutExclusionReason: type: string description: Why a candidate was left out. provider_resolved means the provider check resolved the deposit (paid and credited, or failed); state is its new state. check_failed means the status lookup errored, timed out or did not run within the preview's budget, so the outcome is unknown and the deposit is resolved one by one. provider_inconclusive means the provider reports a status that is not an affirmative non-payment (still processing, refunded). enum: [provider_resolved, check_failed, provider_inconclusive] x-enum-varnames: [CloseoutExclusionReasonProviderResolved, CloseoutExclusionReasonCheckFailed, CloseoutExclusionReasonProviderInconclusive] CloseoutReason: type: string description: Why the items are closed. enum: [never_paid, player_abandoned, test_cleanup, other] x-enum-varnames: [CloseoutReasonNeverPaid, CloseoutReasonPlayerAbandoned, CloseoutReasonTestCleanup, CloseoutReasonOther] CloseoutEffect: type: object required: [to_state, wallet_change_cents] properties: to_state: {"$ref": "#/components/schemas/PaymentDepositState"} wallet_change_cents: {type: integer, format: int64, description: Always 0; closing never moves money.} CloseoutItem: type: object required: [kind, id, user_id, user_email, provider_code, state, amount_cents, created_at, waiting_since, provider_check, effect] properties: kind: {"$ref": "#/components/schemas/CloseoutItemKind"} id: {type: string, format: uuid} user_id: {type: string, format: uuid} user_email: {type: string} provider_code: {"$ref": "#/components/schemas/PaymentDepositProviderCode"} state: {"$ref": "#/components/schemas/PaymentDepositState"} amount_cents: {type: integer, format: int64} created_at: {type: string, format: date-time} waiting_since: {type: string, format: date-time, description: When the item entered its state.} provider_check: {"$ref": "#/components/schemas/CloseoutProviderCheck"} effect: {"$ref": "#/components/schemas/CloseoutEffect"} CloseoutExclusion: type: object required: [kind, id, reason, state] properties: kind: {"$ref": "#/components/schemas/CloseoutItemKind"} id: {type: string, format: uuid} reason: {"$ref": "#/components/schemas/CloseoutExclusionReason"} state: {"$ref": "#/components/schemas/PaymentDepositState"} CloseoutTotal: type: object required: [count, amount_cents] properties: count: {type: integer, format: int32} amount_cents: {type: integer, format: int64, description: Sum of the items' never-paid amounts, computed by the database.} CloseoutPreview: type: object required: [items, excluded, total, has_more] properties: token: {type: string, description: Absent when there is nothing to close.} expires_at: {type: string, format: date-time} items: type: array items: {"$ref": "#/components/schemas/CloseoutItem"} excluded: type: array items: {"$ref": "#/components/schemas/CloseoutExclusion"} total: {"$ref": "#/components/schemas/CloseoutTotal"} has_more: {type: boolean} CloseoutRequest: type: object required: [token, reason_code] properties: token: {type: string, minLength: 1, maxLength: 200} reason_code: {"$ref": "#/components/schemas/CloseoutReason"} note: {type: string, maxLength: 400, description: Required when reason_code is other.} CloseoutConflictReason: type: string enum: [token_used, token_expired, token_foreign, items_changed] x-enum-varnames: [CloseoutConflictReasonTokenUsed, CloseoutConflictReasonTokenExpired, CloseoutConflictReasonTokenForeign, CloseoutConflictReasonItemsChanged] CloseoutConflict: type: object required: [error, reason] properties: error: {"$ref": "#/components/schemas/APIError"} reason: {"$ref": "#/components/schemas/CloseoutConflictReason"} closed_count: {type: integer, format: int32, description: token_used only - how many items the original confirm closed.} ids: type: array description: token_used only - the items the original confirm closed. items: {type: string, format: uuid} CloseoutResult: type: object required: [closed_count, ids] properties: closed_count: {type: integer, format: int32} ids: type: array items: {type: string, format: uuid} BonusRuleChangeReason: type: string description: Why a bonus rule, scheme, enrolment or perk tier changed. referral_tier is written only by automatic perk-tier enrolment; a request that sends it is a 400. enum: [promo_launch, budget_change, abuse_response, correction, vip_request, streamer_partner, support_goodwill, other, referral_tier] x-enum-varnames: - BonusRuleChangeReasonPromoLaunch - BonusRuleChangeReasonBudgetChange - BonusRuleChangeReasonAbuseResponse - BonusRuleChangeReasonCorrection - BonusRuleChangeReasonVipRequest - BonusRuleChangeReasonStreamerPartner - BonusRuleChangeReasonSupportGoodwill - BonusRuleChangeReasonOther - BonusRuleChangeReasonReferralTier BonusPercentMatchRule: type: object additionalProperties: false required: [percent_bps, cap_cents] properties: percent_bps: {type: integer, format: int32, minimum: 100, maximum: 10000, multipleOf: 100} cap_cents: {type: integer, format: int64, minimum: 100, maximum: 100000} BonusEveryDepositRule: type: object additionalProperties: false description: A percentage of every qualifying deposit, paid as freeplay, with an optional cap per deposit. Empty ({percent_bps 0, cap_cents 0}) means inactive; there is no default. It is set by saving a percentage, takes effect on the next qualifying deposit, has no daily count limit and is not covered by the daily freeplay ceiling. A deposit that also earns the first- or second-deposit match pays only the larger. required: [percent_bps, cap_cents] properties: percent_bps: {type: integer, format: int32, minimum: 0, maximum: 10000, multipleOf: 100, description: "Basis points in whole percents; 0 = inactive."} cap_cents: {type: integer, format: int64, minimum: 0, maximum: 100000, description: "Most freeplay one deposit earns (at least 100); 0 = no cap. Only with a percentage."} BonusConsistentDepositRule: type: object additionalProperties: false required: [min_deposits, percent_bps, cap_cents] properties: min_deposits: {type: integer, format: int64, minimum: 1, maximum: 50} percent_bps: {type: integer, format: int32, minimum: 100, maximum: 10000, multipleOf: 100} cap_cents: {type: integer, format: int64, minimum: 100, maximum: 100000} BonusFixedFreeplayRule: type: object additionalProperties: false required: [freeplay_cents] properties: freeplay_cents: {type: integer, format: int64, minimum: 1, maximum: 100000} BonusQualifyingDaysRule: type: object additionalProperties: false required: [min_days, freeplay_cents] properties: min_days: {type: integer, format: int64, minimum: 1, maximum: 7} freeplay_cents: {type: integer, format: int64, minimum: 1, maximum: 100000} BonusVolumeRule: type: object additionalProperties: false required: [min_volume_cents, freeplay_cents] properties: min_volume_cents: {type: integer, format: int64, minimum: 100, maximum: 10000000} freeplay_cents: {type: integer, format: int64, minimum: 1, maximum: 100000} BonusReferralReferrerRule: type: object additionalProperties: false description: Free play on the friend's first successful wallet deposit; flat plus percentage, floored and capped. required: [flat_cents, percent_bps, cap_cents] properties: flat_cents: {type: integer, format: int64, minimum: 0, maximum: 100000} percent_bps: {type: integer, format: int32, minimum: 0, maximum: 10000} cap_cents: {type: integer, format: int64, minimum: 1, maximum: 100000, description: At least flat_cents.} BonusReferralRefereeRule: type: object additionalProperties: false description: Free play on the first successful wallet deposit; flat plus percentage, floored and capped. required: [flat_cents, percent_bps, cap_cents] properties: flat_cents: {type: integer, format: int64, minimum: 0, maximum: 100000} percent_bps: {type: integer, format: int32, minimum: 0, maximum: 10000} cap_cents: {type: integer, format: int64, minimum: 1, maximum: 100000} BonusReferralMilestoneRule: type: object additionalProperties: false required: [referral_count, xp, bonus_cents] properties: referral_count: {type: integer, format: int64, minimum: 1, maximum: 1000} xp: {type: integer, format: int64, minimum: 0, maximum: 100000} bonus_cents: {type: integer, format: int64, minimum: 0, maximum: 100000} BonusReferralMilestones: type: object additionalProperties: false description: Counts must strictly increase from refer_5 to refer_20, and each milestone must pay XP or Bonus. required: [refer_5, refer_10, refer_20] properties: refer_5: {"$ref": "#/components/schemas/BonusReferralMilestoneRule"} refer_10: {"$ref": "#/components/schemas/BonusReferralMilestoneRule"} refer_20: {"$ref": "#/components/schemas/BonusReferralMilestoneRule"} BonusNextLoadTier: type: object additionalProperties: false required: [min_volume_cents, percent_bps, cap_cents] properties: min_volume_cents: {type: integer, format: int64, minimum: 100, maximum: 10000000} percent_bps: {type: integer, format: int32, minimum: 100, maximum: 10000, multipleOf: 100} cap_cents: {type: integer, format: int64, minimum: 100, maximum: 100000} BonusWeeklyNextLoadRule: type: object additionalProperties: false description: A Monday-Sunday New York week whose total successful deposits reach a tier's min_volume_cents earns, for the highest tier reached, a bonus of percent_bps of the next deposit, at most cap_cents, paid as freeplay. It is claimable during the following week and sets the player's pending next-deposit bonus. required: [tiers] properties: tiers: type: array minItems: 1 maxItems: 5 description: Thresholds strictly increase. items: {"$ref": "#/components/schemas/BonusNextLoadTier"} BonusLoginStreakRule: type: object additionalProperties: false description: A deposit-activated player who logs in (claims the daily login) on days consecutive New York days earns freeplay_cents once per run; a missed day starts a new run. required: [days, freeplay_cents] properties: days: {type: integer, format: int64, minimum: 2, maximum: 30} freeplay_cents: {type: integer, format: int64, minimum: 1, maximum: 100000} BonusRuleSwitches: type: object additionalProperties: false description: Whether each rule pays. A switched-off rule pays nothing to players without a scheme override for it. daily_freeplay_ceiling off means no ceiling. Referral side switches also gate all scheme candidates. required: [daily_deposit_match, second_deposit_match, daily_consistent_deposit, deposit_streak_3, weekly_consistent_deposit, weekly_high_roller, monthly_deposit_milestone, weekly_next_load, login_streak, referral_referrer, referral_referee, referral_milestones, daily_freeplay_ceiling] properties: daily_deposit_match: {type: boolean} second_deposit_match: {type: boolean} daily_consistent_deposit: {type: boolean} deposit_streak_3: {type: boolean} weekly_consistent_deposit: {type: boolean} weekly_high_roller: {type: boolean} monthly_deposit_milestone: {type: boolean} weekly_next_load: {type: boolean} login_streak: {type: boolean} referral_referrer: {type: boolean} referral_referee: {type: boolean} referral_milestones: {type: boolean} daily_freeplay_ceiling: {type: boolean} ReferralTrigger: type: string enum: [first_wallet_deposit, first_wallet_game_load] x-enum-varnames: [ReferralTriggerFirstWalletDeposit, ReferralTriggerFirstWalletGameLoad] BonusReferralQualification: type: object additionalProperties: false required: [trigger, minimum_deposit_cents] properties: trigger: {"$ref": "#/components/schemas/ReferralTrigger"} minimum_deposit_cents: {type: integer, format: int64, minimum: 0, maximum: 100000, description: Deposits below this threshold do not qualify. In game-load mode a positive threshold requires an earlier successful deposit meeting it.} BonusRuleValues: type: object additionalProperties: false description: Every bonus rule value (ADR 0023). Money is integer cents, percentages are basis points. Everything pays freeplay or XP, never withdrawable cash. required: [qualifying_deposit_min_cents, daily_deposit_match, second_deposit_match, every_deposit, daily_consistent_deposit, deposit_streak_3, weekly_consistent_deposit, weekly_high_roller, monthly_deposit_milestone, weekly_next_load, login_streak, referral_referrer, referral_referee, referral_qualification, referral_milestones, daily_freeplay_ceiling_cents, enabled] properties: qualifying_deposit_min_cents: type: integer format: int64 minimum: 499 maximum: 100000 description: The smallest deposit that counts toward deposit missions. Never below 499, the platform's qualifying minimum. daily_deposit_match: {"$ref": "#/components/schemas/BonusPercentMatchRule"} second_deposit_match: {"$ref": "#/components/schemas/BonusPercentMatchRule"} every_deposit: {"$ref": "#/components/schemas/BonusEveryDepositRule"} daily_consistent_deposit: {"$ref": "#/components/schemas/BonusConsistentDepositRule"} deposit_streak_3: {"$ref": "#/components/schemas/BonusFixedFreeplayRule"} weekly_consistent_deposit: {"$ref": "#/components/schemas/BonusQualifyingDaysRule"} weekly_high_roller: {"$ref": "#/components/schemas/BonusVolumeRule"} monthly_deposit_milestone: {"$ref": "#/components/schemas/BonusVolumeRule"} weekly_next_load: {"$ref": "#/components/schemas/BonusWeeklyNextLoadRule"} login_streak: {"$ref": "#/components/schemas/BonusLoginStreakRule"} referral_referrer: {"$ref": "#/components/schemas/BonusReferralReferrerRule"} referral_referee: {"$ref": "#/components/schemas/BonusReferralRefereeRule"} referral_qualification: {"$ref": "#/components/schemas/BonusReferralQualification"} referral_milestones: {"$ref": "#/components/schemas/BonusReferralMilestones"} daily_freeplay_ceiling_cents: type: integer format: int64 minimum: 100 maximum: 1000000 description: Per-player, per-New-York-day ceiling on freeplay from the daily rules listed in AdminBonusSettings.daily_ceiling_rules. Other rules, referral awards, admin grants and campaigns neither count nor are limited. A daily-rule claim is reduced to what is left today, and refused while nothing is left (it stays claimable in its grace window). enabled: {"$ref": "#/components/schemas/BonusRuleSwitches"} BonusRuleOverrides: type: object additionalProperties: false description: A scheme's sparse override of the base rules; each present rule replaces the whole base rule for enrolled players and applies even when the base rule is switched off. Referral keys apply to the enrolled player's referrals as the inviter. properties: daily_deposit_match: {"$ref": "#/components/schemas/BonusPercentMatchRule"} second_deposit_match: {"$ref": "#/components/schemas/BonusPercentMatchRule"} every_deposit: {"$ref": "#/components/schemas/BonusEveryDepositRule"} daily_consistent_deposit: {"$ref": "#/components/schemas/BonusConsistentDepositRule"} deposit_streak_3: {"$ref": "#/components/schemas/BonusFixedFreeplayRule"} weekly_consistent_deposit: {"$ref": "#/components/schemas/BonusQualifyingDaysRule"} weekly_high_roller: {"$ref": "#/components/schemas/BonusVolumeRule"} monthly_deposit_milestone: {"$ref": "#/components/schemas/BonusVolumeRule"} weekly_next_load: {"$ref": "#/components/schemas/BonusWeeklyNextLoadRule"} login_streak: {"$ref": "#/components/schemas/BonusLoginStreakRule"} referral_referrer: {"$ref": "#/components/schemas/BonusReferralReferrerRule"} referral_referee: {"$ref": "#/components/schemas/BonusReferralRefereeRule"} BonusRuleWinners: type: object additionalProperties: false description: Per overridable rule, the scheme whose rule is shown as effective; absent means the base rule. properties: daily_deposit_match: {type: string, format: uuid} second_deposit_match: {type: string, format: uuid} every_deposit: {type: string, format: uuid} daily_consistent_deposit: {type: string, format: uuid} deposit_streak_3: {type: string, format: uuid} weekly_consistent_deposit: {type: string, format: uuid} weekly_high_roller: {type: string, format: uuid} monthly_deposit_milestone: {type: string, format: uuid} weekly_next_load: {type: string, format: uuid} login_streak: {type: string, format: uuid} referral_referrer: {type: string, format: uuid} referral_referee: {type: string, format: uuid} AdminBonusSettings: type: object required: [version, updated_at, values, daily_ceiling_rules] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} daily_ceiling_rules: type: array description: The rule keys the daily freeplay ceiling covers (fixed by ADR 0023, read-only) - daily_deposit_match, second_deposit_match, daily_consistent_deposit and login_streak. items: {type: string} version: {type: integer, format: int64, minimum: 1} updated_at: {type: string, format: date-time} updated_by: {type: string, format: uuid, description: Absent for the seeded version 1.} updated_by_email: {type: string} values: {"$ref": "#/components/schemas/BonusRuleValues"} AdminBonusSettingsChange: type: object required: [version, previous, next, actor_id, actor_email, reason_code, created_at] properties: version: {type: integer, format: int64, minimum: 2} previous: {type: object, additionalProperties: true} next: {type: object, additionalProperties: true} actor_id: {type: string, format: uuid, nullable: true, description: Null for audited system migrations.} actor_email: {type: string} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string} created_at: {type: string, format: date-time} AdminBonusSettingsResponse: type: object required: [settings, history] properties: settings: {"$ref": "#/components/schemas/AdminBonusSettings"} history: type: array description: The most recent changes, newest first, at most 20. items: {"$ref": "#/components/schemas/AdminBonusSettingsChange"} PutAdminBonusSettingsRequest: type: object additionalProperties: false required: [expected_version, values, reason_code] properties: expected_version: {type: integer, format: int64, minimum: 1} values: {"$ref": "#/components/schemas/BonusRuleValues"} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: type: string minLength: 1 maxLength: 500 description: Required when reason_code is other. AdminReferralReferrer: type: object required: [user_id, email, invited_count, rewarded_count, friends_qualifying_cents, earned_cents, claimed_cents] properties: user_id: {type: string, format: uuid} email: {type: string} display_name: {type: string} referral_code: {type: string, description: Absent when the player never opened their invite link.} invited_count: type: integer format: int64 description: Friends who chose this player's code. rewarded_count: type: integer format: int64 description: Friends whose first wallet load was rewarded. friends_qualifying_cents: type: integer format: int64 description: Sum of the rewarded friends' first wallet loads. earned_cents: type: integer format: int64 description: Inviter freeplay earned from rewarded friends. claimed_cents: type: integer format: int64 description: The part of earned_cents the inviter has claimed. last_invited_at: {type: string, format: date-time} perk_tier_name: {type: string, description: The highest perk tier the referrer has reached.} AdminReferralRefereeStatus: type: string description: awaiting_qualification means the friend chose the code but has no first wallet load yet. not_rewarded means the first load settled without a reward (the inviter was not eligible). enum: [awaiting_qualification, rewarded, not_rewarded] x-enum-varnames: - AdminReferralRefereeStatusAwaitingQualification - AdminReferralRefereeStatusRewarded - AdminReferralRefereeStatusNotRewarded AdminReferralReferee: type: object required: [user_id, email, status, friend_bonus_claimed, inviter_reward_claimed] properties: user_id: {type: string, format: uuid} email: {type: string} display_name: {type: string} selected_at: {type: string, format: date-time, description: When the friend chose the code; absent if the selection row is gone.} status: {"$ref": "#/components/schemas/AdminReferralRefereeStatus"} qualifying_amount_cents: {type: integer, format: int64} qualified_at: {type: string, format: date-time} friend_bonus_cents: {type: integer, format: int64} friend_bonus_claimed: {type: boolean} inviter_reward_cents: {type: integer, format: int64} inviter_reward_claimed: {type: boolean} bonus_settings_version: type: integer format: int64 description: The bonus settings version the amounts were frozen under; absent for outcomes settled before ADR 0023. AdminReferralReferrerListResponse: type: object required: [referrers, pagination] properties: referrers: type: array items: {"$ref": "#/components/schemas/AdminReferralReferrer"} pagination: {"$ref": "#/components/schemas/Pagination"} AdminReferralReferrerDetailResponse: type: object required: [referrer, referees, pagination] properties: referrer: {"$ref": "#/components/schemas/AdminReferralReferrer"} referees: type: array items: {"$ref": "#/components/schemas/AdminReferralReferee"} pagination: {"$ref": "#/components/schemas/Pagination"} BonusPreviewRequest: type: object additionalProperties: false required: [values] properties: values: {"$ref": "#/components/schemas/BonusRuleValues"} BonusPreviewExample: type: object required: [key, label, amount_cents] properties: key: {type: string, description: The rule the example belongs to.} label: {type: string} amount_cents: {type: integer, format: int64} BonusPreviewResponse: type: object required: [examples] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} examples: type: array items: {"$ref": "#/components/schemas/BonusPreviewExample"} BonusSchemeStatus: type: string description: Legacy storage metadata mirrors availability for preceding readers; not an admin lifecycle. enum: [draft, active, archived] x-enum-varnames: [BonusSchemeStatusDraft, BonusSchemeStatusActive, BonusSchemeStatusArchived] BonusScheme: type: object required: [id, name, status, enabled, enabled_action, version, overrides, enrolled_count, created_at, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} id: {type: string, format: uuid} name: {type: string} status: {"$ref": "#/components/schemas/BonusSchemeStatus", deprecated: true} enabled: {type: boolean, description: Sole availability switch. New schemes start false; switching true activates in the same request. Date windows still apply.} enabled_action: {"$ref": "#/components/schemas/InteractionAction"} starts_on: {type: string, format: date, description: First America/New_York day the scheme applies.} ends_on: {type: string, format: date, description: Last America/New_York day the scheme applies.} version: {type: integer, format: int64, minimum: 1} overrides: {"$ref": "#/components/schemas/BonusRuleOverrides"} enrolled_count: {type: integer, format: int64} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} updated_by_email: {type: string} AdminBonusSchemeListResponse: type: object required: [schemes] properties: schemes: type: array items: {"$ref": "#/components/schemas/BonusScheme"} CreateAdminBonusSchemeRequest: type: object additionalProperties: false required: [name, overrides, reason_code] properties: name: {type: string, minLength: 1, maxLength: 80} status: {"$ref": "#/components/schemas/BonusSchemeStatus", deprecated: true} starts_on: {type: string, format: date} ends_on: {type: string, format: date, description: On or after starts_on.} overrides: {"$ref": "#/components/schemas/BonusRuleOverrides"} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string, minLength: 1, maxLength: 500, description: Required when reason_code is other.} SetAdminBonusSchemeEnabledRequest: type: object additionalProperties: false required: [enabled, expected_version] properties: enabled: {type: boolean} expected_version: {type: integer, format: int64, minimum: 1} PutAdminBonusSchemeRequest: type: object additionalProperties: false required: [expected_version, name, overrides, reason_code] properties: expected_version: {type: integer, format: int64, minimum: 1} name: {type: string, minLength: 1, maxLength: 80} status: {"$ref": "#/components/schemas/BonusSchemeStatus", deprecated: true} starts_on: {type: string, format: date} ends_on: {type: string, format: date, description: On or after starts_on.} overrides: {"$ref": "#/components/schemas/BonusRuleOverrides"} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string, minLength: 1, maxLength: 500, description: Required when reason_code is other.} AdminBonusSchemeEnrollmentSource: type: string enum: [admin, perk_tier] x-enum-varnames: [AdminBonusSchemeEnrollmentSourceAdmin, AdminBonusSchemeEnrollmentSourcePerkTier] AdminBonusSchemeEnrollment: type: object required: [id, user_id, email, source, reason_code, enrolled_at] properties: id: {type: string, format: uuid} user_id: {type: string, format: uuid} email: {type: string} source: {"$ref": "#/components/schemas/AdminBonusSchemeEnrollmentSource"} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string} enrolled_at: {type: string, format: date-time} enrolled_by_email: {type: string, description: Absent for automatic perk-tier enrolments.} AdminBonusSchemeEnrollmentListResponse: type: object required: [enrollments, pagination] properties: enrollments: type: array items: {"$ref": "#/components/schemas/AdminBonusSchemeEnrollment"} pagination: {"$ref": "#/components/schemas/Pagination"} EnrollAdminBonusSchemeRequest: type: object additionalProperties: false required: [emails, reason_code] properties: emails: type: array minItems: 1 maxItems: 500 items: {type: string, minLength: 3, maxLength: 320} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string, minLength: 1, maxLength: 500, description: Required when reason_code is other.} AdminBonusSchemeEnrolledPlayer: type: object required: [user_id, email] properties: user_id: {type: string, format: uuid} email: {type: string} AdminBonusSchemeEnrollResponse: type: object required: [enrolled, already_enrolled, unknown] properties: enrolled: type: array items: {"$ref": "#/components/schemas/AdminBonusSchemeEnrolledPlayer"} already_enrolled: type: array items: {type: string} unknown: type: array items: {type: string} RemoveAdminBonusSchemeEnrollmentRequest: type: object additionalProperties: false required: [reason_code] properties: reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string, minLength: 1, maxLength: 500, description: Required when reason_code is other.} AdminReferralPerkTier: type: object required: [id, name, min_rewarded_referrals, scheme_id, scheme_name] properties: id: {type: string, format: uuid} name: {type: string} min_rewarded_referrals: {type: integer, format: int64} scheme_id: {type: string, format: uuid} scheme_name: {type: string} AdminReferralPerkTiersResponse: type: object required: [version, tiers] properties: version: {type: integer, format: int64, minimum: 1} tiers: type: array items: {"$ref": "#/components/schemas/AdminReferralPerkTier"} AdminReferralPerkTierInput: type: object additionalProperties: false required: [name, min_rewarded_referrals, scheme_id] properties: name: {type: string, minLength: 1, maxLength: 80} min_rewarded_referrals: {type: integer, format: int64, minimum: 1, maximum: 10000} scheme_id: {type: string, format: uuid} PutAdminReferralPerkTiersRequest: type: object additionalProperties: false required: [expected_version, tiers, reason_code] properties: expected_version: {type: integer, format: int64, minimum: 1} tiers: type: array maxItems: 10 description: Counts strictly increase; names are unique; the scheme must exist and not be archived. items: {"$ref": "#/components/schemas/AdminReferralPerkTierInput"} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string, minLength: 1, maxLength: 500, description: Required when reason_code is other.} AdminBonusHistoryKind: type: string enum: [settings, scheme, enrollment, perk_tier] x-enum-varnames: [AdminBonusHistoryKindSettings, AdminBonusHistoryKindScheme, AdminBonusHistoryKindEnrollment, AdminBonusHistoryKindPerkTier] AdminBonusHistoryEntry: type: object required: [id, at, kind, summary, reason_code] properties: id: {type: string, format: uuid} at: {type: string, format: date-time} actor_email: {type: string, description: Absent for automatic perk-tier enrolments.} kind: {"$ref": "#/components/schemas/AdminBonusHistoryKind"} summary: {type: string, description: The change in plain words, composed by the server.} reason_code: {"$ref": "#/components/schemas/BonusRuleChangeReason"} note: {type: string} AdminBonusHistoryResponse: type: object required: [entries, pagination] properties: entries: type: array items: {"$ref": "#/components/schemas/AdminBonusHistoryEntry"} pagination: {"$ref": "#/components/schemas/Pagination"} AdminUserBonusScheme: type: object required: [id, name] properties: id: {type: string, format: uuid} name: {type: string} AdminUserBonusRulesResponse: type: object required: [schemes, effective, winners] properties: schemes: type: array items: {"$ref": "#/components/schemas/AdminUserBonusScheme"} effective: {"$ref": "#/components/schemas/BonusRuleValues"} winners: {"$ref": "#/components/schemas/BonusRuleWinners"} UpdatePayoutSettingsRequest: type: object additionalProperties: false required: [expected_version, manual_late_after_minutes, automatic_late_after_minutes, proof_required, reason_code] properties: expected_version: {type: integer, format: int64, minimum: 1} manual_late_after_minutes: {type: integer, format: int64, minimum: 15, maximum: 20160} automatic_late_after_minutes: {type: integer, format: int64, minimum: 5, maximum: 10080} proof_required: {type: boolean} reason_code: {"$ref": "#/components/schemas/PayoutSettingsChangeReason"} note: type: string minLength: 1 maxLength: 500 description: Required when reason_code is other. AdminPaymentWithdrawalOperatorStatus: description: Backend-derived workflow status for the operator inbox. Clients must not infer this from the canonical lifecycle state. type: string enum: - new - waiting_for_approval - approved_send_payment - processing_automatically - needs_attention - paid - closed x-enum-varnames: - AdminPaymentWithdrawalOperatorStatusNew - AdminPaymentWithdrawalOperatorStatusWaitingForApproval - AdminPaymentWithdrawalOperatorStatusApprovedSendPayment - AdminPaymentWithdrawalOperatorStatusProcessingAutomatically - AdminPaymentWithdrawalOperatorStatusNeedsAttention - AdminPaymentWithdrawalOperatorStatusPaid - AdminPaymentWithdrawalOperatorStatusClosed AdminPaymentWithdrawalQueueCounts: description: Unpaginated counts for all queue classifications matching the non-queue list filters. type: object required: - open - paid - closed properties: open: type: integer format: int64 minimum: 0 paid: type: integer format: int64 minimum: 0 closed: type: integer format: int64 minimum: 0 AdminNotificationDeliveryState: description: Delivery state of the latest withdrawal-status email job. Queued includes in-progress retries; failed includes intentionally skipped jobs. type: string enum: - not_requested - queued - sent - failed AdminNotificationDeliverySummary: type: object required: - state properties: state: "$ref": "#/components/schemas/AdminNotificationDeliveryState" updated_at: description: Last update time of the latest withdrawal-status email job; absent when no email was requested. type: string format: date-time nullable: true AdminPaymentWithdrawal: description: Admin projection of a payment withdrawal/cashout with operator triage and payer identity. allOf: - "$ref": "#/components/schemas/PaymentWithdrawal" - type: object required: - provider_code - tier - queue - operator_status - operator_status_label - payout_mode - reviewed - user_email - user_is_system_account - notification_delivery - evidence properties: provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" provider_transaction_id: type: string nullable: true merchant_order_ref: type: string nullable: true tier: "$ref": "#/components/schemas/AdminPaymentWithdrawalTier" queue: "$ref": "#/components/schemas/AdminPaymentWithdrawalQueue" operator_status: "$ref": "#/components/schemas/AdminPaymentWithdrawalOperatorStatus" operator_status_label: description: Stable display label corresponding to operator_status. type: string payout_mode: allOf: [{$ref: '#/components/schemas/PayoutMode'}] nullable: true description: Null when the payout's pinned provider cannot be resolved; neither Approve is offered until it is known. reviewed: description: True after any admin explicitly acknowledges this withdrawal. type: boolean reviewed_by: description: First admin who acknowledged this withdrawal. type: string format: uuid nullable: true reviewed_at: description: Time this withdrawal was first acknowledged. type: string format: date-time nullable: true user_email: type: string format: email user_alias: type: string nullable: true user_is_system_account: description: True when the requester is a provider-health system canary account. type: boolean notification_delivery: "$ref": "#/components/schemas/AdminNotificationDeliverySummary" evidence: type: object additionalProperties: true completed_at: type: string format: date-time nullable: true refund_transaction_id: type: string format: uuid nullable: true AdminPaymentWithdrawalsResponse: type: object required: - payments - pagination - queue_counts properties: payments: type: array items: "$ref": "#/components/schemas/AdminPaymentWithdrawal" pagination: "$ref": "#/components/schemas/Pagination" queue_counts: "$ref": "#/components/schemas/AdminPaymentWithdrawalQueueCounts" AdminPaymentWithdrawalAcknowledgementResponse: type: object required: - payment properties: payment: "$ref": "#/components/schemas/AdminPaymentWithdrawal" AdminPaymentWithdrawalEvent: type: object required: - id - provider_code - event_type - evidence - created_at properties: id: type: string format: uuid payment_withdrawal_intent_id: type: string format: uuid nullable: true provider_code: "$ref": "#/components/schemas/PaymentWithdrawalProviderCode" event_type: type: string provider_transaction_id: type: string nullable: true signature_valid: type: boolean nullable: true content_type: type: string nullable: true evidence: type: object additionalProperties: true actor_id: type: string format: uuid nullable: true source: type: string enum: [player, admin, provider, system, reconciler] x-enum-varnames: - WithdrawalEventSourcePlayer - WithdrawalEventSourceAdmin - WithdrawalEventSourceProvider - WithdrawalEventSourceSystem - WithdrawalEventSourceReconciler prior_state: allOf: - "$ref": "#/components/schemas/PaymentWithdrawalState" nullable: true new_state: allOf: - "$ref": "#/components/schemas/PaymentWithdrawalState" nullable: true reason: type: string nullable: true created_at: type: string format: date-time AdminPaymentWithdrawalDetailResponse: type: object required: - payment - events - proof_assets properties: payment: "$ref": "#/components/schemas/AdminPaymentWithdrawal" events: type: array items: "$ref": "#/components/schemas/AdminPaymentWithdrawalEvent" proof_assets: type: array items: "$ref": "#/components/schemas/AdminWithdrawalProofAsset" AdminWithdrawalProofAssetState: type: string enum: [pending, finalized] AdminWithdrawalProofAsset: type: object required: [id, payment_withdrawal_intent_id, uploader_id, state, original_filename, declared_mime, declared_size, checksum_sha256, upload_expires_at, created_at] properties: id: {type: string, format: uuid} payment_withdrawal_intent_id: {type: string, format: uuid} uploader_id: {type: string, format: uuid} state: {"$ref": "#/components/schemas/AdminWithdrawalProofAssetState"} original_filename: {type: string} declared_mime: {type: string} detected_mime: {type: string, nullable: true} declared_size: {type: integer, format: int64} actual_size: {type: integer, format: int64, nullable: true} checksum_sha256: {type: string, pattern: '^[0-9a-f]{64}$'} etag: {type: string, nullable: true} version_id: {type: string, nullable: true} upload_expires_at: {type: string, format: date-time} finalized_at: {type: string, format: date-time, nullable: true} created_at: {type: string, format: date-time} AdminInitiateWithdrawalProofUploadRequest: type: object additionalProperties: false required: [original_filename, content_type, size_bytes, checksum_sha256] properties: original_filename: {type: string, minLength: 1, maxLength: 255} content_type: type: string enum: [image/jpeg, image/png, application/pdf] size_bytes: {type: integer, format: int64, minimum: 1} checksum_sha256: {type: string, pattern: '^[0-9a-fA-F]{64}$'} AdminWithdrawalProofUploadResponse: type: object required: [proof, upload_url, headers] properties: proof: {"$ref": "#/components/schemas/AdminWithdrawalProofAsset"} upload_url: {type: string, format: uri} headers: type: object additionalProperties: {type: string} AdminWithdrawalProofAssetResponse: type: object required: [proof] properties: proof: {"$ref": "#/components/schemas/AdminWithdrawalProofAsset"} AdminWithdrawalProofPreviewResponse: type: object required: [url, expires_at] properties: url: {type: string, format: uri} expires_at: {type: string, format: date-time} AdminDepositProofAsset: type: object required: [id, payment_intent_id, uploader_id, state, original_filename, declared_mime, declared_size, checksum_sha256, upload_expires_at, created_at] properties: id: {type: string, format: uuid} payment_intent_id: {type: string, format: uuid} uploader_id: {type: string, format: uuid} state: {"$ref": "#/components/schemas/AdminWithdrawalProofAssetState"} original_filename: {type: string} declared_mime: {type: string} detected_mime: {type: string, nullable: true} declared_size: {type: integer, format: int64} actual_size: {type: integer, format: int64, nullable: true} checksum_sha256: {type: string, pattern: '^[0-9a-f]{64}$'} etag: {type: string, nullable: true} version_id: {type: string, nullable: true} upload_expires_at: {type: string, format: date-time} finalized_at: {type: string, format: date-time, nullable: true} created_at: {type: string, format: date-time} AdminDepositProofUploadResponse: type: object required: [proof, upload_url, headers, replayed] properties: proof: {"$ref": "#/components/schemas/AdminDepositProofAsset"} upload_url: {type: string, format: uri} headers: type: object additionalProperties: {type: string} replayed: {type: boolean} AdminDepositProofAssetResponse: type: object required: [proof, replayed] properties: proof: {"$ref": "#/components/schemas/AdminDepositProofAsset"} replayed: {type: boolean} ManualPayoutConflictReason: type: string description: review_required means the player has open risk signals, so the Approve must say why (approval_reason_code); duplicate_reference means the payment reference already settled another payout; state_changed means the payout changed since it was loaded. enum: [review_required, duplicate_reference, state_changed] x-enum-varnames: - ManualPayoutConflictReasonReviewRequired - ManualPayoutConflictReasonDuplicateReference - ManualPayoutConflictReasonStateChanged AdminMarkPaidConflictResponse: type: object required: [error, reason] properties: error: "$ref": "#/components/schemas/APIError" reason: "$ref": "#/components/schemas/ManualPayoutConflictReason" conflicting_cashout: "$ref": "#/components/schemas/AdminManualPayoutReferenceConflict" AdminManualPayoutReferenceConflict: type: object description: Admin-only summary of the cash-out holding this provider's reference. Never returned on player endpoints. required: [cashout_id, player_label, amount_cents, cashout_created_at] properties: cashout_id: {type: string, format: uuid} player_label: {type: string} amount_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} cashout_created_at: {type: string, format: date-time} AdminManualPayoutFeeDetails: type: object description: Authoritative whole-cent amounts for the refused fee. fee_limit_cents is the exclusive limit after any recorded staff tip, computed by Postgres. required: [fee_cents, amount_cents, fee_limit_cents] properties: fee_cents: {type: integer, format: int64, minimum: -9007199254740991, maximum: 9007199254740991} amount_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991} fee_limit_cents: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991} AdminMarkPaidValidationResponse: type: object required: [error] properties: error: {"$ref": "#/components/schemas/APIError"} reason: {type: string, enum: [fee_invalid]} fee_details: {"$ref": "#/components/schemas/AdminManualPayoutFeeDetails"} ManualPayoutPaidReason: type: string enum: [paid_as_requested, other] x-enum-varnames: - ManualPayoutPaidReasonPaidAsRequested - ManualPayoutPaidReasonOther ManualPayoutPaidVia: type: string enum: [cash_app, chime, paypal, other] AdminManualPayoutPreview: type: object required: [amount_cents, fee_cents, fee_limit_cents, tip_cents, net_cents, valid] properties: amount_cents: {type: integer, format: int64} fee_cents: {type: integer, format: int64} fee_limit_cents: {type: integer, format: int64} tip_cents: {type: integer, format: int64} net_cents: {type: integer, format: int64} valid: {type: boolean} WithdrawalPayingClaimRequest: type: object additionalProperties: false required: [claim_id] properties: claim_id: {type: string, format: uuid} review_evidence: {type: string, maxLength: 500} WithdrawalPayingClaimStatus: type: object additionalProperties: false required: [state, held, owned, needs_review] properties: state: {"$ref": "#/components/schemas/PaymentWithdrawalState"} claim_id: {type: string, format: uuid} held: {type: boolean} owned: {type: boolean} needs_review: {type: boolean} send_valid_for_ms: {type: integer, format: int64, minimum: 0, description: Maximum remaining time to show send instructions for an owned claim. Count from the start of this request.} paying_by: {type: string, format: uuid, description: Original staff user when a claim needs review.} paying_at: {type: string, format: date-time, description: When the original payer opened the claim.} AdminMarkPaymentWithdrawalPaidRequest: type: object description: Approves a cash-out an admin sent by hand and records it paid. Only manual payouts qualify. expected_state awaiting_approval approves and records it paid in one step; provider_created finishes a payout approved before the 2026-11-16 amendment. approval_reason_code is required while the player has open risk signals. The fee defaults to zero and the net is computed by the server. paid_via and tag default to the tag name and payment tag the player gave with the request. proof_asset_id is required only when the site's payout settings require a settlement proof. required: - expected_state - player_paid_confirmed additionalProperties: false properties: paying_claim_id: {type: string, format: uuid, description: Required for a new hand-paid approval.} claim_review_evidence: {type: string, maxLength: 500, description: Verified payment evidence required for a claim under review.} player_paid_confirmed: type: boolean description: The admin's answer to "Did you pay the player already?". Only true is accepted; false is refused with 400. approval_reason_code: "$ref": "#/components/schemas/AdminWithdrawalApprovalReason" approval_note: type: string minLength: 1 maxLength: 400 description: Optional approval detail; required with approval_reason_code other. paid_via: {"$ref": "#/components/schemas/ManualPayoutPaidVia"} expected_state: "$ref": "#/components/schemas/PaymentWithdrawalState" reference: type: string nullable: true maxLength: 200 description: Optional unique transaction ID for this payment. Omitted, null or blank records no reference. tag: type: string minLength: 1 maxLength: 200 description: The payment tag the money was sent to. Omitted uses the player's own tag from the request. proof_asset_id: type: string format: uuid description: The finalized receipt screenshot. Required only when the payout settings require a settlement proof. fee_cents: type: integer format: int64 minimum: 0 description: Fee actually charged; omit for zero. reason_code: "$ref": "#/components/schemas/ManualPayoutPaidReason" note: type: string minLength: 1 maxLength: 500 description: Required when reason_code is other. AdminDepositRoutingRule: type: object required: [method_kind, provider_code, enabled, configured, min_amount_cents, max_amount_cents] properties: method_kind: {"$ref": "#/components/schemas/DepositMethodKind"} provider_code: {"$ref": "#/components/schemas/PaymentDepositProviderCode"} enabled: {type: boolean} configured: {type: boolean, readOnly: true, description: Runtime gateway configuration; never persisted.} min_amount_cents: {type: integer, format: int64, minimum: 0} max_amount_cents: {type: integer, format: int64, minimum: 0, nullable: true} UpdateAdminDepositRoutingRule: type: object additionalProperties: false required: [method_kind, provider_code, enabled, min_amount_cents, max_amount_cents] properties: method_kind: {"$ref": "#/components/schemas/DepositMethodKind"} provider_code: {"$ref": "#/components/schemas/PaymentDepositProviderCode"} enabled: {type: boolean} min_amount_cents: {type: integer, format: int64, minimum: 0} max_amount_cents: {type: integer, format: int64, minimum: 0, nullable: true} AdminDepositProviderAvailability: type: object required: [provider_code, configured] properties: provider_code: {"$ref": "#/components/schemas/PaymentDepositProviderCode"} configured: {type: boolean, description: Runtime deposit gateway configuration; false does not invalidate a routing rule.} AdminDepositMethodProviders: type: object required: [method_kind, providers] properties: method_kind: {"$ref": "#/components/schemas/DepositMethodKind"} providers: type: array description: Site-registered providers whose adapters statically support this method. Empty when none support it; absent site providers are never advertised. items: {"$ref": "#/components/schemas/AdminDepositProviderAvailability"} AdminPaymentSettingsChange: type: object required: [id, created_at, actor_label, kind, reason] properties: id: {type: string, format: uuid} created_at: {type: string, format: date-time} actor_label: {type: string} kind: type: string enum: [payment_settings, provider_routing, manual_settings] x-enum-varnames: [PaymentSettingsChangeCombined, PaymentSettingsChangeRouting, PaymentSettingsChangeManual] reason: {type: string} DepositProviderOutcomes: type: object required: [provider_code, window_minutes, succeeded, failed, pending, unresolved, success_rate_bps] description: Deposit intents created within the last hour. Success rate considers confirmed succeeded and failed only; unresolved outcomes remain unknown. This observation does not change routing. properties: provider_code: {$ref: '#/components/schemas/PaymentDepositProviderCode'} window_minutes: {type: integer, format: int64, minimum: 1} succeeded: {type: integer, format: int64, minimum: 0} failed: {type: integer, format: int64, minimum: 0} pending: {type: integer, format: int64, minimum: 0} unresolved: {type: integer, format: int64, minimum: 0} success_rate_bps: {type: integer, format: int64, minimum: 0, maximum: 10000, nullable: true, description: Null when there are no confirmed outcomes.} AdminDepositPolicy: type: object required: [rules, method_providers, version, effects] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} provider_outcomes: {type: array, readOnly: true, items: {$ref: "#/components/schemas/DepositProviderOutcomes"}} manual_policy: {"$ref": "#/components/schemas/ManualPaymentClaimPolicy"} history: type: array maxItems: 30 items: {"$ref": "#/components/schemas/AdminPaymentSettingsChange"} method_providers: type: array description: One entry per method kind, including empty provider lists. Site registration and static adapter capabilities determine choices; runtime configured flags are never persisted. items: {"$ref": "#/components/schemas/AdminDepositMethodProviders"} rules: type: array description: Ordered by priority within each payment method kind. items: {"$ref": "#/components/schemas/AdminDepositRoutingRule"} effects: type: array items: {"$ref": "#/components/schemas/ResourceEffect"} version: {type: integer, format: int64, minimum: 0} PaymentProviderPolicyChangeReason: type: string description: Why an operator changed a payment provider policy (deposit routing or automatic payouts). enum: [provider_outage, provider_restored, operating_policy, correction, other] x-enum-varnames: - PaymentProviderPolicyChangeReasonProviderOutage - PaymentProviderPolicyChangeReasonProviderRestored - PaymentProviderPolicyChangeReasonOperatingPolicy - PaymentProviderPolicyChangeReasonCorrection - PaymentProviderPolicyChangeReasonOther UpdateAdminDepositPolicyRequest: type: object additionalProperties: false required: [rules, expected_version, reason_code] properties: manual_policy: "$ref": "#/components/schemas/ManualPaymentClaimPolicyInput" description: Optional house settings. Routing and house policies compare both versions and commit together with one before/after audit. Player payment behavior is unchanged. rules: type: array description: Replaces the ordered routing rule list; array order defines priority within a method kind. Provider adapters must statically support the rule's method, independent of site registration or runtime configuration. Unconfigured supported providers can keep disabled rules, and rules that were already enabled, and are skipped at runtime; turning a rule on for a provider with no live integration on this site fails on rules[index].enabled. Duplicate (method_kind, provider_code) pairs are rejected even across amount bands; errors identify the rules[index] field. items: {"$ref": "#/components/schemas/UpdateAdminDepositRoutingRule"} expected_version: {type: integer, format: int64, minimum: 0} reason_code: "$ref": "#/components/schemas/PaymentProviderPolicyChangeReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. AdminNowPaymentsPayoutPolicy: type: object additionalProperties: false required: [automatic_enabled, auto_approval_enabled, payout_configured, manual_fallback] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} automatic_enabled: {type: boolean} auto_approval_enabled: {type: boolean} payout_configured: {type: boolean} manual_fallback: {type: boolean} updated_by: {type: string, format: uuid} updated_at: {type: string, format: date-time} AdminNowPaymentsPayoutPolicyUpdate: type: object additionalProperties: false required: [expected_enabled, automatic_enabled, reason_code] properties: expected_enabled: {type: boolean} automatic_enabled: {type: boolean} expected_auto_approval_enabled: {type: boolean} auto_approval_enabled: {type: boolean} reason_code: "$ref": "#/components/schemas/PaymentProviderPolicyChangeReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. AdminExternalNotificationEventType: type: string enum: - withdrawal_requested - linked_cashout_review_requested - withdrawal_needs_attention - linked_cashout_review_problem - provider_transfer_problem - provider_balance_low - provider_outage - provider_recovered - provider_capability_changed - support_message_received - deposit_problem - deposit_requested - deposit_credited - staff_approval - money_route_failure AdminExternalNotificationGroup: type: string enum: [cash_outs, providers, support, payments] AdminExternalNotificationPreset: type: string enum: [important, maintenance, chat, all, custom] AdminExternalNotificationSchedule: type: string enum: [immediate, hourly, daily, weekly] AdminExternalNotificationDeliveryStatus: type: string description: sent means the email provider accepted the message; skipped (for example email delivery disabled) and failed are never reported as sent. enum: [queued, sending, retrying, sent, skipped, failed, cancelled] AdminExternalNotificationDeliveryKind: type: string enum: [notification, test] AdminExternalNotificationEventDefinition: type: object additionalProperties: false required: [type, group, title, description, presets] properties: type: {"$ref": "#/components/schemas/AdminExternalNotificationEventType"} group: {"$ref": "#/components/schemas/AdminExternalNotificationGroup"} title: {type: string} description: {type: string} presets: type: array description: named presets that include this event; All includes every event items: {"$ref": "#/components/schemas/AdminExternalNotificationPreset"} AdminExternalNotificationEmailDelivery: type: object additionalProperties: false required: [enabled, provider, supported] properties: enabled: {type: boolean} provider: {type: string} supported: {type: boolean} AdminExternalNotificationLastDelivery: type: object additionalProperties: false required: [status, created_at] properties: status: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveryStatus"} reason: {type: string} error: {type: string} created_at: {type: string, format: date-time} AdminTelegramBotHealth: type: object additionalProperties: false required: [bot_username, bot_name] properties: bot_username: {type: string} bot_name: {type: string} AdminTelegramBotInput: type: object additionalProperties: false required: [token] properties: token: {type: string, minLength: 20, maxLength: 128, description: The BotFather token. Write-only.} AdminTelegramUsernameInput: type: object additionalProperties: false required: [telegram_username] properties: telegram_username: {type: string, nullable: true, maxLength: 33, description: Telegram username without @ (5-32 letters, digits, underscores); null or empty clears it.} AdminTelegramLinkStatus: type: string enum: [none, waiting_for_start, linked] x-enum-varnames: [AdminTelegramLinkStatusNone, AdminTelegramLinkStatusWaitingForStart, AdminTelegramLinkStatusLinked] AdminTelegramLastMessage: type: object additionalProperties: false required: [kind, status, created_at] properties: kind: {type: string, enum: [notification, test, link]} status: {type: string, enum: [queued, sending, sent, failed, skipped]} error: {type: string} created_at: {type: string, format: date-time} AdminTelegramRecipient: type: object additionalProperties: false required: [recipient_id, email, status] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} recipient_id: {type: string, format: uuid} email: {type: string} telegram_username: {type: string, nullable: true} status: {"$ref": "#/components/schemas/AdminTelegramLinkStatus"} linked_at: {type: string, format: date-time, nullable: true} last_message: {"$ref": "#/components/schemas/AdminTelegramLastMessage"} AdminTelegramOverview: type: object additionalProperties: false required: [configured, recipients] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} configured: {type: boolean} bot_name: {type: string, nullable: true, description: The bot's display name from Telegram.} bot_username: {type: string, nullable: true, description: Without @; the admin opens t.me/ and presses Start.} token_hint: {type: string, nullable: true, description: Masked token, bot id and last four characters only.} updated_at: {type: string, format: date-time, nullable: true} recipients: type: array items: {"$ref": "#/components/schemas/AdminTelegramRecipient"} AdminExternalNotificationRecipient: type: object additionalProperties: false required: [id, email, preset, event_types, schedule, timezone, send_time, send_weekday, enabled, version, created_at, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} id: {type: string, format: uuid} email: {type: string} preset: {"$ref": "#/components/schemas/AdminExternalNotificationPreset"} event_types: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationEventType"} schedule: {"$ref": "#/components/schemas/AdminExternalNotificationSchedule"} timezone: {type: string, description: IANA timezone name} send_time: {type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$', description: local HH:MM for daily and weekly schedules} send_weekday: {type: integer, minimum: 0, maximum: 6, description: 0 = Sunday for weekly schedules} enabled: {type: boolean} version: {type: integer} next_send_at: {type: string, format: date-time} last_sent_at: {type: string, format: date-time} last_delivery: {"$ref": "#/components/schemas/AdminExternalNotificationLastDelivery"} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} AdminPayoutNotifications: type: object additionalProperties: false required: [enabled, items] properties: enabled: {type: boolean} items: type: array maxItems: 50 items: {"$ref": "#/components/schemas/AdminPayoutNotification"} AdminPayoutNotification: type: object additionalProperties: false required: [id, withdrawal_id, player_id, player_label, kind, amount_cents, method, occurred_at] properties: id: {type: string, format: uuid} withdrawal_id: {type: string, format: uuid} player_id: {type: string, format: uuid} player_label: {type: string} player_alias: {type: string, nullable: true} kind: {type: string, enum: [requested, approved, paid, rejected, canceled, expired, needs_attention]} amount_cents: {type: integer, format: int64, minimum: 1} method: {type: string} occurred_at: {type: string, format: date-time} AdminNotificationBundlePolicy: type: object additionalProperties: false required: [version, player_payout_messages, payout_feed, telegram_deposits, telegram_support_text] properties: version: {type: integer, format: int64, minimum: 1} player_payout_messages: {type: boolean, description: Post-approval system messages in the player's Support conversation.} payout_feed: {type: boolean, description: Show the staff Payouts notification feed.} telegram_deposits: {type: boolean, description: Ordinary deposit alerts for eligible configured recipients.} telegram_support_text: {type: boolean, description: Scrubbed 140-character support preview only in linked private Telegram chats mapped to active staff.} AdminNotificationBundlePolicyReplace: type: object additionalProperties: false required: [expected_version, player_payout_messages, payout_feed, telegram_deposits, telegram_support_text, reason] properties: expected_version: {type: integer, format: int64, minimum: 1} player_payout_messages: {type: boolean} payout_feed: {type: boolean} telegram_deposits: {type: boolean} telegram_support_text: {type: boolean} reason: {type: string, minLength: 3, maxLength: 500} AdminExternalNotificationsResponse: type: object additionalProperties: false required: [email_delivery, default_timezone, events, recipients] properties: email_delivery: {"$ref": "#/components/schemas/AdminExternalNotificationEmailDelivery"} default_timezone: {type: string} events: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationEventDefinition"} recipients: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationRecipient"} AdminExternalNotificationRecipientCreate: type: object additionalProperties: false required: [email, preset, schedule] properties: email: {type: string, maxLength: 254} preset: {"$ref": "#/components/schemas/AdminExternalNotificationPreset"} event_types: type: array description: read only when preset is custom items: {"$ref": "#/components/schemas/AdminExternalNotificationEventType"} schedule: {"$ref": "#/components/schemas/AdminExternalNotificationSchedule"} timezone: {type: string, description: IANA timezone name; defaults to America/Chicago} send_time: {type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$'} send_weekday: {type: integer, minimum: 0, maximum: 6} enabled: {type: boolean} AdminExternalNotificationRecipientUpdate: type: object additionalProperties: false required: [expected_version] properties: expected_version: {type: integer, minimum: 1} email: {type: string, maxLength: 254} preset: {"$ref": "#/components/schemas/AdminExternalNotificationPreset"} event_types: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationEventType"} schedule: {"$ref": "#/components/schemas/AdminExternalNotificationSchedule"} timezone: {type: string} send_time: {type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$'} send_weekday: {type: integer, minimum: 0, maximum: 6} enabled: {type: boolean} AdminExternalNotificationDelivery: type: object additionalProperties: false required: [id, recipient_id, email, kind, schedule, event_count, status, attempts, max_attempts, created_at] properties: id: {type: string, format: uuid} recipient_id: {type: string, format: uuid} email: {type: string} kind: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveryKind"} schedule: {"$ref": "#/components/schemas/AdminExternalNotificationSchedule"} event_count: {type: integer} status: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveryStatus"} reason: {type: string} error: {type: string} attempts: {type: integer} max_attempts: {type: integer} created_at: {type: string, format: date-time} sent_at: {type: string, format: date-time} next_try_at: {type: string, format: date-time} AdminExternalNotificationDeliveriesResponse: type: object additionalProperties: false required: [deliveries] properties: deliveries: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationDelivery"} AdminExternalNotificationDeliveryEvent: type: object additionalProperties: false required: [id, event_type, occurred_at, summary] properties: id: {type: string, format: uuid} event_type: {"$ref": "#/components/schemas/AdminExternalNotificationEventType"} occurred_at: {type: string, format: date-time} summary: {type: string} AdminExternalNotificationDeliveryDetail: type: object additionalProperties: false required: [delivery, events, has_more] properties: delivery: {"$ref": "#/components/schemas/AdminExternalNotificationDelivery"} events: type: array items: {"$ref": "#/components/schemas/AdminExternalNotificationDeliveryEvent"} has_more: {type: boolean} AdminWithdrawalApprovalReason: type: string description: Why an admin approved a withdrawal. enum: [checks_passed, known_player, verified_identity, other] x-enum-varnames: - AdminWithdrawalApprovalReasonChecksPassed - AdminWithdrawalApprovalReasonKnownPlayer - AdminWithdrawalApprovalReasonVerifiedIdentity - AdminWithdrawalApprovalReasonOther AdminApprovePaymentWithdrawalRequest: type: object additionalProperties: false required: [reason_code] properties: reason_code: "$ref": "#/components/schemas/AdminWithdrawalApprovalReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other. AdminWithdrawalRejectionReason: type: string description: Private reason an admin rejected a withdrawal; the player sees only the rejection category. enum: [cheating, cleared_wallet, suspected_fraud, promotion_abuse, unverified_identity, destination_problem, duplicate_request, player_request, provider_unavailable, test_cleanup, other] x-enum-varnames: - AdminWithdrawalRejectionReasonCheating - AdminWithdrawalRejectionReasonClearedWallet - AdminWithdrawalRejectionReasonSuspectedFraud - AdminWithdrawalRejectionReasonPromotionAbuse - AdminWithdrawalRejectionReasonUnverifiedIdentity - AdminWithdrawalRejectionReasonDestinationProblem - AdminWithdrawalRejectionReasonDuplicateRequest - AdminWithdrawalRejectionReasonPlayerRequest - AdminWithdrawalRejectionReasonProviderUnavailable - AdminWithdrawalRejectionReasonTestCleanup - AdminWithdrawalRejectionReasonOther AdminRejectPaymentWithdrawalRequest: type: object additionalProperties: false required: [category, reason_code] properties: category: allOf: - "$ref": "#/components/schemas/PaymentWithdrawalRejectionCategory" nullable: false reason_code: "$ref": "#/components/schemas/AdminWithdrawalRejectionReason" note: type: string minLength: 1 maxLength: 400 description: Optional private detail, never shown to the player. Required (at least 3 characters) when reason_code is other. AdminWithdrawalConfirmFailedReason: type: string description: Why an admin confirmed that a reconciling payout failed. enum: [provider_confirmed_failed, player_cancelled_at_provider, destination_rejected, other] x-enum-varnames: - AdminWithdrawalConfirmFailedReasonProviderConfirmedFailed - AdminWithdrawalConfirmFailedReasonPlayerCancelledAtProvider - AdminWithdrawalConfirmFailedReasonDestinationRejected - AdminWithdrawalConfirmFailedReasonOther AdminConfirmPaymentWithdrawalFailedRequest: type: object additionalProperties: false required: [expected_state, reason_code, evidence] properties: expected_state: "$ref": "#/components/schemas/PaymentWithdrawalState" reason_code: "$ref": "#/components/schemas/AdminWithdrawalConfirmFailedReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other. evidence: type: object additionalProperties: true minProperties: 1 AdminPaymentWithdrawalCommandResponse: type: object required: - payment properties: payment: "$ref": "#/components/schemas/AdminPaymentWithdrawal" AdminLedgerAccount: type: object required: - id - owner_type - account_type - currency_code - balance_cents - created_at properties: id: type: string format: uuid owner_type: type: string enum: - user - system owner_id: type: string format: uuid nullable: true account_type: {$ref: '#/components/schemas/LedgerAccountType'} currency_code: "$ref": "#/components/schemas/CurrencyCode" balance_cents: description: Admin API presentation value normalized from DB-owned numeric(22,4) ledger balance. type: integer format: int64 created_at: type: string format: date-time AdminLedgerAccountsResponse: type: object required: - accounts - pagination properties: accounts: type: array items: "$ref": "#/components/schemas/AdminLedgerAccount" pagination: "$ref": "#/components/schemas/Pagination" AdminLedgerTransaction: type: object required: - id - actor_id - kind - currency_code - metadata - created_at properties: id: type: string format: uuid actor_id: type: string format: uuid kind: "$ref": "#/components/schemas/AdminLedgerTransactionKind" currency_code: "$ref": "#/components/schemas/CurrencyCode" metadata: type: object additionalProperties: true created_at: type: string format: date-time AdminLedgerTransactionsResponse: type: object required: - transactions - pagination properties: transactions: type: array items: "$ref": "#/components/schemas/AdminLedgerTransaction" pagination: "$ref": "#/components/schemas/Pagination" ProductAnalyticsEvent: type: object required: - id - occurred_at - event_name - properties properties: id: type: string format: uuid occurred_at: type: string format: date-time event_name: type: string distinct_user_hash: type: string nullable: true description: Optional HMAC-SHA256 pseudonymous user key when analytics.secret is configured. properties: type: object additionalProperties: true ProductAnalyticsEventsResponse: type: object required: - events - pagination properties: events: type: array items: "$ref": "#/components/schemas/ProductAnalyticsEvent" pagination: "$ref": "#/components/schemas/Pagination" ProductAnalyticsWindow: type: object properties: occurred_from: type: string format: date-time nullable: true occurred_to: type: string format: date-time nullable: true ProductAnalyticsMetric: type: object required: - event_name - event_count properties: event_name: type: string event_count: type: integer format: int64 minimum: 0 unique_user_count: type: integer format: int64 minimum: 0 nullable: true ProductAnalyticsFunnelStep: type: object required: - key - label - event_name - event_count properties: key: type: string enum: - registered - logged_in - game_launched - deposit_created - provider_transfer_created label: type: string event_name: type: string event_count: type: integer format: int64 minimum: 0 unique_user_count: type: integer format: int64 minimum: 0 nullable: true ProductAnalyticsBreakdownRow: type: object required: - value - event_count properties: value: type: string event_count: type: integer format: int64 minimum: 0 unique_user_count: type: integer format: int64 minimum: 0 nullable: true ProductAnalyticsBreakdown: type: object required: - key - label - rows properties: key: type: string enum: - game_launches_by_provider - game_launches_by_fallback - deposits_by_provider - deposits_by_state - deposits_by_amount_bucket - transfers_by_provider - transfers_by_state - transfers_by_direction label: type: string rows: type: array items: "$ref": "#/components/schemas/ProductAnalyticsBreakdownRow" ProductAnalyticsOverviewResponse: type: object required: - generated_at - window - totals - funnel - breakdowns properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/ProductAnalyticsWindow" totals: type: array items: "$ref": "#/components/schemas/ProductAnalyticsMetric" funnel: type: array items: "$ref": "#/components/schemas/ProductAnalyticsFunnelStep" breakdowns: type: array items: "$ref": "#/components/schemas/ProductAnalyticsBreakdown" AdminOpsEvent: type: object required: - id - occurred_at - severity - kind - label - resource properties: id: type: string occurred_at: type: string format: date-time severity: type: string enum: - info - warning - critical kind: type: string description: Emits provider transfer, payment, and immutable wallet-adjustment operational events. enum: - provider_transfer - payment_deposit - payment_webhook - wallet_adjustment - provider_capability - system label: type: string resource: type: object required: - kind properties: kind: type: string description: Operational event target resource. enum: - provider-transfers - reconciliation - payments - users - providers - system id: type: string nullable: true label: type: string nullable: true state: type: string nullable: true evidence_summary: type: string nullable: true AdminOpsEventsResponse: type: object required: - events - pagination properties: events: type: array items: "$ref": "#/components/schemas/AdminOpsEvent" pagination: "$ref": "#/components/schemas/Pagination" VerifyWhatHappenedCode: type: string enum: [game_load_unconfirmed, game_cashout_unconfirmed, deposit_unconfirmed, withdrawal_unconfirmed] x-enum-varnames: - VerifyWhatHappenedGameLoadUnconfirmed - VerifyWhatHappenedGameCashoutUnconfirmed - VerifyWhatHappenedDepositUnconfirmed - VerifyWhatHappenedWithdrawalUnconfirmed VerifyProcedurePlayer: type: object required: [id, display_name, email] properties: id: {type: string, format: uuid} display_name: {type: string} email: {type: string} VerifyCompareAmount: type: string description: Which amount to look for on the panel record. amount is amount_cents; provider_net is payout.provider_net_cents, what the payment provider was asked to send after fees. enum: [amount, provider_net] x-enum-varnames: [VerifyCompareAmountCase, VerifyCompareAmountProviderNet] VerifyPayoutNetSource: type: string description: actual_settlement is the net the provider settled; approved_quote is the approved quote's net, which dispatch sends unless a live quote moved it within the allowed slippage. enum: [actual_settlement, approved_quote] x-enum-varnames: [VerifyPayoutNetSourceActualSettlement, VerifyPayoutNetSourceApprovedQuote] VerifyPayout: type: object description: A withdrawal's money as the payment provider handles it, in USD cents. required: [gross_cents, fee_cents, provider_net_cents, net_source] properties: gross_cents: {type: integer, format: int64} fee_cents: {type: integer, format: int64} provider_net_cents: {type: integer, format: int64} net_source: {"$ref": "#/components/schemas/VerifyPayoutNetSource"} VerifyWhatHappened: type: object required: [code, amount_cents, compare_amount, provider_code, player, at] properties: code: {"$ref": "#/components/schemas/VerifyWhatHappenedCode"} amount_cents: type: integer format: int64 description: The case amount in USD cents; for a withdrawal, the gross reserved. compare_amount: {"$ref": "#/components/schemas/VerifyCompareAmount"} payout: {"$ref": "#/components/schemas/VerifyPayout"} provider_credits: type: integer format: int64 description: The transfer's provider credits, for game cases, when they are whole credits; omitted otherwise (never rounded). provider_code: {type: string} player: {"$ref": "#/components/schemas/VerifyProcedurePlayer"} at: type: string format: date-time description: When the transfer or payment was requested. VerifyProcedureIdLabel: type: string description: Which identifier this is. Game cases list exactly the provider's transfer lookup keys; payment cases list the provider's order and transaction references when stored. enum: [external_order_id, player_account_ref, player_username, merchant_order_ref, provider_transaction_id] x-enum-varnames: - VerifyProcedureIdExternalOrderID - VerifyProcedureIdPlayerAccountRef - VerifyProcedureIdPlayerUsername - VerifyProcedureIdMerchantOrderRef - VerifyProcedureIdProviderTransactionID VerifyProcedureId: type: object required: [label, value, copyable] properties: label: {"$ref": "#/components/schemas/VerifyProcedureIdLabel"} value: {type: string} copyable: {type: boolean} VerifyProcedureStep: type: string enum: [open_provider_panel, search_by_ids, compare_match_fields, record_outcome] x-enum-varnames: - VerifyProcedureStepOpenProviderPanel - VerifyProcedureStepSearchByIDs - VerifyProcedureStepCompareMatchFields - VerifyProcedureStepRecordOutcome VerifyOutcomeCode: type: string enum: [arrived, never_arrived, credits_taken, still_in_game, paid, paid_another_way, not_paid, cant_tell_yet] x-enum-varnames: - VerifyOutcomeArrived - VerifyOutcomeNeverArrived - VerifyOutcomeCreditsTaken - VerifyOutcomeStillInGame - VerifyOutcomePaid - VerifyOutcomePaidAnotherWay - VerifyOutcomeNotPaid - VerifyOutcomeCantTellYet VerifyOutcomeEffect: type: string description: resolve_applied and resolve_not_applied resolve the financial case with the provider reference as evidence_reference; note_and_wait records a note and leaves the case open; convert_to_off_app converts an unconfirmed provider deposit into an off-app deposit. enum: [resolve_applied, resolve_not_applied, note_and_wait, convert_to_off_app] x-enum-varnames: - VerifyOutcomeEffectResolveApplied - VerifyOutcomeEffectResolveNotApplied - VerifyOutcomeEffectNoteAndWait - VerifyOutcomeEffectConvertToOffApp VerifyOutcomeDisabledReason: type: string description: super_admin_required means only a super admin may submit it; action_unavailable means the case does not accept this action in its current state (the case detail's action says why). enum: [super_admin_required, action_unavailable] x-enum-varnames: [VerifyOutcomeDisabledSuperAdminRequired, VerifyOutcomeDisabledActionUnavailable] VerifyProcedureOutcome: type: object required: [code, effect, enabled, requires_reference, super_admin_only] properties: code: {"$ref": "#/components/schemas/VerifyOutcomeCode"} effect: {"$ref": "#/components/schemas/VerifyOutcomeEffect"} enabled: type: boolean description: Whether the viewer can submit it now, from the case's own actions and the viewer's role. disabled_reason: {"$ref": "#/components/schemas/VerifyOutcomeDisabledReason"} action: description: The existing financial-case action the outcome submits through preview and resolve, with the provider reference as evidence_reference when requires_reference is true. Absent for convert_to_off_app, which is its own command. allOf: [{"$ref": "#/components/schemas/AdminFinancialCaseActionCode"}] reason_code: description: The reason code the action is submitted with, when the outcome fixes one. cant_tell_yet is a note with awaiting_provider, so the case stays open and nothing moves. allOf: [{"$ref": "#/components/schemas/AdminFinancialCaseReason"}] requires_reference: type: boolean description: The provider's reference is required; it becomes the evidence_reference. super_admin_only: {type: boolean} VerifyProcedure: type: object required: [case_kind, case_id, what_happened, ids, steps, match_fields, outcomes] properties: provider_status_recheck: description: Explicit status lookup action for an unresolved deposit, including after automatic polling ends. Absent for other cases. allOf: [{"$ref": "#/components/schemas/InteractionAction"}] case_kind: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} case_id: {type: string, format: uuid} what_happened: {"$ref": "#/components/schemas/VerifyWhatHappened"} panel_url: description: The provider's operator back-office, when configured. type: string format: uri nullable: true ids: type: array items: {"$ref": "#/components/schemas/VerifyProcedureId"} steps: type: array items: {"$ref": "#/components/schemas/VerifyProcedureStep"} match_fields: type: array items: {"$ref": "#/components/schemas/ProviderTransferMatchField"} outcomes: type: array items: {"$ref": "#/components/schemas/VerifyProcedureOutcome"} AdminFinancialCaseKind: type: string enum: [provider_transfer, deposit, withdrawal, imported_review, credit_move, deposit_bonus_recovery] AdminFinancialCaseActionCode: type: string enum: [applied, not_applied, move_completed, move_compensated, move_not_applied, note, escalate] AdminFinancialCase: type: object required: [kind, id, user_id, provider_code, state, amount, updated_at, next_step, escalated, actions] properties: kind: {"$ref": "#/components/schemas/AdminFinancialCaseKind"} id: {type: string, format: uuid} user_id: {type: string, format: uuid} provider_code: {type: string} state: {type: string} amount: {"$ref": "#/components/schemas/MoneyAmount"} updated_at: {type: string, format: date-time} next_step: {type: string} escalated: {type: boolean} actions: type: array items: type: object required: [code, label, enabled, disabled_reason] properties: code: {"$ref": "#/components/schemas/AdminFinancialCaseActionCode"} label: {type: string} enabled: {type: boolean} disabled_reason: {type: string} AdminFinancialCaseReason: type: string description: Why an admin resolved, noted or escalated a financial case. enum: [provider_confirmed, provider_statement, player_confirmed, duplicate, test_cleanup, awaiting_provider, needs_investigation, other] x-enum-varnames: - AdminFinancialCaseReasonProviderConfirmed - AdminFinancialCaseReasonProviderStatement - AdminFinancialCaseReasonPlayerConfirmed - AdminFinancialCaseReasonDuplicate - AdminFinancialCaseReasonTestCleanup - AdminFinancialCaseReasonAwaitingProvider - AdminFinancialCaseReasonNeedsInvestigation - AdminFinancialCaseReasonOther AdminFinancialCaseCommand: type: object required: [action, reason_code, evidence_reference] properties: action: {"$ref": "#/components/schemas/AdminFinancialCaseActionCode"} reason_code: "$ref": "#/components/schemas/AdminFinancialCaseReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. evidence_reference: {type: string, maxLength: 255} provider_transaction_id: {type: string, maxLength: 255} source_applied: {type: boolean} destination_applied: {type: boolean} compensation_applied: {type: boolean} source_evidence_reference: {type: string, maxLength: 255} destination_evidence_reference: {type: string, maxLength: 255} compensation_evidence_reference: {type: string, maxLength: 255} proof_asset_id: {type: string, format: uuid} actual_fee_cents: {type: integer, format: int64, minimum: 0} actual_net_cents: {type: integer, format: int64, minimum: 0} AdminFinancialCasePreview: type: object required: [token, expires_at, case, consequences, movements] properties: token: {type: string, format: uuid} expires_at: {type: string, format: date-time} case: {"$ref": "#/components/schemas/AdminFinancialCase"} consequences: {type: string} movements: type: array items: type: object required: [resource, delta_cents] properties: resource: {type: string} delta_cents: {type: integer, format: int64} AdminFinancialCaseDetail: type: object required: [case, events, references] properties: case: {"$ref": "#/components/schemas/AdminFinancialCase"} references: type: array items: {"$ref": "#/components/schemas/AdminFinancialCaseReference"} events: type: array items: type: object required: [id, actor_id, action, reason, evidence_reference, state, created_at] properties: id: {type: string, format: uuid} actor_id: {type: string, format: uuid} action: {type: string} reason: {type: string} evidence_reference: {type: string} state: {type: string} created_at: {type: string, format: date-time} AdminFinancialCaseReference: type: object required: [kind, label, reference] properties: kind: {type: string, enum: [provider_order, provider_account, provider_transfer, payment, imported_review, provider_health, source_order, destination_order, compensation_order]} label: {type: string} reference: {type: string} ReconciliationQueueResponse: type: object required: - transfers - pagination properties: transfers: type: array items: "$ref": "#/components/schemas/ProviderTransfer" pagination: "$ref": "#/components/schemas/Pagination" FakeProviderOutcomeRequest: type: object required: - provider_code - operation - outcome additionalProperties: false properties: provider_code: "$ref": "#/components/schemas/ProviderCode" operation: type: string enum: - create_player - launch - load - unload outcome: type: string enum: - succeeded - rejected - unknown - duplicate_succeeded - duplicate_rejected external_order_id: type: string nullable: true message: type: string nullable: true FakeProviderOutcomeResponse: type: object required: - ok properties: ok: type: boolean ErrorResponse: type: object required: - error properties: field_errors: type: object additionalProperties: {type: string} description: Safe contract-defined field names mapped to actionable validation messages. error: "$ref": "#/components/schemas/APIError" RequestValidationRule: type: string enum: [required, enum, type, additionalProperties, format, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, minItems, maxItems, uniqueItems, minProperties, maxProperties, oneOf, anyOf, allOf, not, nullable, discriminator, const, readOnly, writeOnly, syntax, encoding, unknown] JSONValidationKind: type: string enum: [string, integer, number, boolean, object, array, "null", missing, invalid, json, unknown] RequestValidationIssue: type: object additionalProperties: false required: [path, rule, expected_kind, got_kind] description: >- Value-free request validation detail. Path is an RFC6901 JSON pointer; the empty string means the document root. Only contract property names and array indexes appear. Unknown properties identify their containing object; dynamic map members use their safe containing path. No submitted property names, values, enum alternatives or validator messages are echoed. At most 16 distinct issues are returned. Existing status and error codes remain unchanged. properties: path: {type: string, maxLength: 512} rule: {$ref: "#/components/schemas/RequestValidationRule"} expected_kind: {$ref: "#/components/schemas/JSONValidationKind"} got_kind: {$ref: "#/components/schemas/JSONValidationKind"} APIError: description: >- Browser API requests send X-Client-Build (the SHA-256 of their OpenAPI contract). When CFG_HTTP_CLIENT_BUILD_FILE enables the gate, mutating /api requests with a missing or mismatched contract hash receive HTTP 426 with code client_outdated before request validation or body decoding. Reload the current frontend and preserve the unsent draft; do not retry the rejected mutation automatically. Server-to-server webhooks are exempt. type: object required: - code - message properties: pending_load: {$ref: "#/components/schemas/PendingProviderLoad"} retry_after_seconds: type: integer format: int32 minimum: 1 maximum: 10 description: Seconds to wait before requesting another preview for the same game and amount after a temporary balance-read failure. field: {type: string, description: Safe invalid input field.} field_reason: {type: string, description: Stable safe field validation classification.} validation_issues: type: array maxItems: 16 description: Safe decode/validation details shared with the corresponding server log. items: {$ref: "#/components/schemas/RequestValidationIssue"} emulation_reason: {"$ref": "#/components/schemas/EmulationRefusalReason"} reason: {"$ref": "#/components/schemas/ProviderLoadReason"} store_management_reason: {"$ref": "#/components/schemas/GameStoreManagementReason"} account_management_reason: {"$ref": "#/components/schemas/ProviderAccountManagementReason"} game_activation_refusal: {$ref: "#/components/schemas/GameProviderActivationRefusal"} account_import_reason: {"$ref": "#/components/schemas/ProviderAccountImportReason"} mission_claim_reason: {"$ref": "#/components/schemas/MissionClaimRefusalReason"} staff_wallet_refusal_reason: {"$ref": "#/components/schemas/StaffWalletRefusalReason"} code: type: string enum: - bad_request - client_outdated - integration_unavailable - unauthorized - forbidden - conflict - rate_limited - internal_error - not_found - method_not_allowed - service_unavailable - account_unreadable - credentials_rejected - command_in_progress - timeout - request_canceled - credit_moves_disabled - provider_api_disabled - provider_temporarily_unavailable x-enum-varnames: [BadRequest, ClientOutdated, IntegrationUnavailable, Unauthorized, Forbidden, Conflict, RateLimited,InternalError, NotFound, MethodNotAllowed, ServiceUnavailable, AccountUnreadable, CredentialsRejected, CommandInProgress, Timeout, RequestCanceled, CreditMovesDisabledError, ProviderAPIDisabledError, ProviderTemporarilyUnavailableError] message: type: string request_id: type: string RewardBalance: type: object required: - user_id - xp - lifetime_xp - diamonds - spin_tokens - deposit_bonus - freeplay - pending_next_deposit_bonus_percent - pending_next_deposit_bonus_cap - updated_at properties: user_id: type: string format: uuid xp: type: integer format: int64 minimum: 0 lifetime_xp: type: integer format: int64 minimum: 0 description: Cumulative XP earned. Claims and spending never reduce it. diamonds: type: integer format: int64 minimum: 0 spin_tokens: type: integer format: int64 minimum: 0 deposit_bonus: "$ref": "#/components/schemas/MoneyAmount" freeplay: "$ref": "#/components/schemas/MoneyAmount" pending_next_deposit_bonus_percent: type: integer minimum: 0 pending_next_deposit_bonus_cap: "$ref": "#/components/schemas/MoneyAmount" updated_at: type: string format: date-time RewardChoiceKind: type: string enum: - freeplay - next_deposit_bonus RewardChoice: type: object required: - id - kind - required_xp - freeplay - next_deposit_bonus_percent - next_deposit_bonus_cap properties: id: type: string minLength: 1 kind: "$ref": "#/components/schemas/RewardChoiceKind" required_xp: type: integer format: int64 minimum: 1 freeplay: "$ref": "#/components/schemas/MoneyAmount" next_deposit_bonus_percent: type: integer minimum: 0 next_deposit_bonus_cap: "$ref": "#/components/schemas/MoneyAmount" RewardMarketplaceProductKind: type: string enum: - level_up - wheel_spins - freeplay RewardMarketplaceProduct: type: object required: - id - kind - diamond_cost - xp_grant - spin_token_grant - freeplay properties: id: type: string minLength: 1 kind: "$ref": "#/components/schemas/RewardMarketplaceProductKind" diamond_cost: type: integer format: int64 minimum: 1 xp_grant: type: integer format: int64 minimum: 0 spin_token_grant: type: integer format: int64 minimum: 0 freeplay: "$ref": "#/components/schemas/MoneyAmount" RewardRouletteOutcomeKind: type: string enum: - no_prize - diamonds - xp - extra_spin RewardRouletteOutcome: type: object required: - id - kind - weight - xp_grant - diamond_grant - spin_token_grant properties: id: type: string minLength: 1 kind: "$ref": "#/components/schemas/RewardRouletteOutcomeKind" weight: type: integer format: int64 minimum: 1 description: Relative draw weight of this outcome. The v1 config weights sum to 10,000, so each weight reads as basis points of probability; render odds as weight divided by the sum of all outcome weights. xp_grant: type: integer format: int64 minimum: 0 diamond_grant: type: integer format: int64 minimum: 0 spin_token_grant: type: integer format: int64 minimum: 0 RewardEventKind: type: string enum: - deposit_reward - deposit_reversal - daily_login_xp - weekly_login_xp - xp_reward_claim - marketplace_purchase - roulette_spin - admin_grant - admin_clawback - campaign_claim - mission_claim - referral_referrer_reward - referral_referee_bonus - referral_milestone_claim - provider_load - provider_load_refund - provider_cashout - inapp_signup_freeplay RewardEvent: type: object required: - id - user_id - kind - delta_xp - delta_diamonds - delta_spin_tokens - delta_deposit_bonus - delta_freeplay - balance - created_at properties: id: type: string format: uuid user_id: type: string format: uuid actor_id: type: string format: uuid nullable: true kind: "$ref": "#/components/schemas/RewardEventKind" delta_xp: type: integer format: int64 delta_diamonds: type: integer format: int64 delta_spin_tokens: type: integer format: int64 delta_deposit_bonus: "$ref": "#/components/schemas/MoneyAmount" delta_freeplay: "$ref": "#/components/schemas/MoneyAmount" balance: "$ref": "#/components/schemas/RewardBalance" reason: type: string nullable: true outcome_id: type: string nullable: true description: Roulette outcome ID for roulette_spin events so the wheel can land on the granted segment; null for every other event kind. created_at: type: string format: date-time RewardsSummaryResponse: type: object required: - balance - reward_choices - marketplace_products - roulette_outcomes properties: balance: "$ref": "#/components/schemas/RewardBalance" reward_choices: type: array items: "$ref": "#/components/schemas/RewardChoice" marketplace_products: type: array items: "$ref": "#/components/schemas/RewardMarketplaceProduct" roulette_outcomes: type: array items: "$ref": "#/components/schemas/RewardRouletteOutcome" RewardsHistoryResponse: type: object required: - events - pagination properties: events: type: array items: "$ref": "#/components/schemas/RewardEvent" pagination: "$ref": "#/components/schemas/Pagination" RewardCommandResponse: type: object required: - balance - event - replayed - effects properties: balance: "$ref": "#/components/schemas/RewardBalance" event: "$ref": "#/components/schemas/RewardEvent" replayed: type: boolean effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" RewardMarketplaceProductsResponse: type: object required: - products properties: products: type: array items: "$ref": "#/components/schemas/RewardMarketplaceProduct" RecentWinner: type: object additionalProperties: false required: [masked_username, kind, prize_amount, game_name, occurred_at] properties: masked_username: {type: string, pattern: '^[^*]+\*\*\*[^*]*$', maxLength: 7} kind: {type: string, enum: [wheel_gems, wheel_xp, wheel_spin]} prize_amount: type: integer format: int64 minimum: 1 description: Gems, XP or granted spin tokens from roulette; never a cash-out amount. game_name: {type: string, nullable: true} occurred_at: {type: string, format: date-time} RecentWinnersResponse: type: object additionalProperties: false required: [wins, refresh_after_ms] properties: wins: {type: array, maxItems: 100, items: {"$ref": "#/components/schemas/RecentWinner"}} refresh_after_ms: {type: integer, minimum: 1, description: Backend-owned active refresh cadence.} CashoutWinner: type: object additionalProperties: false required: [masked_username, kind, amount_cents, source_label, relative_time, is_big_win] properties: masked_username: {type: string, pattern: '^[^*]+\*\*\*[^*]*$', maxLength: 7} kind: {type: string, enum: [payment_cashout, game_withdrawal]} amount_cents: {type: integer, format: int64, minimum: 1, maximum: 9007199254740991, description: Whole USD cents actually paid to the player or returned to the wallet; not a requested amount or game credit balance.} source_label: {type: string, minLength: 1, maxLength: 120, description: Server-owned payment method or game display name. Never a destination or provider account identifier.} relative_time: {type: string, minLength: 1, maxLength: 30, description: Relative display time only; no exact timestamp is exposed.} is_big_win: {type: boolean, description: BIG WIN when game paid profit or payment cash-out net amount is strictly above the configured threshold. Equality is not highlighted; display-only, never changes payout eligibility.} RecentCashoutWinnersResponse: type: object additionalProperties: false required: [wins, refresh_after_ms] properties: wins: {type: array, maxItems: 4, items: {"$ref": "#/components/schemas/CashoutWinner"}} refresh_after_ms: {type: integer, minimum: 1} RecentWinnerSettingsValidationError: type: object required: [error, field_errors] properties: error: {"$ref": "#/components/schemas/APIError"} field_errors: type: object additionalProperties: {type: string} description: Contract field names threshold_cents, reason or expected_version, mapped to safe actionable messages. RecentWinnerSettings: type: object required: [threshold_cents, window_days, feed_size, version, updated_at] properties: readiness: {$ref: "#/components/schemas/SettingsReadiness", readOnly: true} threshold_cents: {type: integer, format: int64, minimum: 500, maximum: 9007199254740991, description: Configured Home winner floor and BIG WIN threshold, default8500. Game paid profit must exceed it; payment net amount must meet it with lifetime net-positive eligibility. BIG WIN is strictly above it. Does not filter roulette prizes.} window_days: {type: integer, minimum: 1, maximum: 30, default: 7} feed_size: {type: integer, minimum: 1, maximum: 100, default: 20} version: {type: integer, format: int64, minimum: 1} updated_at: {type: string, format: date-time} RecentWinnerSettingChange: type: object required: [version, previous_cents, next_cents, previous_window_days, next_window_days, previous_feed_size, next_feed_size, actor_id, reason, created_at] properties: version: {type: integer, format: int64} previous_cents: {type: integer, format: int64} next_cents: {type: integer, format: int64} previous_window_days: {type: integer} next_window_days: {type: integer} previous_feed_size: {type: integer} next_feed_size: {type: integer} actor_id: {type: string, format: uuid} reason: {type: string} created_at: {type: string, format: date-time} RecentWinnerSettingsResponse: type: object required: [settings, history, update_action] properties: settings: {"$ref": "#/components/schemas/RecentWinnerSettings"} history: {type: array, items: {"$ref": "#/components/schemas/RecentWinnerSettingChange"}} update_action: {"$ref": "#/components/schemas/InteractionAction"} UpdateRecentWinnerSettingsRequest: type: object additionalProperties: false required: [threshold_cents, expected_version, reason] properties: threshold_cents: {type: integer, format: int64, minimum: 500, maximum: 9007199254740991, description: Configured Home winner floor and BIG WIN threshold, default8500. Game paid profit must exceed it; payment net amount must meet it with lifetime net-positive eligibility. BIG WIN is strictly above it. Does not filter roulette prizes.} window_days: {type: integer, minimum: 1, maximum: 30, default: 7} feed_size: {type: integer, minimum: 1, maximum: 100, default: 20} expected_version: {type: integer, format: int64, minimum: 1} reason: {type: string, minLength: 3, maxLength: 500} RewardRouletteResponse: type: object required: - balance - outcomes properties: balance: "$ref": "#/components/schemas/RewardBalance" outcomes: type: array items: "$ref": "#/components/schemas/RewardRouletteOutcome" RewardXPClaimRequest: type: object required: - reward_choice_id additionalProperties: false properties: reward_choice_id: type: string minLength: 1 RewardMarketplacePurchaseRequest: type: object required: - product_id additionalProperties: false properties: product_id: type: string minLength: 1 ReferralSelectionRequest: type: object required: - referral_code additionalProperties: false properties: referral_code: type: string minLength: 1 maxLength: 64 ReferralPendingSelection: type: object required: - referrer_user_id - referral_code - selected_at - updated_at properties: referrer_user_id: type: string format: uuid referral_code: type: string minLength: 1 selected_at: type: string format: date-time updated_at: type: string format: date-time ReferralOutcomeKind: type: string enum: - rewarded - no_selection - referrer_ineligible - no_reward ReferralRewardAsset: type: string description: Frozen reward asset; missing historical markers mean freeplay. deposit_bonus is displayed as Bonus. enum: [freeplay, deposit_bonus] ReferralOutcome: type: object required: - payment_id - amount - outcome - created_at properties: reward_asset: {"$ref": "#/components/schemas/ReferralRewardAsset"} payment_id: type: string format: uuid amount: "$ref": "#/components/schemas/MoneyAmount" outcome: "$ref": "#/components/schemas/ReferralOutcomeKind" referrer_user_id: type: string format: uuid nullable: true referral_code: type: string nullable: true referrer_reward_event_id: type: string format: uuid nullable: true referee_bonus_event_id: type: string format: uuid nullable: true created_at: type: string format: date-time referee_bonus: nullable: true description: The invited player's one-off referral reward claimable; non-null only for a rewarded outcome. allOf: - "$ref": "#/components/schemas/ReferralRefereeBonus" ReferralClaimState: type: string description: Claim status of a claim-gated referral reward. enum: - pending - claimed x-enum-varnames: - ReferralClaimStatePending - ReferralClaimStateClaimed ReferralRefereeBonus: type: object required: - bonus - state properties: reward_asset: {"$ref": "#/components/schemas/ReferralRewardAsset"} bonus: description: The invited player's frozen referral reward amount in its declared asset. allOf: - "$ref": "#/components/schemas/MoneyAmount" state: "$ref": "#/components/schemas/ReferralClaimState" claimed_at: type: string format: date-time nullable: true ReferralOffer: type: object required: [inviter, friend, inviter_enabled, friend_enabled, qualification] properties: reward_asset: {"$ref": "#/components/schemas/ReferralRewardAsset"} inviter_enabled: {type: boolean} friend_enabled: {type: boolean} qualification: {"$ref": "#/components/schemas/BonusReferralQualification"} inviter: {"$ref": "#/components/schemas/BonusReferralReferrerRule"} friend: {"$ref": "#/components/schemas/BonusReferralRefereeRule"} ReferralStatusResponse: type: object required: - code - share_url - offer - selection_open - pending_selection - final_outcome properties: selection_open: {type: boolean, description: A referral code can be selected before any successful wallet deposit or frozen outcome.} offer: {"$ref": "#/components/schemas/ReferralOffer"} code: type: string minLength: 1 share_url: type: string format: uri pending_selection: nullable: true allOf: - "$ref": "#/components/schemas/ReferralPendingSelection" final_outcome: nullable: true allOf: - "$ref": "#/components/schemas/ReferralOutcome" ReferralSelectionResponse: type: object required: - status - effects properties: status: "$ref": "#/components/schemas/ReferralStatusResponse" effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" ReferralReward: type: object description: One of the referrer's per-referral rewards, keyed by the referral's triggering first successful wallet deposit. The payment_id field carries the deposit ID; historical earned awards retain their original opaque source identity. required: - referee_user_id - payment_id - reward - state - referral_code - created_at properties: reward_asset: {"$ref": "#/components/schemas/ReferralRewardAsset"} referee_user_id: type: string format: uuid payment_id: type: string format: uuid description: Opaque original qualifying source identity; future awards use the first successful wallet deposit ID. reward: description: The frozen inviter reward amount in its declared asset. allOf: - "$ref": "#/components/schemas/MoneyAmount" state: "$ref": "#/components/schemas/ReferralClaimState" referral_code: type: string claimed_at: type: string format: date-time nullable: true created_at: type: string format: date-time ReferralRewardsResponse: type: object required: - rewards - claimable_count - claimable - claimed properties: rewards: type: array items: "$ref": "#/components/schemas/ReferralReward" claimable_count: type: integer format: int64 minimum: 0 claimable: description: Total claimable inviter rewards across their declared assets. allOf: - "$ref": "#/components/schemas/MoneyAmount" claimed: description: Total claimed inviter rewards across their declared assets. allOf: - "$ref": "#/components/schemas/MoneyAmount" ReferralRewardClaimRequest: type: object required: - payment_id additionalProperties: false properties: payment_id: type: string format: uuid description: The rewarded referral's triggering payment to claim. ReferralRewardClaimResponse: type: object required: - state - granted - replayed - effects properties: reward_asset: {"$ref": "#/components/schemas/ReferralRewardAsset"} state: "$ref": "#/components/schemas/ReferralClaimState" granted: description: The amount granted in the declared reward asset. allOf: - "$ref": "#/components/schemas/MoneyAmount" replayed: type: boolean effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" RewardBalanceKind: type: string description: Grantable reward balance kind. freeplay amounts are integer USD cents. enum: - xp - diamonds - spin_tokens - freeplay AdminRewardGrantReason: type: string description: Why an admin gives a player a reward. enum: [goodwill, compensation, promotion, missed_reward, test_credit, other] x-enum-varnames: - AdminRewardGrantReasonGoodwill - AdminRewardGrantReasonCompensation - AdminRewardGrantReasonPromotion - AdminRewardGrantReasonMissedReward - AdminRewardGrantReasonTestCredit - AdminRewardGrantReasonOther AdminRewardGrantRequest: type: object required: - user_id - balance_kind - amount - reason_code additionalProperties: false properties: user_id: type: string format: uuid balance_kind: "$ref": "#/components/schemas/RewardBalanceKind" amount: type: integer format: int64 minimum: 1 description: Integer reward amount in the balance kind's own unit. Freeplay is whole USD cents, the same unit as wallet adjustments and campaign freeplay rewards. reason_code: "$ref": "#/components/schemas/AdminRewardGrantReason" note: type: string minLength: 1 maxLength: 400 description: Optional detail. Required (at least 3 characters) when reason_code is other; the server composes the audit text from the code and the note. RewardMissionId: type: string description: Reward mission catalog - the period-scoped missions plus the three lifetime referral-milestone missions (refer_5/refer_10/refer_20). Amounts come from the bonus rule settings (ADR 0023); a switched-off mission is left out of the catalog. No jackpot, draw, or live-event missions. enum: - daily_login - daily_deposit_match - daily_consistent_deposit - deposit_streak_3 - weekly_consistent_deposit - weekly_high_roller - monthly_deposit_milestone - refer_5 - refer_10 - refer_20 - second_deposit_match - weekly_next_load - login_streak RewardMissionPeriodKind: type: string description: Reward Period shape - calendar day, Monday-Sunday week, calendar month, or derived streak run (all keyed to America/New_York), or a never-expiring lifetime period (referral milestones). enum: - day - week - month - streak_run - lifetime RewardMissionClaimability: type: string enum: - in_progress - claimable - claimed - expired x-enum-varnames: - RewardMissionClaimabilityInProgress - RewardMissionClaimabilityClaimable - RewardMissionClaimabilityClaimed - RewardMissionClaimabilityExpired RewardMissionPayoutBasis: type: string description: How the freeplay payout amount is determined - a fixed amount, a percentage of the period's first or second qualifying deposit, a percentage of the period's qualifying-deposit sum, or a pending next-deposit bonus from the highest weekly tier reached (next_load_tiers). enum: - fixed - percent_first_qualifying_deposit - percent_qualifying_deposit_sum - percent_second_qualifying_deposit - next_deposit_bonus_tiers MissionClaimRefusalReason: type: string enum: [daily_limit_reached, mission_expired, bonus_already_pending, claim_conflict] MissionRewardKind: type: string enum: [freeplay, deposit_bonus, referral_bonus] RewardMissionPayout: type: object required: - basis - reward_kind - xp - freeplay - percent - percent_cap properties: reward_kind: {"$ref": "#/components/schemas/MissionRewardKind"} basis: "$ref": "#/components/schemas/RewardMissionPayoutBasis" xp: type: integer format: int64 minimum: 0 description: Fixed XP grant (basis fixed); zero otherwise. freeplay: description: Fixed freeplay grant (basis fixed); zero otherwise. allOf: - "$ref": "#/components/schemas/MoneyAmount" bonus: $ref: "#/components/schemas/MoneyAmount" percent: type: integer minimum: 0 description: Payout percentage for percent bases; zero for fixed. percent_cap: description: Per-period cap applied to percent payouts; zero for fixed. allOf: - "$ref": "#/components/schemas/MoneyAmount" RewardMissionCatalogEntry: type: object required: - id - period_kind - payout - deposit_activated_freeplay - deposit_activated_spin_tokens - required_qualifying_deposits - required_qualifying_days - required_streak_days - required_volume - required_referral_count properties: id: "$ref": "#/components/schemas/RewardMissionId" period_kind: "$ref": "#/components/schemas/RewardMissionPeriodKind" payout: "$ref": "#/components/schemas/RewardMissionPayout" deposit_activated_freeplay: description: Extra freeplay the daily login claim grants once the account is deposit-activated; zero for other missions. allOf: - "$ref": "#/components/schemas/MoneyAmount" deposit_activated_spin_tokens: type: integer format: int64 minimum: 0 description: Free Daily Spin tokens the daily login claim grants once the account is deposit-activated; zero for other missions. Granted by the same claim (or same-day unlock top-up) as the activated freeplay. required_qualifying_deposits: type: integer format: int64 minimum: 0 required_qualifying_days: type: integer format: int64 minimum: 0 required_streak_days: type: integer format: int64 minimum: 0 required_volume: description: Total successful deposit volume required in the period; zero when not applicable. allOf: - "$ref": "#/components/schemas/MoneyAmount" required_referral_count: type: integer format: int64 minimum: 0 description: Rewarded referrals required to complete a lifetime referral-milestone mission; zero for other missions. next_load_tiers: type: array description: weekly_next_load only - weekly deposit thresholds and the next-deposit bonus each earns; the highest tier reached applies. items: {"$ref": "#/components/schemas/RewardMissionNextLoadTier"} RewardMissionNextLoadTier: type: object required: [required_volume, percent, percent_cap] properties: required_volume: {"$ref": "#/components/schemas/MoneyAmount"} percent: {type: integer, minimum: 1} percent_cap: {"$ref": "#/components/schemas/MoneyAmount"} RewardMissionProgress: type: object required: - mission_id - period_kind - period_key - period_start - period_end - claimable_until - state - completed - qualifying_deposits - qualifying_days - streak_progress_days - volume - qualifying_deposit_sum - first_qualifying_deposit - deposit_activated - referral_count - every_deposit_bonus - payout_after_every_deposit properties: claimed_payout: description: Actual recorded payout of a claimed referral milestone. $ref: "#/components/schemas/RewardMissionPayout" every_deposit_bonus: allOf: - "$ref": "#/components/schemas/MoneyAmount" description: First- and second-deposit match only, and zero otherwise - the bonus the every-deposit rule paid on the deposit the match pays on. It is counted against the match; the deposit earns the larger of the two. payout_after_every_deposit: allOf: - "$ref": "#/components/schemas/MoneyAmount" description: Meaningful when every_deposit_bonus is above zero - what claiming the match will pay now (the match minus that bonus, never below zero). Show this instead of the full match amount; zero means the bonus already covers it. mission_id: "$ref": "#/components/schemas/RewardMissionId" period_kind: "$ref": "#/components/schemas/RewardMissionPeriodKind" period_key: type: string minLength: 1 description: Claim identity key - day and streak-run keys are "2006-01-02", week keys are the Monday date "2006-01-02", month keys are "2006-01". period_start: type: string format: date-time period_end: type: string format: date-time claimable_until: type: string format: date-time description: Grace deadline - period end plus the grace window; the completed mission expires unclaimed afterwards. daily_limit_resets_at: type: string format: date-time description: Present when the daily reward limit blocks this earned mission. The player can claim after reset if the claim window is still open and the next read confirms availability. state: "$ref": "#/components/schemas/RewardMissionClaimability" completed: type: boolean qualifying_deposits: type: integer format: int64 minimum: 0 qualifying_days: type: integer format: int64 minimum: 0 streak_progress_days: type: integer format: int64 minimum: 0 volume: description: Total successful deposit volume in the period; zero when not applicable to the mission. allOf: - "$ref": "#/components/schemas/MoneyAmount" qualifying_deposit_sum: allOf: - "$ref": "#/components/schemas/MoneyAmount" first_qualifying_deposit: allOf: - "$ref": "#/components/schemas/MoneyAmount" deposit_activated: type: boolean description: daily_login only - whether the account has any successful deposit, unlocking the freeplay portion of the claim. referral_count: type: integer format: int64 minimum: 0 description: Lifetime referral-milestone missions only - the user's rewarded-referral count so far; zero for other missions. RewardsMissionsResponse: type: object required: - missions_enabled - catalog - entries - weekly_login_streaks properties: missions_enabled: type: boolean description: Missions kill switch state. When false the client must hide the missions panel; mission claim requests are refused. catalog: type: array items: "$ref": "#/components/schemas/RewardMissionCatalogEntry" entries: type: array description: Derived progress - each mission's current period, completed previous periods still inside the grace window, and one entry per derived streak run. items: "$ref": "#/components/schemas/RewardMissionProgress" weekly_login_streaks: type: array description: Derived weekly login streak state (not a catalog mission) - the current week always, plus the previous week while it is completed or claimed (a completed previous week stays claimable through the grace window). items: "$ref": "#/components/schemas/RewardWeeklyLoginStreak" RewardWeeklyLoginStreak: type: object description: Derived weekly login streak read state for one Monday-Sunday New York week (the weekly login XP claim). required: - week_start - days_claimed - completed - state - period_end - claimable_until - granted_xp properties: week_start: type: string minLength: 1 description: The week's Monday date "2006-01-02" (the claim identity key). days_claimed: type: integer format: int64 minimum: 0 maximum: 7 description: Days of the week with a daily login claim (0-7). completed: type: boolean state: "$ref": "#/components/schemas/RewardMissionClaimability" period_end: type: string format: date-time claimable_until: type: string format: date-time description: Period end plus the grace window. granted_xp: type: integer format: int64 description: Fixed XP the weekly claim grants. RewardMissionClaimRequest: type: object required: - mission_id additionalProperties: false properties: mission_id: "$ref": "#/components/schemas/RewardMissionId" period_key: type: string description: Period being claimed; omitted selects the period the server resolves as currently claimable. RewardMissionClaimResponse: type: object description: RewardCommandResponse shape plus the resolved mission claim identity (mission_id and the server-resolved period_key). required: - balance - event - replayed - effects - mission_id - period_key properties: balance: "$ref": "#/components/schemas/RewardBalance" event: "$ref": "#/components/schemas/RewardEvent" replayed: type: boolean effects: type: array items: "$ref": "#/components/schemas/ResourceEffect" mission_id: "$ref": "#/components/schemas/RewardMissionId" period_key: type: string minLength: 1 RewardSandboxCommandKind: type: string description: Injectable sandbox step kinds - reward commands mirror their production counterparts; the rest are operator controls. enum: - deposit - claim_daily_login - claim_weekly_streak - claim_mission - claim_xp_reward - purchase_marketplace - spin_roulette - admin_grant - set_clock - advance_clock - arm_error - disarm_errors - reset - load_preset RewardSandboxArmedError: type: string description: Operator-armed failure mode applied to the next matching simulated command, then cleared (fire-once). enum: - claim_rejection - insufficient_balance - idempotency_replay - idempotency_conflict RewardSandboxPreset: type: string enum: - new_user - deposit_activated - xp_threshold_freeplay_3 - xp_threshold_freeplay_5 - xp_threshold_next_deposit_bonus - pending_next_deposit_bonus - mid_deposit_streak - claimable_completed_missions - expired_missions RewardSandboxCommand: type: object description: One injected sandbox step. Only the fields for the chosen kind are read; the rest stay unset. required: - kind additionalProperties: false properties: kind: "$ref": "#/components/schemas/RewardSandboxCommandKind" amount_cents: type: integer format: int64 minimum: 1 description: Simulated successful deposit amount in USD cents (deposit). mission_id: nullable: true allOf: - "$ref": "#/components/schemas/RewardMissionId" period_key: type: string description: Optional period selector (claim_mission, claim_weekly_streak); empty resolves the period the virtual clock makes currently claimable. reward_choice_id: type: string description: XP reward choice (claim_xp_reward). product_id: type: string description: Marketplace product (purchase_marketplace). forced_outcome_id: type: string description: Forces a roulette outcome by ID instead of rolling the seeded RNG (spin_roulette, optional). grant_kind: nullable: true allOf: - "$ref": "#/components/schemas/RewardBalanceKind" grant_amount: type: integer format: int64 minimum: 1 description: Admin grant amount (admin_grant). For freeplay, USD cents. grant_reason: type: string description: Admin grant reason (admin_grant). clock_to: type: string format: date-time description: Absolute virtual clock instant (set_clock). advance_by_ms: type: integer format: int64 description: Relative virtual clock advance in milliseconds (advance_clock). arm_error: nullable: true allOf: - "$ref": "#/components/schemas/RewardSandboxArmedError" preset: nullable: true allOf: - "$ref": "#/components/schemas/RewardSandboxPreset" RewardSandboxCommandResult: type: object description: Engine command result recorded for an applied or replayed sandbox reward command. required: - balance - event - replayed properties: balance: "$ref": "#/components/schemas/RewardBalance" event: "$ref": "#/components/schemas/RewardEvent" replayed: type: boolean RewardSandboxLogEntry: type: object required: - seq - at - command - decision properties: seq: type: integer at: type: string format: date-time description: Virtual clock instant the step ran at. command: "$ref": "#/components/schemas/RewardSandboxCommand" decision: type: string description: Human-readable description of the decision taken. result: nullable: true allOf: - "$ref": "#/components/schemas/RewardSandboxCommandResult" error: type: string nullable: true description: Typed rejection error string when the command was rejected. armed_error_fired: nullable: true allOf: - "$ref": "#/components/schemas/RewardSandboxArmedError" RewardSandboxSnapshot: type: object required: - session_id - now - seed - balance - deposit_activated - missions - weekly_login_streaks - armed_errors - event_log properties: session_id: type: string format: uuid now: type: string format: date-time description: The session's virtual clock. seed: type: integer format: int64 description: The session's roulette RNG seed. balance: "$ref": "#/components/schemas/RewardBalance" deposit_activated: type: boolean missions: type: array items: "$ref": "#/components/schemas/RewardMissionProgress" weekly_login_streaks: type: array description: Derived weekly login streak read state, reusing the missions read model schema (same evaluator, same shape). items: "$ref": "#/components/schemas/RewardWeeklyLoginStreak" armed_errors: type: array description: Failure modes armed and not yet fired, in arm order. items: "$ref": "#/components/schemas/RewardSandboxArmedError" event_log: type: array items: "$ref": "#/components/schemas/RewardSandboxLogEntry" RewardSandboxStepResult: type: object required: - snapshot - entry properties: snapshot: "$ref": "#/components/schemas/RewardSandboxSnapshot" entry: "$ref": "#/components/schemas/RewardSandboxLogEntry" RewardSandboxCreateRequest: type: object additionalProperties: false properties: start_at: type: string format: date-time description: Initial virtual clock instant; defaults to the wall clock. seed: type: integer format: int64 description: Roulette RNG seed; defaults to a fixed constant. preset: nullable: true allOf: - "$ref": "#/components/schemas/RewardSandboxPreset" RewardSandboxPresetInfo: type: object required: - id - description properties: id: "$ref": "#/components/schemas/RewardSandboxPreset" description: type: string RewardSandboxPresetsResponse: type: object required: - presets properties: presets: type: array items: "$ref": "#/components/schemas/RewardSandboxPresetInfo" AcquisitionLandingTouchSchemaVersion: type: string enum: - acquisition.landing-touch/2026-07-17.v1 AcquisitionAdClickIDKind: type: string enum: - gclid - fbclid - msclkid - ttclid AcquisitionEntrySource: type: string enum: [inapp_open] x-enum-varnames: [AcquisitionEntrySourceInappOpen] description: Functional signup entry marker from the src=inapp_open browser-opening link. AcquisitionLandingTouchRequest: type: object additionalProperties: false required: - anonymous_subject - schema_version - occurred_at - landing_path - consent properties: entry_source: {"$ref": "#/components/schemas/AcquisitionEntrySource"} anonymous_subject: type: string format: uuid schema_version: "$ref": "#/components/schemas/AcquisitionLandingTouchSchemaVersion" occurred_at: type: string format: date-time landing_path: type: string minLength: 1 maxLength: 1024 description: A path or URL; only its normalized path is persisted, without query or fragment. referrer: type: string format: uri maxLength: 2048 description: Referrer URL; only its normalized host is persisted. utm_source: type: string minLength: 1 maxLength: 200 utm_medium: type: string minLength: 1 maxLength: 200 utm_campaign: type: string minLength: 1 maxLength: 200 utm_term: type: string minLength: 1 maxLength: 200 utm_content: type: string minLength: 1 maxLength: 200 ad_click_id_kind: "$ref": "#/components/schemas/AcquisitionAdClickIDKind" ad_click_id: type: string minLength: 1 maxLength: 512 description: Raw value accepted for keyed HMAC processing and never persisted or returned. consent: type: boolean AcquisitionLandingTouchResponse: type: object additionalProperties: false required: - id - anonymous_subject - schema_version - occurred_at - received_at - landing_path - consent - replayed properties: id: type: string format: uuid anonymous_subject: type: string format: uuid schema_version: "$ref": "#/components/schemas/AcquisitionLandingTouchSchemaVersion" occurred_at: type: string format: date-time received_at: type: string format: date-time landing_path: type: string consent: type: boolean replayed: type: boolean GrowthWindow: type: object required: - from - to properties: from: type: string format: date-time to: type: string format: date-time GrowthOverviewResponse: type: object required: - generated_at - window - timezone - exclusion_rule_version - landing_touches - anonymous_visitors - registered_users - activated_users - active_users - deposited_users - cashed_out_users - registration_rate_bps - activation_rate_bps properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/GrowthWindow" timezone: type: string exclusion_rule_version: type: string landing_touches: type: integer format: int64 minimum: 0 anonymous_visitors: type: integer format: int64 minimum: 0 registered_users: type: integer format: int64 minimum: 0 activated_users: type: integer format: int64 minimum: 0 active_users: type: integer format: int64 minimum: 0 deposited_users: type: integer format: int64 minimum: 0 cashed_out_users: type: integer format: int64 minimum: 0 registration_rate_bps: type: integer format: int64 minimum: 0 maximum: 10000 activation_rate_bps: type: integer format: int64 minimum: 0 maximum: 10000 GrowthAcquisitionChannel: type: object required: - source - medium - campaign - landing_touches - anonymous_visitors - registered_users - activated_users - deposited_users properties: source: type: string medium: type: string campaign: type: string landing_touches: type: integer format: int64 minimum: 0 anonymous_visitors: type: integer format: int64 minimum: 0 registered_users: type: integer format: int64 minimum: 0 activated_users: type: integer format: int64 minimum: 0 deposited_users: type: integer format: int64 minimum: 0 GrowthAcquisitionResponse: type: object required: - generated_at - window - timezone - exclusion_rule_version - channels properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/GrowthWindow" timezone: type: string exclusion_rule_version: type: string channels: type: array items: "$ref": "#/components/schemas/GrowthAcquisitionChannel" GrowthFunnelResponse: type: object required: - generated_at - window - timezone - exclusion_rule_version - registered_users - activated_users - deposited_users - cashed_out_users properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/GrowthWindow" timezone: type: string exclusion_rule_version: type: string registered_users: type: integer format: int64 minimum: 0 activated_users: type: integer format: int64 minimum: 0 deposited_users: type: integer format: int64 minimum: 0 cashed_out_users: type: integer format: int64 minimum: 0 GrowthRetentionMetric: type: object required: - mature - users - rate_bps properties: mature: type: boolean users: type: integer format: int64 minimum: 0 nullable: true description: Null until the complete exact-day window has matured. rate_bps: type: integer format: int64 minimum: 0 maximum: 10000 nullable: true description: Null until the complete exact-day window has matured. GrowthRetentionWindow: type: object required: - exact - rolling properties: exact: "$ref": "#/components/schemas/GrowthRetentionMetric" rolling: "$ref": "#/components/schemas/GrowthRetentionMetric" GrowthRetentionCohort: type: object required: - cohort_date - cohort_size - d1 - d7 - d30 properties: cohort_date: type: string format: date cohort_size: type: integer format: int64 minimum: 0 d1: "$ref": "#/components/schemas/GrowthRetentionWindow" d7: "$ref": "#/components/schemas/GrowthRetentionWindow" d30: "$ref": "#/components/schemas/GrowthRetentionWindow" GrowthRetentionResponse: type: object required: - generated_at - window - as_of - timezone - exclusion_rule_version - cohorts properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/GrowthWindow" as_of: type: string format: date-time timezone: type: string exclusion_rule_version: type: string cohorts: type: array items: "$ref": "#/components/schemas/GrowthRetentionCohort" WithdrawalProvenanceQuality: type: string enum: - authoritative - explicit_non_game - non_authoritative - mixed - unattributed WithdrawalProvenanceSourceKind: type: string enum: - provider_cashout - tester - admin - legacy_opening - provider_reviewed_unload WithdrawalProvenanceAttributionScope: type: string enum: - provider_platform_only - explicit_non_game - legacy_opening WithdrawalProvenanceSource: type: object additionalProperties: false required: - lot_id - withdrawal_id - source_kind - attribution_scope - attribution_note - original_amount_cents - prior_consumed_amount_cents - currently_reserved_amount_cents - current_allocation_amount_cents - remaining_amount_cents - current_payable_amount_cents - quality - occurred_at - created_at - reserved_at properties: lot_id: type: string format: uuid withdrawal_id: type: string format: uuid source_kind: "$ref": "#/components/schemas/WithdrawalProvenanceSourceKind" attribution_scope: "$ref": "#/components/schemas/WithdrawalProvenanceAttributionScope" attribution_note: type: string description: Explicitly states the evidence scope and any game-level limitation. provider_code: type: string game_ref: type: string description: Present only when a source record carries a game reference; provider cashout evidence alone is not individual-game proof. provider_account_id: type: string format: uuid provider_account_ref: type: string cashout_transfer_id: type: string format: uuid cashout_ref: type: string original_amount_cents: type: integer format: int64 minimum: 0 prior_consumed_amount_cents: type: integer format: int64 minimum: 0 currently_reserved_amount_cents: type: integer format: int64 minimum: 0 current_allocation_amount_cents: type: integer format: int64 minimum: 0 remaining_amount_cents: type: integer format: int64 current_payable_amount_cents: type: integer format: int64 minimum: 0 quality: "$ref": "#/components/schemas/WithdrawalProvenanceQuality" occurred_at: type: string format: date-time created_at: type: string format: date-time reserved_at: type: string format: date-time terminal_at: type: string format: date-time WithdrawalProvenanceResponse: type: object additionalProperties: false required: - withdrawal_id - user_id - state - requested_amount_cents - reservation_amount_cents - currently_reserved_amount_cents - gross_amount_cents - estimated_fee_amount_cents - estimated_net_amount_cents - allocated_amount_cents - ledger_balance_cents - reconciliation_delta_cents - quality - requested_at - reserved_at - sources properties: withdrawal_id: type: string format: uuid user_id: type: string format: uuid state: "$ref": "#/components/schemas/PaymentWithdrawalState" requested_amount_cents: type: integer format: int64 minimum: 0 reservation_amount_cents: type: integer format: int64 minimum: 0 currently_reserved_amount_cents: type: integer format: int64 minimum: 0 gross_amount_cents: type: integer format: int64 minimum: 0 estimated_fee_amount_cents: type: integer format: int64 minimum: 0 estimated_net_amount_cents: type: integer format: int64 minimum: 0 actual_fee_amount_cents: type: integer format: int64 minimum: 0 actual_net_amount_cents: type: integer format: int64 minimum: 0 allocated_amount_cents: type: integer format: int64 minimum: 0 ledger_balance_cents: type: integer format: int64 reconciliation_delta_cents: type: integer format: int64 quality: "$ref": "#/components/schemas/WithdrawalProvenanceQuality" requested_at: type: string format: date-time reserved_at: type: string format: date-time completed_at: type: string format: date-time sources: type: array items: "$ref": "#/components/schemas/WithdrawalProvenanceSource" PlayerWithdrawalProvenanceSummaryResponse: type: object additionalProperties: false required: - user_id - original_amount_cents - prior_consumed_amount_cents - reserved_amount_cents - allocated_amount_cents - remaining_amount_cents - current_payable_amount_cents - ledger_balance_cents - reconciliation_delta_cents - quality properties: user_id: type: string format: uuid original_amount_cents: type: integer format: int64 minimum: 0 prior_consumed_amount_cents: type: integer format: int64 minimum: 0 reserved_amount_cents: type: integer format: int64 minimum: 0 allocated_amount_cents: type: integer format: int64 minimum: 0 remaining_amount_cents: type: integer format: int64 current_payable_amount_cents: type: integer format: int64 minimum: 0 ledger_balance_cents: type: integer format: int64 reconciliation_delta_cents: type: integer format: int64 quality: "$ref": "#/components/schemas/WithdrawalProvenanceQuality" AdminPenguConversationStatus: type: string enum: [active, archived] AdminPenguRunStatus: type: string enum: [queued, running, completed, failed, cancelled] AdminPenguMessageRole: type: string enum: [user, assistant, system] AdminPenguConversation: type: object additionalProperties: false required: [id, title, creator_admin_id, status, message_seq, created_at, updated_at] properties: id: {type: string, format: uuid} title: {type: string, minLength: 1, maxLength: 200} creator_admin_id: {type: string, format: uuid} status: {"$ref": "#/components/schemas/AdminPenguConversationStatus"} folder_id: {type: string, format: uuid, nullable: true} origin_route: {type: string, nullable: true, maxLength: 500} entity_context: type: object additionalProperties: true message_seq: {type: integer, format: int64, minimum: 0} last_message_at: {type: string, format: date-time, nullable: true} archived_at: {type: string, format: date-time, nullable: true} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} AdminPenguCreateConversationRequest: type: object additionalProperties: false properties: title: {type: string, minLength: 1, maxLength: 200, default: New conversation} folder_id: {type: string, format: uuid, nullable: true} origin_route: {type: string, minLength: 1, maxLength: 500} entity_context: type: object additionalProperties: true AdminPenguFolder: type: object additionalProperties: false required: [id, creator_admin_id, name, created_at, updated_at] properties: id: {type: string, format: uuid} creator_admin_id: {type: string, format: uuid} parent_id: {type: string, format: uuid, nullable: true} name: {type: string, minLength: 1, maxLength: 120} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} AdminPenguCreateFolderRequest: type: object additionalProperties: false required: [name] properties: name: {type: string, minLength: 1, maxLength: 120} parent_id: {type: string, format: uuid, nullable: true} AdminPenguRenameFolderRequest: type: object additionalProperties: false required: [name] properties: name: {type: string, minLength: 1, maxLength: 120} AdminPenguMoveFolderRequest: type: object additionalProperties: false required: [parent_id] properties: parent_id: {type: string, format: uuid, nullable: true} AdminPenguMoveConversationRequest: type: object additionalProperties: false required: [folder_id] properties: folder_id: {type: string, format: uuid, nullable: true} AdminPenguCreateTurnRequest: type: object additionalProperties: false required: [message] properties: message: {type: string, minLength: 1, maxLength: 20000} AdminPenguRun: type: object additionalProperties: false required: - id - conversation_id - actor_admin_id - status - provider_id - model_id - analysis_attempts - attempts_remaining - queued_at - created_at - updated_at properties: id: {type: string, format: uuid} conversation_id: {type: string, format: uuid} actor_admin_id: {type: string, format: uuid} status: {"$ref": "#/components/schemas/AdminPenguRunStatus"} provider_id: {type: string, minLength: 1, maxLength: 120} model_id: {type: string, minLength: 1, maxLength: 200} analysis_attempts: {type: integer, minimum: 0, maximum: 4} attempts_remaining: {type: integer, minimum: 0, maximum: 4} error_category: {type: string, nullable: true, maxLength: 120} queued_at: {type: string, format: date-time} started_at: {type: string, format: date-time, nullable: true} completed_at: {type: string, format: date-time, nullable: true} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} AdminPenguDatasetColumn: type: object additionalProperties: false required: [name, type] properties: name: type: string pattern: '^[A-Za-z_][A-Za-z0-9_]*$' maxLength: 80 type: type: string enum: [text, uuid, int2, int4, int8, numeric, float4, float8, bool, date, timestamp, timestamptz] AdminPenguDatasetValue: nullable: true oneOf: - {type: string} - {type: number, format: double} - {type: boolean} AdminPenguDataset: type: object additionalProperties: false required: [columns, rows, row_count, truncated] properties: columns: type: array minItems: 1 maxItems: 50 items: {"$ref": "#/components/schemas/AdminPenguDatasetColumn"} rows: type: array maxItems: 500 items: type: array items: {"$ref": "#/components/schemas/AdminPenguDatasetValue"} row_count: {type: integer, minimum: 0} truncated: {type: boolean} AdminPenguElement: type: object additionalProperties: false required: [type, props, children] properties: type: type: string enum: [Report, Section, Grid, Markdown, Metric, MetricGroup, TimeSeriesChart, BarChart, DataTable, Timeline, Alert, EntityList] props: type: object additionalProperties: true children: type: array items: type: string pattern: '^[A-Za-z0-9_-]+$' maxLength: 80 AdminPenguSurface: type: object additionalProperties: false required: [root, elements] properties: root: type: string pattern: '^[A-Za-z0-9_-]+$' maxLength: 80 elements: type: object additionalProperties: {"$ref": "#/components/schemas/AdminPenguElement"} AdminPenguArtifact: type: object additionalProperties: false required: [id, schema_version, catalog_version, datasets, surface] properties: id: {type: string, format: uuid} schema_version: {type: integer, enum: [1]} catalog_version: {type: integer, enum: [1]} datasets: type: object additionalProperties: {"$ref": "#/components/schemas/AdminPenguDataset"} surface: {"$ref": "#/components/schemas/AdminPenguSurface"} AdminPenguQueryEvidence: type: object additionalProperties: false required: [id, attempt, sequence, name, sql, duration_ms, row_count, byte_count, truncated, outcome] properties: id: {type: string, format: uuid} attempt: {type: integer, minimum: 1, maximum: 4} sequence: {type: integer, minimum: 1, maximum: 8} name: {type: string, pattern: '^[a-z][a-z0-9_]{0,63}$'} sql: {type: string, minLength: 1} duration_ms: {type: integer, format: int64, minimum: 0} row_count: {type: integer, minimum: 0, maximum: 500} byte_count: {type: integer, format: int64, minimum: 0, maximum: 1048576} truncated: {type: boolean} outcome: type: string enum: [succeeded, rejected, timed_out, cancelled, failed] error_category: {type: string, nullable: true, maxLength: 120} AdminPenguMessagePart: type: object additionalProperties: false required: [type] properties: type: type: string enum: [text, artifact, evidence] text: {type: string, maxLength: 50000} artifact: {"$ref": "#/components/schemas/AdminPenguArtifact"} queries: type: array maxItems: 32 items: {"$ref": "#/components/schemas/AdminPenguQueryEvidence"} AdminPenguMessage: type: object additionalProperties: false required: [id, conversation_id, sequence, role, parts, created_at] properties: id: {type: string, format: uuid} conversation_id: {type: string, format: uuid} run_id: {type: string, format: uuid, nullable: true} sequence: {type: integer, format: int64, minimum: 1} role: {"$ref": "#/components/schemas/AdminPenguMessageRole"} parts: type: array minItems: 1 items: {"$ref": "#/components/schemas/AdminPenguMessagePart"} created_at: {type: string, format: date-time} AdminPenguConversationResponse: type: object additionalProperties: false required: [conversation] properties: conversation: {"$ref": "#/components/schemas/AdminPenguConversation"} AdminPenguFolderResponse: type: object additionalProperties: false required: [folder] properties: folder: {"$ref": "#/components/schemas/AdminPenguFolder"} AdminPenguFoldersResponse: type: object additionalProperties: false required: [folders] properties: folders: type: array items: {"$ref": "#/components/schemas/AdminPenguFolder"} AdminPenguConversationsResponse: type: object additionalProperties: false required: [conversations, has_more] properties: conversations: type: array items: {"$ref": "#/components/schemas/AdminPenguConversation"} has_more: {type: boolean} next_before_updated_at: {type: string, format: date-time, nullable: true} next_before_id: {type: string, format: uuid, nullable: true} AdminPenguConversationDetailResponse: type: object additionalProperties: false required: [conversation, messages] properties: conversation: {"$ref": "#/components/schemas/AdminPenguConversation"} messages: type: array items: {"$ref": "#/components/schemas/AdminPenguMessage"} active_run: nullable: true allOf: - {"$ref": "#/components/schemas/AdminPenguRun"} AdminPenguRunResponse: type: object additionalProperties: false required: [run] properties: run: {"$ref": "#/components/schemas/AdminPenguRun"} ManualPaymentClaimMethod: type: string enum: [cash_app, paypal, chime] ManualDepositClaimMethodId: type: string pattern: '^(cash_app|chime|paypal|venmo|custom_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$' description: Stable enabled manual deposit method key; catalog IDs retain their identity across display-name changes. ManualPaymentClaimRounding: type: string enum: [none, ceil_dollar] x-enum-varnames: [ManualClaimRoundingNone, ManualClaimRoundingCeilDollar] PaymentMethodDisplayOrder: type: object additionalProperties: false required: [deposit, payout] description: Ordered stable card keys per direction. Empty preserves current order; unlisted new methods follow existing relative order. One online/house card shares its method key. properties: deposit: {type: array, maxItems: 64, uniqueItems: true, items: {type: string, minLength: 1, maxLength: 100}} payout: {type: array, maxItems: 64, uniqueItems: true, items: {type: string, minLength: 1, maxLength: 100}} HouseMethodIcon: type: string enum: [wallet, bank, phone] HousePayoutMode: type: string enum: [pay_player, request_on_house_tag] HousePaymentMethod: type: object required: [id, name, icon, logo_data_url, enabled, input, qr_payload, tag, payment_link] properties: id: {type: string, minLength: 1, maxLength: 100} name: {type: string, minLength: 1, maxLength: 64} icon: {$ref: "#/components/schemas/HouseMethodIcon"} logo_data_url: {type: string, maxLength: 22000, description: Validated small PNG or JPEG logo data URL; uploaded images are resized before saving. SVG and external image URLs are not accepted.} enabled: {type: boolean} input: {type: string, maxLength: 2048, description: House receiving link or tag; parsed by the shared smart-input parser.} qr_payload: {type: string, maxLength: 512} tag: {type: string, maxLength: 2048, readOnly: true} payment_link: {type: string, maxLength: 2048, readOnly: true} HouseDepositMethod: allOf: - "$ref": "#/components/schemas/HousePaymentMethod" - type: object required: [rounding] properties: rounding: {$ref: "#/components/schemas/ManualPaymentClaimRounding"} HousePayoutMethod: allOf: - "$ref": "#/components/schemas/HousePaymentMethod" - type: object required: [allow_player_mode_choice, default_mode] properties: allow_player_mode_choice: {type: boolean, description: Off fixes the default mode; on offers both supported paths to players.} default_mode: {$ref: "#/components/schemas/HousePayoutMode"} HousePaymentMethodInput: type: object additionalProperties: false required: [id, name, icon, logo_data_url, enabled, input, qr_payload] properties: id: {type: string, minLength: 1, maxLength: 100} name: {type: string, minLength: 1, maxLength: 64} icon: {$ref: "#/components/schemas/HouseMethodIcon"} logo_data_url: {type: string, maxLength: 22000, description: Validated small PNG or JPEG logo data URL; uploaded images are resized before saving. SVG and external image URLs are not accepted.} enabled: {type: boolean} input: {type: string, maxLength: 2048, description: House receiving link or tag; parsed by the shared smart-input parser.} qr_payload: {type: string, maxLength: 512} HouseDepositMethodInput: type: object additionalProperties: false required: [id, name, icon, logo_data_url, enabled, input, qr_payload, rounding] properties: id: {type: string, minLength: 1, maxLength: 100} name: {type: string, minLength: 1, maxLength: 64} icon: {$ref: "#/components/schemas/HouseMethodIcon"} logo_data_url: {type: string, maxLength: 22000, description: Validated small PNG or JPEG logo data URL; uploaded images are resized before saving. SVG and external image URLs are not accepted.} enabled: {type: boolean} input: {type: string, maxLength: 2048, description: House receiving link or tag; parsed by the shared smart-input parser.} qr_payload: {type: string, maxLength: 512} rounding: {$ref: "#/components/schemas/ManualPaymentClaimRounding"} HousePayoutMethodInput: type: object additionalProperties: false required: [id, name, icon, logo_data_url, enabled, input, qr_payload, allow_player_mode_choice, default_mode] properties: id: {type: string, minLength: 1, maxLength: 100} name: {type: string, minLength: 1, maxLength: 64} icon: {$ref: "#/components/schemas/HouseMethodIcon"} logo_data_url: {type: string, maxLength: 22000, description: Validated small PNG or JPEG logo data URL; uploaded images are resized before saving. SVG and external image URLs are not accepted.} enabled: {type: boolean} input: {type: string, maxLength: 2048, description: House receiving link or tag; parsed by the shared smart-input parser.} qr_payload: {type: string, maxLength: 512} allow_player_mode_choice: {type: boolean} default_mode: {$ref: "#/components/schemas/HousePayoutMode"} ParseManualPaymentInputRequest: type: object required: [method, input] properties: method: {"$ref": "#/components/schemas/ManualPaymentInputMethod"} input: {type: string, maxLength: 2048, description: Receiving profile URL, tag, handle or PayPal email. Ordinary surrounding spaces are normalised. PayPal.Me inputs accept bare domains, handles and HTTPS profiles; recognizable misplaced scheme separators and repeated paypal.me prefixes normalize only when there is one valid recipient.} ManualPaymentInputMethod: type: string enum: [cash_app, chime, paypal, venmo, custom] ManualPaymentInput: type: object required: [method, tag, payment_link, label] properties: method: {$ref: '#/components/schemas/ManualPaymentInputMethod'} tag: {type: string} payment_link: {type: string} label: {type: string} BonusSchemeReadinessPreviewRequest: type: object additionalProperties: false required: [status, overrides] properties: scheme_id: {type: string, format: uuid, description: Existing scheme whose current enrolments are used. Omit for a new scheme.} status: {$ref: "#/components/schemas/BonusSchemeStatus"} starts_on: {type: string, format: date} ends_on: {type: string, format: date} overrides: {$ref: "#/components/schemas/BonusRuleOverrides"} AdminSettingsReadinessPreviewRequest: type: object additionalProperties: false description: Supply exactly one settings group. Versions and audit fields are not mutated by preview. properties: credit_moves: type: object required: [enabled] properties: enabled: {type: boolean} withdrawal_review: type: object required: [require_review, review_unrecorded_credits] properties: require_review: {type: boolean} review_unrecorded_credits: {type: boolean} risk: {$ref: "#/components/schemas/AdminRiskPolicyConfig"} payout: {$ref: "#/components/schemas/ReadinessPayoutSettings"} nowpayments: type: object required: [automatic_enabled, auto_approval_enabled] properties: automatic_enabled: {type: boolean} auto_approval_enabled: {type: boolean} campaign: {$ref: "#/components/schemas/CreateRewardCampaignRequest"} campaign_enabled: {type: boolean, description: Used with campaign; creation defaults to off.} contacts: {$ref: "#/components/schemas/UpdateSupportContactLinksRequest"} game_link: type: object required: [game_id, state] properties: game_id: {type: string} state: {$ref: "#/components/schemas/GameLaunchFallbackRevisionState"} fallback_url: {type: string} provider_access: type: object required: [provider_code, mode] properties: provider_code: {$ref: "#/components/schemas/ProviderCode"} mode: {$ref: "#/components/schemas/ProviderAPIAccessMode"} provider_panel: type: object required: [kind, provider_code, action] properties: kind: {$ref: "#/components/schemas/ProviderPanelLinkKind"} provider_code: {type: string} action: {$ref: "#/components/schemas/ProviderPanelLinkAction"} url: {type: string} provider_reads: type: object required: [provider_code, read_interval_hours] properties: provider_code: {$ref: "#/components/schemas/ProviderCode"} read_interval_hours: {type: integer, format: int32} provider_refill: type: object required: [provider_code, refill_below_credits, warn_if_no_refill_within_hours] properties: provider_code: {$ref: "#/components/schemas/ProviderCode"} refill_below_credits: {type: integer, format: int64} warn_if_no_refill_within_hours: {type: integer, format: int32, nullable: true} alerts: {$ref: "#/components/schemas/AdminExternalNotificationRecipientCreate"} telegram: type: object properties: recipient_id: {type: string, format: uuid} username: {type: string} token_change: {type: boolean, description: No token is sent to the readiness endpoint. Proposed tokens remain unverified until the existing save verifies them.} recent_wins: type: object required: [threshold_cents, window_days, feed_size] properties: threshold_cents: {type: integer, format: int64} window_days: {type: integer} feed_size: {type: integer} ReadinessPayoutSettings: type: object required: [block_withdrawable_loads, freeplay_min_cash_threshold, inapp_signup_freeplay_cents, freeplay_winnings_percent, tiers, maximum_base_cap_cents, excess_percent, minimum_load_multiplier] properties: bonus_only_enabled: {type: boolean} bonus_only_min_net_winnings_cents: {type: integer, format: int64} bonus_only_max_payout_cents: {type: integer, format: int64} bonus_only_winnings_percent: {type: integer, format: int64} bonus_only_cycle_interval_days: {type: integer, format: int64} bonus_only_principal_multiplier: {type: integer, format: int64} deposit_bonus_load_share_enabled: {type: boolean} deposit_bonus_load_share_bps: {type: integer, format: int64} block_withdrawable_loads: {type: boolean} freeplay_min_cash_threshold: {type: integer, format: int64} inapp_signup_freeplay_cents: {type: integer, format: int64} signup_freeplay_cents: {type: integer, format: int64} freeplay_winnings_percent: {type: integer, format: int64} tiers: {type: array, items: {$ref: "#/components/schemas/PayoutTier"}} maximum_base_cap_cents: {type: integer, format: int64} excess_percent: {type: integer, format: int64} minimum_load_multiplier: {type: integer, format: int64} SettingsReadiness: type: object description: Effective configuration state, evaluated by the same backend rules used by players. Live does not guarantee an individual player qualifies or that a provider call will succeed. required: [live, because] properties: live: {type: boolean} because: type: array items: {type: string} fix_hints: type: array items: type: object required: [field, label] properties: field: {type: string, description: Stable field key within this settings editor.} label: {type: string} SettingsReadinessMap: type: object additionalProperties: {$ref: "#/components/schemas/SettingsReadiness"} PaymentSettingsReadinessPreviewRequest: type: object additionalProperties: false required: [manual_policy] properties: manual_policy: {$ref: "#/components/schemas/ManualPaymentClaimPolicyInput"} rules: type: array items: {$ref: "#/components/schemas/UpdateAdminDepositRoutingRule"} PlayerDepositMethodId: type: string minLength: 1 maxLength: 43 description: A routed method kind or a configured house method ID. PlayerDepositMethodVisibility: type: object required: [revision, methods] properties: revision: {type: integer, format: int64, minimum: 0} methods: type: array items: "$ref": "#/components/schemas/PlayerDepositMethodVisibilityItem" last_change: "$ref": "#/components/schemas/PlayerDepositMethodVisibilityChange" PlayerDepositMethodVisibilityItem: type: object required: [id, configured, hidden] properties: id: "$ref": "#/components/schemas/PlayerDepositMethodId" custom_name: {type: string, maxLength: 64} configured: {type: boolean} hidden: {type: boolean} PlayerDepositMethodVisibilityChange: type: object required: [actor_id, actor_label, changed_at] properties: actor_id: {type: string, format: uuid} actor_label: {type: string} changed_at: {type: string, format: date-time} UpdatePlayerDepositMethodVisibility: type: object required: [expected_revision, hidden_methods] properties: expected_revision: {type: integer, format: int64, minimum: 0} hidden_methods: type: array uniqueItems: true maxItems: 30 items: "$ref": "#/components/schemas/PlayerDepositMethodId" ManualPaymentClaimPolicy: type: object required: [cash_app_payment_link, chime_payment_link, paypal_payment_link, method_display_order, payout_methods, additional_deposit_methods, allow_tips, cash_app_rounding, chime_rounding, paypal_rounding, cash_app_qr_payload, chime_qr_payload, paypal_qr_payload, enabled_methods, version, withdrawal_minimum_cents, cash_app_tag, chime_tag, paypal_email] properties: readiness: {$ref: "#/components/schemas/SettingsReadinessMap", readOnly: true} minimum_paid_cents: {type: integer, format: int64, minimum: 1, readOnly: true, description: Minimum paid amount for a manual deposit claim.} method_display_order: {"$ref": "#/components/schemas/PaymentMethodDisplayOrder"} payout_methods: type: array maxItems: 24 items: {"$ref": "#/components/schemas/HousePayoutMethod"} additional_deposit_methods: type: array maxItems: 21 items: {"$ref": "#/components/schemas/HouseDepositMethod"} withdrawal_minimum_cents: {type: integer, format: int64, minimum: 0, maximum: 100000000} cash_app_tag: {type: string, maxLength: 21} chime_tag: {type: string, maxLength: 64} paypal_email: {type: string, maxLength: 254, description: House PayPal email or PayPal.Me handle/link.} cash_app_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: HTTPS Cash App receiving profile link.} cash_app_input: {type: string, maxLength: 2048, description: Optional smart input on replacement; server parses and stores the tag and link.} chime_input: {type: string, maxLength: 2048, description: Optional smart receiving link or ChimeSign.} paypal_input: {type: string, maxLength: 2048, description: Optional smart receiving link, handle or PayPal email.} chime_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on chime.com or chime.me (including subdomains); credentials and nonstandard ports prohibited.} paypal_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on paypal.me or paypal.com (including subdomains); credentials and nonstandard ports prohibited.} allow_tips: {type: boolean, default: true, description: Allow optional tips on manual cash-out.} cash_app_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} chime_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} paypal_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} cash_app_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} chime_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} paypal_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} enabled_methods: type: array items: {"$ref": "#/components/schemas/ManualPaymentClaimMethod"} version: {type: integer, format: int64, minimum: 0} ManualPaymentClaimPolicyInput: type: object additionalProperties: false required: [cash_app_payment_link, chime_payment_link, paypal_payment_link, method_display_order, payout_methods, additional_deposit_methods, allow_tips, cash_app_rounding, chime_rounding, paypal_rounding, cash_app_qr_payload, chime_qr_payload, paypal_qr_payload, enabled_methods, version, withdrawal_minimum_cents, cash_app_tag, chime_tag, paypal_email] properties: method_display_order: {"$ref": "#/components/schemas/PaymentMethodDisplayOrder"} payout_methods: type: array maxItems: 24 items: {"$ref": "#/components/schemas/HousePayoutMethodInput"} additional_deposit_methods: type: array maxItems: 21 items: {"$ref": "#/components/schemas/HouseDepositMethodInput"} withdrawal_minimum_cents: {type: integer, format: int64, minimum: 0, maximum: 100000000} cash_app_tag: {type: string, maxLength: 21} chime_tag: {type: string, maxLength: 64} paypal_email: {type: string, maxLength: 254, description: House PayPal email or PayPal.Me handle/link.} cash_app_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: HTTPS Cash App receiving profile link.} cash_app_input: {type: string, maxLength: 2048, description: Optional smart input on replacement; server parses and stores the tag and link.} chime_input: {type: string, maxLength: 2048, description: Optional smart receiving link or ChimeSign.} paypal_input: {type: string, maxLength: 2048, description: Optional smart receiving link, handle or PayPal email.} chime_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on chime.com or chime.me (including subdomains); credentials and nonstandard ports prohibited.} paypal_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on paypal.me or paypal.com (including subdomains); credentials and nonstandard ports prohibited.} allow_tips: {type: boolean, default: true, description: Allow optional tips on manual cash-out.} cash_app_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} chime_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} paypal_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} cash_app_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} chime_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} paypal_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} enabled_methods: type: array items: {"$ref": "#/components/schemas/ManualPaymentClaimMethod"} version: {type: integer, format: int64, minimum: 0} UpdateManualPaymentClaimPolicyRequest: type: object additionalProperties: false required: [cash_app_payment_link, chime_payment_link, paypal_payment_link, method_display_order, payout_methods, additional_deposit_methods, allow_tips, cash_app_rounding, chime_rounding, paypal_rounding, cash_app_qr_payload, chime_qr_payload, paypal_qr_payload, enabled_methods, version, withdrawal_minimum_cents, cash_app_tag, chime_tag, paypal_email, reason] properties: method_display_order: {"$ref": "#/components/schemas/PaymentMethodDisplayOrder"} payout_methods: type: array maxItems: 24 items: {"$ref": "#/components/schemas/HousePayoutMethodInput"} additional_deposit_methods: type: array maxItems: 21 items: {"$ref": "#/components/schemas/HouseDepositMethodInput"} withdrawal_minimum_cents: {type: integer, format: int64, minimum: 0, maximum: 100000000} cash_app_tag: {type: string, maxLength: 21} chime_tag: {type: string, maxLength: 64} paypal_email: {type: string, maxLength: 254, description: House PayPal email or PayPal.Me handle/link.} cash_app_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: HTTPS Cash App receiving profile link.} cash_app_input: {type: string, maxLength: 2048, description: Optional smart input on replacement; server parses and stores the tag and link.} chime_input: {type: string, maxLength: 2048, description: Optional smart receiving link or ChimeSign.} paypal_input: {type: string, maxLength: 2048, description: Optional smart receiving link, handle or PayPal email.} chime_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on chime.com or chime.me (including subdomains); credentials and nonstandard ports prohibited.} paypal_payment_link: {x-go-type: "*string", type: string, maxLength: 2048, default: "", description: Optional HTTPS house payment link on paypal.me or paypal.com (including subdomains); credentials and nonstandard ports prohibited.} allow_tips: {type: boolean, default: true, description: Allow optional tips on manual cash-out.} cash_app_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} chime_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} paypal_rounding: {"$ref": "#/components/schemas/ManualPaymentClaimRounding"} cash_app_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} chime_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} paypal_qr_payload: {type: string, maxLength: 512, description: Optional QR text payload (up to 512 UTF-8 bytes); HTTPS payment link or cashapp/paypal/chime payment URI.} enabled_methods: type: array items: {"$ref": "#/components/schemas/ManualPaymentClaimMethod"} version: {type: integer, format: int64, minimum: 0} reason: {type: string, minLength: 3, maxLength: 500} CreateManualPaymentClaimRequest: type: object required: [method, paid_cents, receipt_attachment_id, payer_tag] properties: receipt_attachment_id: {type: string, format: uuid, description: Existing Support screenshot reservation, bound atomically to this request.} payer_tag: {type: string, minLength: 1, maxLength: 200, description: The player's own payment tag the money was sent from.} method: {"$ref": "#/components/schemas/ManualDepositClaimMethodId"} paid_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} note: {type: string, maxLength: 2000} DecideManualPaymentClaimRequest: type: object required: [decision] properties: decision: {type: string, enum: [approve, reject], x-enum-varnames: [ManualClaimDecisionApprove, ManualClaimDecisionReject]} credit_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} reason: {type: string, maxLength: 500, description: Required for rejection.} ManualPaymentClaimList: type: object required: [claims] properties: claims: type: array items: {"$ref": "#/components/schemas/ManualPaymentClaim"} AdminManualPaymentClaimList: allOf: - "$ref": "#/components/schemas/ManualPaymentClaimList" - type: object properties: receipt_matches: description: Earlier claims matching the uploaded receipt images. Only included in staff reads. type: array items: {"$ref": "#/components/schemas/ManualReceiptClaimMatch"} ManualPaymentClaimStatus: type: string enum: [pending, approved, rejected] x-enum-varnames: [ManualClaimPending, ManualClaimApproved, ManualClaimRejected] x-go-type: payments.ManualClaimStatus x-go-type-import: {path: codeberg.org/hemanta212/playgo/api/payments} ManualReceiptClaimMatch: type: object required: [claim_id, paid_cents, status, created_at] properties: claim_id: {type: string, format: uuid, description: The claim in this list for which staff should see the receipt caption.} paid_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000, description: Amount reported on the earlier claim.} status: {"$ref": "#/components/schemas/ManualPaymentClaimStatus"} created_at: {type: string, format: date-time, description: When the earlier claim was submitted.} ManualPaymentClaim: type: object required: [id, conversation_id, user_id, method, paid_cents, suggested_credit_cents, note, status, reason, created_at] properties: receipt_attachment_id: {type: string, format: uuid, description: Existing Support screenshot reservation, bound atomically to this request.} id: {type: string, format: uuid} conversation_id: {type: string, format: uuid} user_id: {type: string, format: uuid} method: {"$ref": "#/components/schemas/ManualDepositClaimMethodId"} method_name: {type: string, readOnly: true, description: Receiving method display name captured when the claim was accepted.} payer_tag: {type: string, readOnly: true, description: The player's payment tag the money was sent from; absent on claims made before 2026-11-17.} paid_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} suggested_credit_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} round_up_cents: {type: integer, format: int64, minimum: 0, maximum: 100000000, description: Recorded house-funded difference from the exact paid receipt.} credit_cents: {type: integer, format: int64, minimum: 1, maximum: 100000000} note: {type: string} status: {"$ref": "#/components/schemas/ManualPaymentClaimStatus"} reason: {type: string} payment_id: {type: string, format: uuid} decided_by_label: {type: string, description: Display label of the staff member who reviewed the claim.} decided_by: {type: string, format: uuid} decided_at: {type: string, format: date-time} created_at: {type: string, format: date-time} AdminPaymentVendor: type: object required: [code, display_name, balance_supported] properties: code: {type: string} display_name: {type: string} balance_supported: {type: boolean} panel_url: {type: string, format: uri} AdminPaymentVendorsResponse: type: object required: [providers] properties: providers: type: array items: {"$ref": "#/components/schemas/AdminPaymentVendor"} PaymentProviderBalanceAmount: type: object required: [currency, kind] description: USD observations use amount_cents exclusively. Other assets use units and decimal_places exclusively. Each observation has one exact value; there is no conversion or rounding. properties: currency: {type: string} kind: type: string enum: [available, pending, total, delayed, on_hold] x-enum-varnames: [PaymentBalanceAvailable, PaymentBalancePending, PaymentBalanceTotal, PaymentBalanceDelayed, PaymentBalanceOnHold] amount_cents: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991, description: Required for USD; an exact whole-cent balance, absent for other assets.} units: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991, description: Required for crypto or other non-USD assets; exact integer coefficient, absent for USD.} decimal_places: {type: integer, minimum: 0, maximum: 18, description: Required with non-USD units; absent for USD.} AdminPaymentProviderBalance: type: object required: [provider_code, state, checked_at, cached_until, amounts] properties: provider_code: {type: string} state: type: string enum: [ready, unavailable] x-enum-varnames: [PaymentBalanceReady, PaymentBalanceUnavailable] checked_at: {type: string, format: date-time, description: Completion time of the vendor attempt, unchanged on cache hits.} as_of: {type: string, format: date-time, description: When the successful observation completed; absent on failure.} cached_until: {type: string, format: date-time} reason: type: string enum: [timeout, authentication, invalid_response, provider_unavailable] x-enum-varnames: [PaymentBalanceTimeout, PaymentBalanceAuthentication, PaymentBalanceInvalidResponse, PaymentBalanceProviderUnavailable] amounts: type: array items: {"$ref": "#/components/schemas/PaymentProviderBalanceAmount"}