openapi: 3.1.0
info:
  title: Casino connector
  version: "2.0"
  description: >
    The API a casino exposes so support agents can see a player and approve
    redemptions. Only GET /players/{id} is required; the rest can come later,
    and until they exist those panels are simply empty.

    Version 2 adds optional player actions (search, notes, block/unblock,
    responsible-play break, GC/SC adjustments, resending emails, a timeline)
    and optional fields on the profile. Each v2 write carries an
    `idempotency-key: crm-<action>-<uuid>` header and a JSON body whose `by`
    is the agent's display name. Pryzr Engage only calls a write when the agent
    holds the matching right for that casino, and caps adjustments at
    +/-10,000 SC or +/-10,000,000 GC per call before calling you.

    The provisioning API that a launcher calls ON Pryzr Engage (create a casino,
    invite agents) is documented separately at /docs#provisioning.

    Generate a server stub from this file, point the portal at its base URL, then
    press "Check the connection" in the owner portal to see exactly what is
    missing.

    The `webhooks` section below describes the other direction: what Pryzr
    Engage POSTs to you. That endpoint is configured in the owner portal, not
    here, and it may live on a completely different host.
servers:
  - url: https://api.yourcasino.com/crm
    description: Whatever base URL you enter in the portal
security:
  - bearerAuth: []
paths:
  /players/{id}:
    get:
      summary: One player, with balances (required)
      operationId: getPlayer
      parameters:
        - $ref: "#/components/parameters/PlayerId"
      responses:
        "200":
          description: The player
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlayerProfile" }
        "404": { $ref: "#/components/responses/NotFound" }
  /players/{id}/redemptions:
    get:
      summary: Recent redemptions (optional, needed for approvals)
      operationId: listRedemptions
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/Redemption" }
  /players/{id}/redemptions/{redemptionId}/approve:
    post:
      summary: Approve one pending redemption (optional)
      operationId: approveRedemption
      description: >
        Must be idempotent: we send an idempotency-key header and may retry.
        Return 409 if it is no longer pending.
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - name: redemptionId
          in: path
          required: true
          schema: { type: string }
        - name: idempotency-key
          in: header
          required: false
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                approved_by:
                  type: string
                  description: The agent's name, for your own audit trail
      responses:
        "200": { description: Approved }
        "409": { description: Already approved, paid, rejected or cancelled }
  /players/{id}/transactions:
    get:
      summary: Recent purchases, bonuses and adjustments (optional)
      operationId: listTransactions
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/Transaction" }
  /players/{id}/games:
    get:
      summary: Recent game rounds (optional)
      operationId: listGames
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/GameRound" }
  /players/search:
    get:
      summary: Find players by name, email or id (v2, optional)
      operationId: searchPlayers
      description: Powers the inbox's player search. At most 20 results.
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 2 }
      responses:
        "200":
          description: Matches, best first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    maxItems: 20
                    items: { $ref: "#/components/schemas/PlayerHit" }
  /players/{id}/notes:
    get:
      summary: Staff notes, newest first (v2, optional)
      operationId: listNotes
      parameters:
        - $ref: "#/components/parameters/PlayerId"
      responses:
        "200":
          description: Newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/PlayerNote" }
    post:
      summary: Add a staff note (v2, optional)
      operationId: addNote
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text, by]
              properties:
                text: { type: string, maxLength: 2000 }
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Saved }
  /players/{id}/block:
    post:
      summary: Block the account (v2, optional)
      operationId: blockPlayer
      description: No play, buy or redeem until unblocked.
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason, by]
              properties:
                reason: { type: string, maxLength: 500 }
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Blocked }
  /players/{id}/unblock:
    post:
      summary: Lift a block (v2, optional)
      operationId: unblockPlayer
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [by]
              properties:
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Unblocked }
  /players/{id}/break:
    post:
      summary: Responsible-play break (v2, optional)
      operationId: givePlayerBreak
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [days, by]
              properties:
                days: { type: integer, minimum: 1, maximum: 90 }
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Break set }
  /players/{id}/adjust:
    post:
      summary: Ledger adjustment in coins (v2, optional)
      operationId: adjustBalance
      description: >
        Signed amount in coins. Engage refuses more than +/-10,000 SC or
        +/-10,000,000 GC per call before it reaches you; re-check on your side
        and log it against `by`.
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [currency, amount, reason, by]
              properties:
                currency: { type: string, enum: [GC, SC] }
                amount: { type: number, description: Positive adds coins, negative takes them away. Never zero. }
                reason: { type: string, maxLength: 500 }
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Posted }
        "409": { description: Would take the balance below zero, or the account is closed }
  /players/{id}/email:
    post:
      summary: Resend an account email (v2, optional)
      operationId: resendEmail
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template, by]
              properties:
                template: { type: string, enum: [verify, w9, reset] }
                by: { $ref: "#/components/schemas/By" }
      responses:
        "200": { description: Sent }
  /players/{id}/timeline:
    get:
      summary: Account timeline, newest first (v2, optional)
      operationId: playerTimeline
      description: Purchases, redemptions, adjustments, blocks, notes and KYC changes.
      parameters:
        - $ref: "#/components/parameters/PlayerId"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/TimelineItem" }
webhooks:
  engageEvent:
    post:
      summary: An event from Pryzr Engage
      description: >
        Pryzr Engage POSTs here when something happens in this casino's chat.
        The address is set per casino in the owner portal, typically one path
        per tenant, e.g. /api/v1/pryzr/webhooks/{casino_slug}.

        Answer with any 2xx; the body is ignored, so an empty 200 is ideal.
        Anything else, including a timeout after 8 seconds, is a failure and is
        retried at 1, 2, 4, 8 and 16 minutes, six attempts in total.

        Delivery is at least once and NOT ordered: use `occurred_at`, never
        arrival order. Make the handler idempotent.

        Bodies never contain message text.
      operationId: receiveEngageEvent
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EngageEvent" }
            examples:
              chatWaiting:
                summary: A player is waiting and nobody has the inbox open
                value:
                  event: chat.waiting
                  occurred_at: "2026-01-31T14:02:11Z"
                  casino_slug: lucky-reef
                  conversation_id: 3f7c9a12-1f4e-4a55-9d2e-0b6f8c1d7e40
                  player_id: player-123
                  waiting_since: "2026-01-31T13:58:40Z"
                  waiting_minutes: 3
              chatStarted:
                summary: A new conversation
                value:
                  event: chat.started
                  occurred_at: "2026-01-31T13:58:40Z"
                  casino_slug: lucky-reef
                  conversation_id: 3f7c9a12-1f4e-4a55-9d2e-0b6f8c1d7e40
                  player_id: player-123
                  identified: true
              redemptionApproved:
                summary: An agent approved a redemption
                value:
                  event: redemption.approved
                  occurred_at: "2026-01-31T14:10:02Z"
                  casino_slug: lucky-reef
                  conversation_id: 3f7c9a12-1f4e-4a55-9d2e-0b6f8c1d7e40
                  player_id: player-123
                  redemption_id: RD-1040
                  amount: 325
                  currency: USD
                  approved_by: Sam C.
      responses:
        "200":
          description: Accepted. Any 2xx works and the body is ignored.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "The API key you paste into the owner portal, sent as `authorization: Bearer <key>`."
    basicAuth:
      type: http
      scheme: basic
      description: >
        Optional HTTP Basic credentials for the webhook endpoint. The user and
        password are entered in the owner portal and sent on every delivery.
  parameters:
    PlayerId:
      name: id
      in: path
      required: true
      description: Your own player id, the same one you put in the chat token as "sub".
      schema: { type: string }
    Limit:
      name: limit
      in: query
      required: false
      schema: { type: integer, default: 25, maximum: 100 }
    IdempotencyKey:
      name: idempotency-key
      in: header
      required: false
      description: "`crm-<action>-<uuid>`, fresh per attempt. Treat a repeated key as the same request."
      schema: { type: string }
  responses:
    NotFound:
      description: No such player
  schemas:
    Balances:
      type: object
      required: [gold_coins, sweeps_coins, redeemable_sc]
      properties:
        gold_coins: { type: number, description: Play-money coins }
        sweeps_coins: { type: number }
        redeemable_sc: { type: number, description: The part that can be redeemed today }
    PlayerProfile:
      type: object
      required: [id, status, kyc_status, balances]
      properties:
        id: { type: string }
        name: { type: [string, "null"] }
        email: { type: [string, "null"] }
        status: { type: string, examples: [active, closed, self-excluded] }
        kyc_status: { type: string, examples: ["verified", "pending review", "not started"] }
        joined_at: { type: [string, "null"], format: date-time }
        last_login_at: { type: [string, "null"], format: date-time }
        state: { type: [string, "null"], description: US state code }
        balances: { $ref: "#/components/schemas/Balances" }
        lifetime:
          type: object
          properties:
            purchases_usd: { type: number }
            redeemed_usd: { type: number }
        # ---- v2, all optional ----
        phone: { type: [string, "null"] }
        vip_level: { type: [integer, "null"] }
        flags:
          type: [object, "null"]
          properties:
            blocked: { type: boolean }
            block_reason: { type: [string, "null"] }
            self_excluded_until: { type: [string, "null"], format: date-time }
            on_break_until: { type: [string, "null"], format: date-time }
            kyc_note: { type: [string, "null"] }
        limits:
          type: [object, "null"]
          properties:
            daily_usd: { type: [number, "null"] }
            weekly_usd: { type: [number, "null"] }
            monthly_usd: { type: [number, "null"] }
        tax:
          type: [object, "null"]
          properties:
            w9_status: { type: string, enum: [none, requested, on_file] }
            ytd_prizes_usd: { type: number }
        notes_count: { type: [integer, "null"] }
        tags:
          type: [array, "null"]
          items: { type: string }
    By:
      type: string
      description: The agent's display name, for your own audit trail. Log every write as engage:<by>.
    PlayerHit:
      type: object
      required: [id]
      properties:
        id: { type: string }
        name: { type: [string, "null"] }
        email: { type: [string, "null"] }
        status: { type: [string, "null"] }
    PlayerNote:
      type: object
      required: [id, text, created_at]
      properties:
        id: { type: string }
        text: { type: string }
        by: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
    TimelineItem:
      type: object
      required: [at, kind, summary]
      properties:
        at: { type: string, format: date-time }
        kind: { type: string, examples: [purchase, redemption, adjustment, block, note, kyc] }
        summary: { type: string }
    Redemption:
      type: object
      required: [id, amount, status, requested_at]
      properties:
        id: { type: string }
        amount: { type: number }
        currency: { type: string, default: USD }
        sweeps_coins: { type: number }
        method: { type: string, examples: ["ACH bank transfer", "Skrill", "Gift card"] }
        status:
          type: string
          enum: [pending, approved, paid, rejected, cancelled]
        requested_at: { type: string, format: date-time }
        processed_at: { type: [string, "null"], format: date-time }
        note: { type: [string, "null"], description: Anything an agent should know }
    Transaction:
      type: object
      required: [id, type, status, created_at]
      properties:
        id: { type: string }
        type:
          type: string
          enum: [purchase, bonus, redemption, adjustment]
        description: { type: string }
        amount_usd: { type: [number, "null"] }
        gold_coins: { type: number }
        sweeps_coins: { type: number }
        status: { type: string }
        method: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
    GameRound:
      type: object
      required: [id, game, currency, wager, win, played_at]
      properties:
        id: { type: string }
        game: { type: string }
        provider: { type: string }
        currency: { type: string, enum: [GC, SC] }
        wager: { type: number }
        win: { type: number }
        played_at: { type: string, format: date-time }
    EngageEvent:
      type: object
      description: >
        One webhook body. Every event carries event, occurred_at, casino_slug
        and conversation_id; the remaining fields depend on the event.
      required: [event, occurred_at, casino_slug]
      properties:
        event:
          type: string
          enum:
            - chat.started
            - chat.waiting
            - chat.resolved
            - redemption.approved
            - webhook.test
        occurred_at:
          type: string
          format: date-time
          description: UTC, ISO 8601. Use this for ordering, not arrival time.
        casino_slug:
          type: string
          description: Which casino this happened in.
        conversation_id:
          type: string
          format: uuid
          description: Absent on webhook.test.
        player_id:
          type: [string, "null"]
          description: Your own player id, the same value you signed as "sub". Null for a guest.
        identified:
          type: boolean
          description: chat.started only. False when the visitor is a guest.
        waiting_since:
          type: string
          format: date-time
          description: chat.waiting only. When the unanswered message arrived.
        waiting_minutes:
          type: integer
          description: chat.waiting only.
        messages:
          type: integer
          description: chat.resolved only. How many messages the conversation ended with.
        opened_at:
          type: string
          format: date-time
          description: chat.resolved only.
        redemption_id:
          type: string
          description: redemption.approved only. Your own redemption id.
        amount:
          type: [number, "null"]
          description: redemption.approved only.
        currency:
          type: string
          description: redemption.approved only. Defaults to USD.
        approved_by:
          type: [string, "null"]
          description: redemption.approved only. The agent's display name.
        message:
          type: string
          description: webhook.test only. Human-readable note that this was a test.
