# Baccarat Live Platform · B2B Operator Seamless Wallet OpenAPI Guide (v1.0.0)

- OpenAPI 3.1 YAML: `https://openapi.lt.cniia.cloud/openapi.yaml`
- OpenAPI 3.1 JSON: `https://openapi.lt.cniia.cloud/openapi.json`
- Sandbox S2S Base URL: `https://api.lt.cniia.cloud`
- Sandbox Player Web Host: `https://play.lt.cniia.cloud` (24×7 Live Studio Table `T-A2` & Demo `T-A1`)

## 1. Authentication, HMAC-SHA256 & Envelope

1. **Symmetrical Headers**: Both inbound `/operator/v1/*` calls and outbound `{callbackUrl}/wallet/*` webhooks require:
   - `Content-Type: application/json`
   - `X-API-Key: ak_<32-hex-chars>`
   - `X-Signature: <64-char lowercase hex>` = `HMAC-SHA256(rawJsonBodyBytes, hmacSecret)` (**sign and verify exact raw UTF-8 HTTP body bytes**).
2. **HTTP 200 Envelope**: Returns `{ "traceId": "...", "status": "SC_OK", "data": { ... } }` on success or `{ "traceId": "...", "status": "SC_*", "message": "...", "validation"?: { ... } }` on rejection.
3. **Decimal Precision**: All monetary strings use exact base-10 Decimal strings (e.g. `"100.00"`). Wallet callback `data.balance` accepts non-negative Decimal strings (recommended) or finite JSON numbers.

## 2. Inbound S2S Endpoints (Operator -> Platform)

### `POST /operator/v1/game/url` — Issue one-time player launch URL & wallet session token

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.

```json
{
  "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"
}
```

```json
{
  "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"
  }
}
```

### `POST /operator/v1/game/tables` — List permitted live tables & dynamic betting limits

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.

```json
{
  "traceId": "7f19b4a2-3d10-4c9a-9e21-5518a0c21101",
  "currency": "USD",
  "pageNo": 1,
  "pageSize": 50
}
```

```json
{
  "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
  }
}
```

### `POST /operator/v1/game/terminate` — Force-terminate player sessions & unused launch tokens

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.

```json
{
  "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
  "username": "player_9527"
}
```

```json
{
  "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "terminatedSessions": 1,
    "revokedLaunchTokens": 0
  }
}
```

### `POST /operator/v1/transaction/list` — Paginated settled/voided ticket reconciliation feed

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`.

```json
{
  "traceId": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "fromTime": 1763611200000,
  "toTime": 1763614800000,
  "pageNo": 1,
  "pageSize": 2000
}
```

```json
{
  "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
  }
}
```

### `POST /operator/v1/transaction/detail` — Inspect single ticket & verified round card outcome

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.

```json
{
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "betId": "cm3p9z1x0000108l47a9g2k1m",
  "fromTime": 1763550000000,
  "toTime": 1763636400000
}
```

```json
{
  "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
    }
  }
}
```

## 3. Outbound Seamless Wallet Webhooks (Platform -> Operator `{callbackUrl}`)

### `POST {callbackUrl}/wallet/balance — Query player available balance`

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.

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "username": "player_9527",
  "currency": "USD",
  "token": "b2bt_9f81c204d7e641b8a5309c17e248f6b109d3a4c5e6f70819"
}
```

```json
{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1000.00",
    "timestamp": 1763612005000
  }
}
```

### `POST {callbackUrl}/wallet/bet — Deduct player stake (idempotent by transactionId)`

Invoked outside PostgreSQL transactions after risk & betting-window checks pass. Guarded by `opbet:{operatorId}:{transactionId}` (`transactionId = bet_<32hex>`).

- **Idempotent replay**: Same `transactionId` + same payload -> do NOT deduct again; return `HTTP 200` + `status: "SC_OK"` + current `data.balance`.
- **Conflict**: Same `transactionId` + different payload -> return `status: "SC_TRANSACTION_DUPLICATED"`.
- **Insufficient balance**: Return `status: "SC_INSUFFICIENT_FUNDS"`.

```json
{
  "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
}
```

```json
{
  "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "900.00",
    "timestamp": 1763612010185
  }
}
```

### `POST {callbackUrl}/wallet/bet_result — Per-ticket settlement payout / loss / push`

Invoked per ticket upon verified round settlement. Guarded by `opsettle:{operatorId}:{transactionId}` (`transactionId = stl_<32hex>`).

- **WIN**: `resultType = "WIN"`, `winAmount = betAmount + netPayout`, `winLoss = +netPayout`, `effectiveTurnover = betAmount`.
- **LOSE**: `resultType = "LOSE"`, `winAmount = "0.00"`, `winLoss = -betAmount`, `effectiveTurnover = betAmount`.
- **PUSH (Tie refund)**: `resultType = "WIN"`, `winAmount = betAmount`, `winLoss = "0.00"`, `effectiveTurnover = "0.00"`.

```json
{
  "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
}
```

```json
{
  "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1100.00",
    "timestamp": 1763612038510
  }
}
```

### `POST {callbackUrl}/wallet/rollback — Void refund or late-round-close compensation`

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}`.

- **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.

```json
{
  "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
}
```

```json
{
  "traceId": "c1094e22-8831-42b7-9901-77a6b5c4d3e2",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1000.00",
    "timestamp": 1763612042060
  }
}
```

## 4. Status Code Reference (`SC_*`)

| Code | Category | Same-Key Retry | Description |
| --- | --- | --- | --- |
| `SC_OK` | SUCCESS | NO | Success, or idempotent replay of an identical financial transaction (replay MUST return latest balance + SC_OK). |
| `SC_INVALID_REQUEST` | VALIDATION | NO | Missing or invalid parameters in request body, malformed decimal, or invalid pagination/time window (includes validation map when applicable). |
| `SC_AUTHENTICATION_FAILED` | AUTH | NO | Missing, invalid, or disabled X-API-Key, client IP not in operator IP whitelist, or operator callbackUrl not configured. |
| `SC_INVALID_SIGNATURE` | AUTH | NO | X-Signature HMAC-SHA256 verification failed (must sign exact raw UTF-8 JSON body bytes as 64-char hex). |
| `SC_INVALID_TOKEN` | SESSION | NO | Wallet/session token is invalid, expired, or does not belong to the player/operator. |
| `SC_INVALID_GAME` | GAME | NO | Table does not exist, is unconfigured, or is not permitted for this operator (allowedTables). |
| `SC_USER_NOT_EXISTS` | USER | NO | Specified username has no mapped player under this operator (e.g., on /game/terminate). |
| `SC_USER_DISABLED` | USER | NO | Player account is disabled or has an active responsible-gaming restriction (SELF_EXCLUSION / COOLING_OFF). |
| `SC_WRONG_CURRENCY` | CURRENCY | NO | Requested currency mismatches table operating currency, or wallet callback returned a mismatched data.currency. |
| `SC_CURRENCY_NOT_SUPPORTED` | CURRENCY | NO | Currency is not supported by the platform or not enabled for this operator (allowedCurrencies). |
| `SC_INSUFFICIENT_FUNDS` | WALLET | NO | Player available balance in operator seamless wallet is insufficient for this bet. |
| `SC_TRANSACTION_DUPLICATED` | IDEMPOTENCY | NO | Idempotency conflict: same transactionId reused with different business payload (do NOT return this for same-payload retries; return SC_OK instead). |
| `SC_TRANSACTION_NOT_EXISTS` | RECONCILE | NO | Transaction not found / outside requested time window; or on /wallet/rollback when original bet was never deducted (treated as empty-success). |
| `SC_TRANSACTION_STILL_PROCESSING` | TRANSIENT | YES | Transaction with the same idempotency key is currently in progress; retry shortly with the exact same transactionId. |
| `SC_OPERATOR_TIMEOUT` | TRANSIENT | YES | Outbound request to operator wallet timed out (8000ms default) or received HTTP 408/429/5xx transient failure. |
| `SC_UNDER_MAINTENANCE` | MAINTENANCE | NO | Target table is suspended for maintenance, or the operator risk limit template is currently inactive. |
| `SC_GAME_DISABLED` | MAINTENANCE | NO | Game type is disabled for this environment or operator. |
