{
  "openapi": "3.1.0",
  "info": {
    "title": "Baccarat Live Platform · B2B Operator Seamless Wallet OpenAPI",
    "version": "1.0.0",
    "summary": "Server-to-Server (S2S) Game Launch, Table Discovery, Session Termination, Transaction Reconciliation, and Outbound Seamless Wallet Webhook Specification (C01).",
    "description": "Official B2B Operator S2S & Single Seamless Wallet API for **Baccarat Live Platform**.\n\n### Key Protocol Invariants\n1. **Dual-Header HMAC-SHA256 Authentication**: Both inbound `/operator/v1/*` requests and outbound `{callbackUrl}/wallet/*` webhooks carry `X-API-Key` and `X-Signature` (`64-char lowercase hex` HMAC-SHA256 computed over the **exact raw UTF-8 JSON request body bytes**).\n2. **HTTP 200 Protocol Envelope**: Inbound `/operator/v1/*` endpoints return `HTTP 200` with `{ traceId, status, data? }` on success (`status = \"SC_OK\"`) or `{ traceId, status, message, validation? }` on protocol/business rejections.\n3. **Exact Decimal Strings**: Outbound monetary amounts (`amount`, `betAmount`, `winAmount`, `winLoss`, `effectiveTurnover`) are transmitted as exact Decimal strings scaled to the currency `displayExponent` (e.g. `\"100.00\"` for `USD`). Operator wallet responses return `data.balance` as a Decimal string (recommended) or finite JSON number.\n4. **Strict Idempotency**: Outbound wallet webhooks use deterministic `transactionId` keys (`bet_<32hex>`, `stl_<32hex>`, `rb_<ticketId>`, `late_<betTxId>`). Replays with identical payload **must not** double-deduct or double-credit, and **must** return `HTTP 200` with `status: \"SC_OK\"` and current `data.balance`.",
    "contact": {
      "name": "1Bit Live Platform Integration Engineering",
      "url": "https://openapi.lt.cniia.cloud"
    }
  },
  "servers": [
    {
      "url": "https://api.lt.cniia.cloud",
      "description": "Dev / Sandbox Environment (24x7 Live Studio Table T-A2 & Demo Table T-A1)"
    },
    {
      "url": "https://{apiHost}",
      "description": "Dedicated Production / Regional S2S Gateway",
      "variables": {
        "apiHost": {
          "default": "api.lt.cniia.cloud",
          "description": "Provisioned S2S API hostname assigned during commercial onboarding"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Game & Session (Inbound S2S)",
      "description": "Operator -> Platform endpoints under `/operator/v1/game/*` for player table launch, live table catalog, and session revocation."
    },
    {
      "name": "Reconciliation (Inbound S2S)",
      "description": "Operator -> Platform endpoints under `/operator/v1/transaction/*` for settled ticket feeds and single-ticket card result inspection."
    },
    {
      "name": "Seamless Wallet Webhooks (Outbound)",
      "description": "Platform -> Operator callbacks under `{callbackUrl}/wallet/*` that the integrating operator must host and sign-verify."
    }
  ],
  "security": [
    {
      "OperatorApiKey": [],
      "OperatorHmacSignature": []
    }
  ],
  "paths": {
    "/operator/v1/game/url": {
      "post": {
        "tags": [
          "Game & Session (Inbound S2S)"
        ],
        "operationId": "createGameUrl",
        "summary": "Issue one-time player launch URL & wallet session token",
        "description": "Validates operator table/currency permissions and responsible-gaming status, performs a synchronous pre-launch `POST {callbackUrl}/wallet/balance` probe with the newly minted `b2bt_` token, persists the single-use launch token (default TTL 900s), and returns the H5/Web launch URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGameUrlRequest"
              },
              "examples": {
                "launchStudioTable": {
                  "summary": "Launch 24x7 Live Studio Table T-A2",
                  "value": {
                    "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
                    "username": "player_9527",
                    "tableId": "T-A2",
                    "language": "zh-CN",
                    "platform": "H5",
                    "currency": "USD",
                    "lobbyUrl": "https://merchant.example.com/lobby",
                    "ipAddress": "203.0.113.42"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Protocol envelope (`SC_OK` on success, or `SC_*` error status with `message` / `validation`).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CreateGameUrlSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Launch URL issued (SC_OK)",
                    "value": {
                      "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
                      "status": "SC_OK",
                      "data": {
                        "gameUrl": "https://play.lt.cniia.cloud/?token=b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819&tableId=T-A2&lang=zh-CN",
                        "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819"
                      }
                    }
                  },
                  "validationError": {
                    "summary": "Invalid parameters (SC_INVALID_REQUEST)",
                    "value": {
                      "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
                      "status": "SC_INVALID_REQUEST",
                      "message": "Wrong/missing parameters sent in request body.",
                      "validation": {
                        "platform": "Platform is not supported (expected web | H5)."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/operator/v1/game/tables": {
      "post": {
        "tags": [
          "Game & Session (Inbound S2S)"
        ],
        "operationId": "listTables",
        "summary": "List permitted live tables & dynamic betting limits",
        "description": "Returns paginated configured/suspended tables permitted for the authenticated operator, including effective `minBet`, `maxBet` (intersected with table override, global cap, FX benchmark, and operator risk limit template), `chipUnit`, and cover image URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListTablesRequest"
              },
              "examples": {
                "allUsdTables": {
                  "summary": "Query USD tables",
                  "value": {
                    "traceId": "7f19b4a2-3d10-4c9a-9e21-5518a0c21101",
                    "currency": "USD",
                    "pageNo": 1,
                    "pageSize": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paginated table catalog (`SC_OK`) or protocol error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ListTablesSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Table list response (SC_OK)",
                    "value": {
                      "traceId": "7f19b4a2-3d10-4c9a-9e21-5518a0c21101",
                      "status": "SC_OK",
                      "data": {
                        "tables": [
                          {
                            "tableId": "T-A2",
                            "gameCode": "BACCARAT_T-A2",
                            "tableName": "Studio VIP Baccarat A2",
                            "gameType": "BACCARAT",
                            "currency": "USD",
                            "status": "OPEN",
                            "minBet": "10.00",
                            "maxBet": "5000.00",
                            "chipUnit": "1.00",
                            "languages": [
                              "en",
                              "zh-CN"
                            ],
                            "platforms": [
                              "web",
                              "H5"
                            ],
                            "coverImageUrl": "https://play.lt.cniia.cloud/player/v1/table-images/4b825dc642cb6eb9a060e54bf8d69288fbee4904f1e2d3c4b5a6978877665544.jpg"
                          }
                        ],
                        "pageNo": 1,
                        "pageSize": 50,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/operator/v1/game/terminate": {
      "post": {
        "tags": [
          "Game & Session (Inbound S2S)"
        ],
        "operationId": "terminateSessions",
        "summary": "Force-terminate player sessions & unused launch tokens",
        "description": "Immediately revokes all active player Web/WS sessions (`revokeReason = \"TERMINATED\"`) and unredeemed `b2b_launch_tokens` for `username` under the calling operator. Already-accepted in-flight bets remain bound to their round and settle or void normally without losing idempotency.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TerminateSessionsRequest"
              },
              "examples": {
                "kickPlayer": {
                  "summary": "Terminate player sessions",
                  "value": {
                    "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
                    "username": "player_9527"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session termination count (`SC_OK`) or `SC_USER_NOT_EXISTS` / error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TerminateSessionsSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Sessions revoked (SC_OK)",
                    "value": {
                      "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
                      "status": "SC_OK",
                      "data": {
                        "username": "player_9527",
                        "terminatedSessions": 1,
                        "revokedLaunchTokens": 0
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/operator/v1/transaction/list": {
      "post": {
        "tags": [
          "Reconciliation (Inbound S2S)"
        ],
        "operationId": "listTransactions",
        "summary": "Paginated settled/voided ticket reconciliation feed",
        "description": "Queries settled/voided tickets belonging to the authenticated operator filtered inclusively by `settledAt` in `[fromTime, toTime]` (epoch milliseconds), ordered deterministically by `(settledAt ASC, ticketId ASC)`. Default `pageSize = 2000`, maximum `20000`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListTransactionsRequest"
              },
              "examples": {
                "hourlyWindow": {
                  "summary": "Fetch 1-hour settlement window",
                  "value": {
                    "traceId": "1a2b3c4d-5e6f-4789-8abc-def012345678",
                    "fromTime": 1763611200000,
                    "toTime": 1763614800000,
                    "pageNo": 1,
                    "pageSize": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paginated reconciliation rows (`SC_OK`) or protocol error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ListTransactionsSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Settled ticket list (SC_OK)",
                    "value": {
                      "traceId": "1a2b3c4d-5e6f-4789-8abc-def012345678",
                      "status": "SC_OK",
                      "data": {
                        "transactions": [
                          {
                            "betId": "cm3p9z1x0000108l47a9g2k1m",
                            "roundId": "cm3p9y0a0000008l4b1122334",
                            "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
                            "username": "player_9527",
                            "currencyCode": "USD",
                            "gameCode": "BACCARAT_T-A2",
                            "betSide": "PLAYER",
                            "betAmount": "100.00",
                            "winAmount": "200.00",
                            "winLoss": "100.00",
                            "effectiveTurnover": "100.00",
                            "status": 1,
                            "vendorBetTime": 1763612010120,
                            "vendorSettleTime": 1763612038450
                          }
                        ],
                        "pageNo": 1,
                        "pageSize": 2000,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/operator/v1/transaction/detail": {
      "post": {
        "tags": [
          "Reconciliation (Inbound S2S)"
        ],
        "operationId": "getTransactionDetail",
        "summary": "Inspect single ticket & verified round card outcome",
        "description": "Looks up a single ticket `betId` within `[fromTime, toTime]` (window **must be `<= 7 days`**, i.e. `604800000` ms). Matches if either `vendorBetTime` or `vendorSettleTime` falls inside `[fromTime, toTime]`, including unsettled (`status = 0`) tickets, and attaches verified `roundResult` points/pairs/natural flags when settled.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionDetailRequest"
              },
              "examples": {
                "lookupTicket": {
                  "summary": "Query single bet ticket within 24h window",
                  "value": {
                    "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                    "betId": "cm3p9z1x0000108l47a9g2k1m",
                    "fromTime": 1763550000000,
                    "toTime": 1763636400000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Single ticket detail with `roundResult` (`SC_OK`) or `SC_TRANSACTION_NOT_EXISTS`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TransactionDetailSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Ticket detail with verified round outcome (SC_OK)",
                    "value": {
                      "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                      "status": "SC_OK",
                      "data": {
                        "betId": "cm3p9z1x0000108l47a9g2k1m",
                        "roundId": "cm3p9y0a0000008l4b1122334",
                        "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
                        "username": "player_9527",
                        "currencyCode": "USD",
                        "gameCode": "BACCARAT_T-A2",
                        "betSide": "PLAYER",
                        "betAmount": "100.00",
                        "winAmount": "200.00",
                        "winLoss": "100.00",
                        "effectiveTurnover": "100.00",
                        "status": 1,
                        "vendorBetTime": 1763612010120,
                        "vendorSettleTime": 1763612038450,
                        "roundResult": {
                          "outcome": "PLAYER",
                          "playerPoints": 8,
                          "bankerPoints": 5,
                          "playerPair": false,
                          "bankerPair": false,
                          "natural": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "walletBalance": {
      "post": {
        "tags": [
          "Seamless Wallet Webhooks (Outbound)"
        ],
        "operationId": "webhookWalletBalance",
        "summary": "POST {callbackUrl}/wallet/balance — Query player available balance",
        "description": "Invoked synchronously during `/operator/v1/game/url` pre-launch check and when the player refreshes wallet balance in the live table UI. Read-only; must never mutate player balance.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletBalanceWebhookRequest"
              },
              "examples": {
                "balanceProbe": {
                  "value": {
                    "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
                    "username": "player_9527",
                    "currency": "USD",
                    "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operator wallet balance response (`SC_OK` + `data.balance`, or rejection status).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/WalletCallbackSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "ok": {
                    "value": {
                      "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
                      "status": "SC_OK",
                      "data": {
                        "username": "player_9527",
                        "currency": "USD",
                        "balance": "1000.00",
                        "timestamp": 1763612005000
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "walletBet": {
      "post": {
        "tags": [
          "Seamless Wallet Webhooks (Outbound)"
        ],
        "operationId": "webhookWalletBet",
        "summary": "POST {callbackUrl}/wallet/bet — Deduct player stake (idempotent by transactionId)",
        "description": "Invoked outside PostgreSQL transactions after risk & betting-window checks pass. Guarded by `opbet:{operatorId}:{transactionId}` (`transactionId = bet_<32hex>`).\n\n- **Idempotent replay**: Same `transactionId` + same payload -> do NOT deduct again; return `HTTP 200` + `status: \"SC_OK\"` + current `data.balance`.\n- **Conflict**: Same `transactionId` + different payload -> return `status: \"SC_TRANSACTION_DUPLICATED\"`.\n- **Insufficient balance**: Return `status: \"SC_INSUFFICIENT_FUNDS\"`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletBetWebhookRequest"
              },
              "examples": {
                "debitBet": {
                  "value": {
                    "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
                    "username": "player_9527",
                    "transactionId": "bet_4a19f08c2e77b3109d44e6128a5bc091",
                    "betId": "cm3p9z1x0000108l47a9g2k1m",
                    "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
                    "amount": "100.00",
                    "currency": "USD",
                    "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
                    "gameCode": "BACCARAT_T-A2",
                    "roundId": "cm3p9y0a0000008l4b1122334",
                    "timestamp": 1763612010120
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated balance after stake deduction (`SC_OK`), or rejection (`SC_INSUFFICIENT_FUNDS`, etc.).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/WalletCallbackSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "ok": {
                    "value": {
                      "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
                      "status": "SC_OK",
                      "data": {
                        "username": "player_9527",
                        "currency": "USD",
                        "balance": "900.00",
                        "timestamp": 1763612010185
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "walletBetResult": {
      "post": {
        "tags": [
          "Seamless Wallet Webhooks (Outbound)"
        ],
        "operationId": "webhookWalletBetResult",
        "summary": "POST {callbackUrl}/wallet/bet_result — Per-ticket settlement payout / loss / push",
        "description": "Invoked per ticket upon verified round settlement. Guarded by `opsettle:{operatorId}:{transactionId}` (`transactionId = stl_<32hex>`).\n\n- **WIN**: `resultType = \"WIN\"`, `winAmount = betAmount + netPayout`, `winLoss = +netPayout`, `effectiveTurnover = betAmount`.\n- **LOSE**: `resultType = \"LOSE\"`, `winAmount = \"0.00\"`, `winLoss = -betAmount`, `effectiveTurnover = betAmount`.\n- **PUSH (Tie refund)**: `resultType = \"WIN\"`, `winAmount = betAmount`, `winLoss = \"0.00\"`, `effectiveTurnover = \"0.00\"`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletBetResultWebhookRequest"
              },
              "examples": {
                "winSettlement": {
                  "summary": "Winning ticket payout (stake 100.00 + net win 100.00 = 200.00)",
                  "value": {
                    "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
                    "username": "player_9527",
                    "transactionId": "stl_90e12d4b7c6a8812f34509ab12cd34ef",
                    "betId": "cm3p9z1x0000108l47a9g2k1m",
                    "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
                    "roundId": "cm3p9y0a0000008l4b1122334",
                    "betAmount": "100.00",
                    "winAmount": "200.00",
                    "effectiveTurnover": "100.00",
                    "winLoss": "100.00",
                    "jackpotAmount": "0.00",
                    "resultType": "WIN",
                    "isFreespin": 0,
                    "isEndRound": 1,
                    "currency": "USD",
                    "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
                    "gameCode": "BACCARAT_T-A2",
                    "betTime": 1763612010120,
                    "settledTime": 1763612038450
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operator acknowledgement with updated player balance (`SC_OK`).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/WalletCallbackSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "ok": {
                    "value": {
                      "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
                      "status": "SC_OK",
                      "data": {
                        "username": "player_9527",
                        "currency": "USD",
                        "balance": "1100.00",
                        "timestamp": 1763612038510
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "walletRollback": {
      "post": {
        "tags": [
          "Seamless Wallet Webhooks (Outbound)"
        ],
        "operationId": "webhookWalletRollback",
        "summary": "POST {callbackUrl}/wallet/rollback — Void refund or late-round-close compensation",
        "description": "Reverses a prior `/wallet/bet` stake for round `VOID`, manual held-ticket void (`rb_<ticketId>`), or late-round-close race compensation (`late_<betTxId>`). Guarded by `oprollback:{operatorId}:{transactionId}`.\n\n- **Empty-Success Rule**: If the original `betId` was never deducted on the operator side, return `SC_TRANSACTION_NOT_EXISTS` (or `SC_OK` without crediting) — the platform converges both to `COMPLETED` empty-success.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletRollbackWebhookRequest"
              },
              "examples": {
                "voidRollback": {
                  "value": {
                    "traceId": "c1094e22-8831-42b7-9901-77a6b5c4d3e2",
                    "username": "player_9527",
                    "transactionId": "rb_cm3p9z1x0000108l47a9g2k1m",
                    "betId": "cm3p9z1x0000108l47a9g2k1m",
                    "externalTransactionId": "cm3p9z1x0000108l47a9g2k1m",
                    "roundId": "cm3p9y0a0000008l4b1122334",
                    "amount": "100.00",
                    "currency": "USD",
                    "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819",
                    "gameCode": "BACCARAT_T-A2",
                    "timestamp": 1763612042000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "`SC_OK` (stake refunded or idempotent replay) or `SC_TRANSACTION_NOT_EXISTS` (original bet never existed -> empty-success).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/WalletCallbackSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OperatorErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "ok": {
                    "value": {
                      "traceId": "c1094e22-8831-42b7-9901-77a6b5c4d3e2",
                      "status": "SC_OK",
                      "data": {
                        "username": "player_9527",
                        "currency": "USD",
                        "balance": "1000.00",
                        "timestamp": 1763612042060
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OperatorApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Operator credential identifier (`ak_<32-hex-chars>`) issued in the Admin / Merchant Console."
      },
      "OperatorHmacSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature",
        "description": "64-character lowercase hexadecimal `HMAC-SHA256(rawJsonBodyBytes, hmacSecret)` computed over the exact UTF-8 bytes of the HTTP request body."
      }
    },
    "parameters": {
      "WebhookApiKeyHeader": {
        "name": "X-API-Key",
        "in": "header",
        "required": true,
        "description": "Operator `apiKey` (`ak_<32-hex-chars>`) identifying the merchant credential.",
        "schema": {
          "type": "string",
          "pattern": "^ak_[0-9a-f]{32}$"
        }
      },
      "WebhookSignatureHeader": {
        "name": "X-Signature",
        "in": "header",
        "required": true,
        "description": "64-char hex `HMAC-SHA256(rawJsonBodyBytes, hmacSecret)` signed by Baccarat Live Platform.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        }
      }
    },
    "schemas": {
      "OperatorStatusCode": {
        "type": "string",
        "enum": [
          "SC_OK",
          "SC_INVALID_REQUEST",
          "SC_AUTHENTICATION_FAILED",
          "SC_INVALID_SIGNATURE",
          "SC_INVALID_TOKEN",
          "SC_INVALID_GAME",
          "SC_USER_NOT_EXISTS",
          "SC_USER_DISABLED",
          "SC_WRONG_CURRENCY",
          "SC_CURRENCY_NOT_SUPPORTED",
          "SC_INSUFFICIENT_FUNDS",
          "SC_TRANSACTION_DUPLICATED",
          "SC_TRANSACTION_NOT_EXISTS",
          "SC_TRANSACTION_STILL_PROCESSING",
          "SC_OPERATOR_TIMEOUT",
          "SC_UNDER_MAINTENANCE",
          "SC_GAME_DISABLED"
        ],
        "description": "Standard B2B S2S & Seamless Wallet status code."
      },
      "DecimalString": {
        "type": "string",
        "pattern": "^-?\\d+(?:\\.\\d+)?$",
        "description": "Exact base-10 Decimal string formatted to the currency `displayExponent` (e.g. `\"100.00\"` for USD, `\"100\"` for JPY). Never uses scientific notation or floating-point rounding.",
        "examples": [
          "100.00"
        ]
      },
      "UnsignedDecimalString": {
        "type": "string",
        "pattern": "^\\d+(?:\\.\\d+)?$",
        "description": "Non-negative exact base-10 Decimal string.",
        "examples": [
          "100.00"
        ]
      },
      "BaccaratBetSide": {
        "type": "string",
        "enum": [
          "PLAYER",
          "BANKER",
          "TIE",
          "P_PAIR",
          "B_PAIR",
          "ANY_PAIR",
          "SUPER_6"
        ],
        "description": "Baccarat bet side code (`PLAYER`, `BANKER`, `TIE` mandatory main bets; `P_PAIR`, `B_PAIR`, `ANY_PAIR`, `SUPER_6` optional ruleset-priced side bets)."
      },
      "BaccaratOutcome": {
        "type": "string",
        "enum": [
          "PLAYER",
          "BANKER",
          "TIE"
        ],
        "description": "Verified main outcome of a settled Baccarat round."
      },
      "ReconcileTicketStatus": {
        "type": "integer",
        "enum": [
          0,
          1,
          2,
          3
        ],
        "description": "Reconciliation status: `0` = Unsettled (ACCEPTED/HELD), `1` = Settled (WIN/LOSE/PUSH), `2` = Cancelled, `3` = Voided/Refunded."
      },
      "CreateGameUrlRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username",
          "tableId",
          "platform",
          "currency",
          "lobbyUrl",
          "ipAddress"
        ],
        "additionalProperties": false,
        "properties": {
          "traceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Unique request trace ID (UUID v4 recommended; not an idempotency key)."
          },
          "username": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Operator-side unique player identifier (mapped per operator to a platform player)."
          },
          "tableId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Target live table ID (e.g. `\"T-A2\"` or `\"T-A1\"`)."
          },
          "language": {
            "type": "string",
            "default": "en",
            "description": "UI locale (`\"en\"` or `\"zh-CN\"`)."
          },
          "platform": {
            "type": "string",
            "enum": [
              "web",
              "H5"
            ],
            "description": "Client form factor (`\"web\"` for desktop, `\"H5\"` for mobile webview)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "3-letter uppercase ISO-4217 / platform currency code matching the table currency."
          },
          "lobbyUrl": {
            "type": "string",
            "format": "uri",
            "description": "Safe `http://` or `https://` return URL when the player exits the table."
          },
          "ipAddress": {
            "type": "string",
            "description": "Player client IPv4 or IPv6 address."
          }
        }
      },
      "CreateGameUrlSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "type": "object",
            "required": [
              "gameUrl",
              "token"
            ],
            "properties": {
              "gameUrl": {
                "type": "string",
                "format": "uri",
                "description": "One-time player launch URL (default 900s TTL for URL exchange)."
              },
              "token": {
                "type": "string",
                "description": "Session wallet token (`b2bt_<48hex>`) echoed on all subsequent `/wallet/*` callbacks."
              }
            }
          }
        }
      },
      "ListTablesRequest": {
        "type": "object",
        "required": [
          "traceId"
        ],
        "additionalProperties": false,
        "properties": {
          "traceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Optional 3-letter currency filter."
          },
          "pageNo": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        }
      },
      "TableCatalogItem": {
        "type": "object",
        "required": [
          "tableId",
          "gameCode",
          "tableName",
          "gameType",
          "currency",
          "status",
          "minBet",
          "maxBet",
          "chipUnit",
          "languages",
          "platforms",
          "coverImageUrl"
        ],
        "properties": {
          "tableId": {
            "type": "string",
            "examples": [
              "T-A2"
            ]
          },
          "gameCode": {
            "type": "string",
            "description": "Canonical `{gameType}_{tableId}` identifier.",
            "examples": [
              "BACCARAT_T-A2"
            ]
          },
          "tableName": {
            "type": "string",
            "examples": [
              "Studio VIP Baccarat A2"
            ]
          },
          "gameType": {
            "type": "string",
            "examples": [
              "BACCARAT"
            ]
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "OPEN",
              "MAINTENANCE"
            ]
          },
          "minBet": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UnsignedDecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "maxBet": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UnsignedDecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "chipUnit": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UnsignedDecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "en",
                "zh-CN"
              ]
            ]
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "web",
                "H5"
              ]
            }
          },
          "coverImageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        }
      },
      "ListTablesSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "type": "object",
            "required": [
              "tables",
              "pageNo",
              "pageSize",
              "total"
            ],
            "properties": {
              "tables": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TableCatalogItem"
                }
              },
              "pageNo": {
                "type": "integer",
                "minimum": 1
              },
              "pageSize": {
                "type": "integer",
                "minimum": 1,
                "maximum": 200
              },
              "total": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      },
      "TerminateSessionsRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username"
        ],
        "additionalProperties": false,
        "properties": {
          "traceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "username": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "TerminateSessionsSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "type": "object",
            "required": [
              "username",
              "terminatedSessions",
              "revokedLaunchTokens"
            ],
            "properties": {
              "username": {
                "type": "string"
              },
              "terminatedSessions": {
                "type": "integer",
                "minimum": 0
              },
              "revokedLaunchTokens": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      },
      "ListTransactionsRequest": {
        "type": "object",
        "required": [
          "traceId",
          "fromTime",
          "toTime"
        ],
        "additionalProperties": false,
        "properties": {
          "traceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "fromTime": {
            "type": "integer",
            "minimum": 0,
            "description": "Inclusive settlement start timestamp in epoch milliseconds (`settledAt >= fromTime`)."
          },
          "toTime": {
            "type": "integer",
            "minimum": 0,
            "description": "Inclusive settlement end timestamp in epoch milliseconds (`settledAt <= toTime`, `toTime >= fromTime`)."
          },
          "pageNo": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20000,
            "default": 2000
          }
        }
      },
      "ReconcileTransactionRow": {
        "type": "object",
        "required": [
          "betId",
          "roundId",
          "externalTransactionId",
          "username",
          "currencyCode",
          "gameCode",
          "betSide",
          "betAmount",
          "winAmount",
          "winLoss",
          "effectiveTurnover",
          "status",
          "vendorBetTime",
          "vendorSettleTime"
        ],
        "properties": {
          "betId": {
            "type": "string",
            "description": "Immutable platform ticket ID (`bet_tickets.id`)."
          },
          "roundId": {
            "type": "string",
            "description": "Round identifier (`rounds.id`, or `{shoeId}:{roundNo}` fallback)."
          },
          "externalTransactionId": {
            "type": "string",
            "description": "Mirrors `betId`."
          },
          "username": {
            "type": "string",
            "description": "Operator-side player username."
          },
          "currencyCode": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "gameCode": {
            "type": "string",
            "description": "`{gameType}_{tableId}` (e.g. `BACCARAT_T-A2`)."
          },
          "betSide": {
            "$ref": "#/components/schemas/BaccaratBetSide"
          },
          "betAmount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "winAmount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "winLoss": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "effectiveTurnover": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "status": {
            "$ref": "#/components/schemas/ReconcileTicketStatus"
          },
          "vendorBetTime": {
            "type": "integer",
            "description": "Ticket acceptance timestamp in epoch milliseconds."
          },
          "vendorSettleTime": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Settlement timestamp in epoch milliseconds (`null` while unsettled)."
          }
        }
      },
      "ListTransactionsSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "type": "object",
            "required": [
              "transactions",
              "pageNo",
              "pageSize",
              "total"
            ],
            "properties": {
              "transactions": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReconcileTransactionRow"
                }
              },
              "pageNo": {
                "type": "integer",
                "minimum": 1
              },
              "pageSize": {
                "type": "integer",
                "minimum": 1,
                "maximum": 20000
              },
              "total": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      },
      "TransactionDetailRequest": {
        "type": "object",
        "required": [
          "traceId",
          "betId",
          "fromTime",
          "toTime"
        ],
        "additionalProperties": false,
        "properties": {
          "traceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "betId": {
            "type": "string",
            "minLength": 1,
            "description": "Target `bet_tickets.id`."
          },
          "fromTime": {
            "type": "integer",
            "minimum": 0,
            "description": "Window start in epoch milliseconds."
          },
          "toTime": {
            "type": "integer",
            "minimum": 0,
            "description": "Window end in epoch milliseconds (`toTime - fromTime <= 604800000`, max 7 days)."
          }
        }
      },
      "VerifiedRoundResult": {
        "type": "object",
        "required": [
          "outcome",
          "playerPoints",
          "bankerPoints",
          "playerPair",
          "bankerPair",
          "natural"
        ],
        "properties": {
          "outcome": {
            "$ref": "#/components/schemas/BaccaratOutcome"
          },
          "playerPoints": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9
          },
          "bankerPoints": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9
          },
          "playerPair": {
            "type": "boolean"
          },
          "bankerPair": {
            "type": "boolean"
          },
          "natural": {
            "type": "boolean"
          }
        }
      },
      "TransactionDetailSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReconcileTransactionRow"
              },
              {
                "type": "object",
                "required": [
                  "roundResult"
                ],
                "properties": {
                  "roundResult": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/VerifiedRoundResult"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            ]
          }
        }
      },
      "WalletBalanceWebhookRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username",
          "currency",
          "token"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "token": {
            "type": "string",
            "description": "Launch wallet token (`b2bt_<48hex>`) issued by `/operator/v1/game/url`."
          }
        }
      },
      "WalletBetWebhookRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username",
          "transactionId",
          "betId",
          "externalTransactionId",
          "amount",
          "currency",
          "token",
          "gameCode",
          "roundId",
          "timestamp"
        ],
        "properties": {
          "traceId": {
            "type": "string",
            "description": "Per-attempt HTTP trace UUID (may change on retry; NEVER use for idempotency)."
          },
          "username": {
            "type": "string"
          },
          "transactionId": {
            "type": "string",
            "description": "Deterministic outbound idempotency key (`bet_<32hex>`). Must be deduplicated uniquely by the operator."
          },
          "betId": {
            "type": "string",
            "description": "Platform `bet_tickets.id`."
          },
          "externalTransactionId": {
            "type": "string",
            "description": "Same as `betId`."
          },
          "amount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "token": {
            "type": "string"
          },
          "gameCode": {
            "type": "string",
            "examples": [
              "BACCARAT_T-A2"
            ]
          },
          "roundId": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer",
            "description": "Dispatch epoch milliseconds."
          }
        }
      },
      "WalletBetResultWebhookRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username",
          "transactionId",
          "betId",
          "externalTransactionId",
          "roundId",
          "betAmount",
          "winAmount",
          "effectiveTurnover",
          "winLoss",
          "jackpotAmount",
          "resultType",
          "isFreespin",
          "isEndRound",
          "currency",
          "token",
          "gameCode",
          "betTime",
          "settledTime"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "transactionId": {
            "type": "string",
            "description": "Deterministic settlement idempotency key (`stl_<32hex>`)."
          },
          "betId": {
            "type": "string"
          },
          "externalTransactionId": {
            "type": "string"
          },
          "roundId": {
            "type": "string"
          },
          "betAmount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "winAmount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "effectiveTurnover": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "winLoss": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "jackpotAmount": {
            "$ref": "#/components/schemas/UnsignedDecimalString",
            "default": "0.00"
          },
          "resultType": {
            "type": "string",
            "enum": [
              "WIN",
              "LOSE"
            ],
            "description": "`WIN` (includes Tie PUSH with `winAmount = betAmount`, `winLoss = \"0.00\"`) or `LOSE` (`winAmount = \"0.00\"`)."
          },
          "isFreespin": {
            "type": "integer",
            "const": 0
          },
          "isEndRound": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "token": {
            "type": "string"
          },
          "gameCode": {
            "type": "string"
          },
          "betTime": {
            "type": "integer",
            "description": "Original bet timestamp in epoch milliseconds."
          },
          "settledTime": {
            "type": "integer",
            "description": "Round settlement timestamp in epoch milliseconds."
          }
        }
      },
      "WalletRollbackWebhookRequest": {
        "type": "object",
        "required": [
          "traceId",
          "username",
          "transactionId",
          "betId",
          "externalTransactionId",
          "roundId",
          "amount",
          "currency",
          "token",
          "gameCode",
          "timestamp"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "transactionId": {
            "type": "string",
            "description": "Deterministic rollback idempotency key (`rb_<ticketId>` for void or `late_<betTxId>` for late-round-close compensation)."
          },
          "betId": {
            "type": "string"
          },
          "externalTransactionId": {
            "type": "string"
          },
          "roundId": {
            "type": "string"
          },
          "amount": {
            "$ref": "#/components/schemas/UnsignedDecimalString"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "token": {
            "type": "string"
          },
          "gameCode": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer"
          }
        }
      },
      "WalletCallbackSuccessResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "data"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "SC_OK"
          },
          "data": {
            "type": "object",
            "required": [
              "balance",
              "timestamp"
            ],
            "properties": {
              "username": {
                "type": "string"
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "balance": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/UnsignedDecimalString"
                  },
                  {
                    "type": "number",
                    "minimum": 0
                  }
                ],
                "description": "Player available balance after applying the operation (Decimal string strongly recommended)."
              },
              "timestamp": {
                "type": "integer",
                "description": "Operator wallet posting timestamp in epoch milliseconds."
              }
            }
          }
        }
      },
      "OperatorErrorResponse": {
        "type": "object",
        "required": [
          "traceId",
          "status",
          "message"
        ],
        "properties": {
          "traceId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "SC_INVALID_REQUEST",
              "SC_AUTHENTICATION_FAILED",
              "SC_INVALID_SIGNATURE",
              "SC_INVALID_TOKEN",
              "SC_INVALID_GAME",
              "SC_USER_NOT_EXISTS",
              "SC_USER_DISABLED",
              "SC_WRONG_CURRENCY",
              "SC_CURRENCY_NOT_SUPPORTED",
              "SC_INSUFFICIENT_FUNDS",
              "SC_TRANSACTION_DUPLICATED",
              "SC_TRANSACTION_NOT_EXISTS",
              "SC_TRANSACTION_STILL_PROCESSING",
              "SC_OPERATOR_TIMEOUT",
              "SC_UNDER_MAINTENANCE",
              "SC_GAME_DISABLED"
            ]
          },
          "message": {
            "type": "string"
          },
          "validation": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional field-level validation failure messages when `status = \"SC_INVALID_REQUEST\"`."
          }
        }
      }
    }
  }
}
