B Baccarat OpenAPIB2B Seamless v1
OpenAPI Explorer YAML JSON Markdown AI Prompt
中文English

OpenAPI 3.1.0 · B2B Single Seamless Wallet (C01)

Live Studio Baccarat · B2B Operator Integration

Canonical Server-to-Server (S2S) table launch, dynamic limit discovery, settlement reconciliation, and outbound Single Seamless Wallet webhook contract. Player balances remain 100% in your operator wallet with zero credit-transfer friction.

Symmetrical HMAC-SHA256

Both inbound /operator/v1/* and outbound /wallet/* webhooks use X-API-Key + X-Signature over exact UTF-8 JSON bytes.

Lock-Free Bet & Auto-Rollback

External HTTP runs outside DB locks; if the betting window closes mid-flight, an automatic late_ rollback fires immediately.

Exact Decimal Strings

All outbound stakes, payouts, and reconciliation figures are exact base-10 Decimal strings (e.g. "100.00") with zero float drift.

24×7 Live Studio Sandbox T-A2

Dev environment streams 24×7 1280×720 LL-HLS + WebRTC WHEP video with real 8-deck shoe rounds for live E2E testing.

1. Environments & Operator Credentials

Component Dev / Sandbox Endpoint Notes
S2S OpenAPI Base URL https://api.lt.cniia.cloud Hosts all POST /operator/v1/game/* and /operator/v1/transaction/* endpoints over HTTPS.
Player H5 / Web Table Host https://play.lt.cniia.cloud Host returned in gameUrl; includes 24×7 studio table T-A2 and demo table T-A1.
Merchant Portal https://admin.lt.cniia.cloud/merchant/ View tickets, mapped external_user_id, fee rates, and commercial statements.
Raw OpenAPI 3.1 Spec https://openapi.lt.cniia.cloud/openapi.yaml CORS-enabled for one-click import into Postman, Apifox, Hoppscotch, or AI agents.
Credential Format & Security: Upon onboarding, you receive an X-API-Key (ak_<32-hex>) and a 32-byte base64url HMAC Secret (displayed in plaintext only once upon issuance/rotation). Operator IDs match ^[A-Z0-9_-]{1,64}$ (no colons). Provide: (1) your callbackUrl base (e.g. https://wallet.merchant.com/baccarat, without trailing /wallet/*), and (2) your outbound server IP/CIDR whitelist.

2. 5-Language Signing & Launch Quickstart

Golden rule: Serialize your JSON payload once to exact UTF-8 bytes (rawBody), compute lowercase 64-char hex HMAC-SHA256(rawBody, hmacSecret) into X-Signature, and transmit those exact bytes. Likewise, verify inbound /wallet/* webhooks against raw unparsed request body bytes.

import crypto from 'node:crypto';

const BASE_URL = 'https://api.lt.cniia.cloud';
const API_KEY = process.env.B2B_API_KEY;       // e.g. "ak_8f12c4e9..."
const HMAC_SECRET = process.env.B2B_SECRET;    // 32-byte base64url secret issued once

export function signRawBody(rawBodyBytes, secret) {
  return crypto
    .createHmac('sha256', Buffer.from(secret, 'utf8'))
    .update(rawBodyBytes)
    .digest('hex');
}

export function verifyWebhookSignature(rawBodyBuffer, sigHeader, secret) {
  if (!sigHeader || !/^[0-9a-fA-F]{64}$/.test(sigHeader.trim())) return false;
  const expected = Buffer.from(signRawBody(rawBodyBuffer, secret), 'hex');
  const actual = Buffer.from(sigHeader.trim().toLowerCase(), 'hex');
  return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
}

// 1. Outbound S2S call: POST /operator/v1/game/url
export async function launchBaccaratTable() {
  const payload = {
    traceId: crypto.randomUUID(),
    username: 'player_9527',
    tableId: 'T-A2',
    language: 'zh-CN',
    platform: 'H5',
    currency: 'USD',
    lobbyUrl: 'https://merchant.example.com/lobby',
    ipAddress: '203.0.113.42',
  };
  const rawBody = Buffer.from(JSON.stringify(payload), 'utf8');
  const signature = signRawBody(rawBody, HMAC_SECRET);

  const res = await fetch(`${BASE_URL}/operator/v1/game/url`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
      'x-signature': signature,
    },
    body: rawBody,
  });
  const json = await res.json();
  if (json.status !== 'SC_OK') {
    throw new Error(`Launch rejected [${json.status}]: ${json.message}`);
  }
  return json.data; // { gameUrl, token }
}

3. End-to-End Session & Fund Lifecycle

[Operator Backend]               [Baccarat Platform S2S & Settler]          [Operator Wallet callbackUrl]
     |                                        |                                         |
     |-- 1. POST /operator/v1/game/url ------>|                                         |
     |      (username, tableId=T-A2, USD)     |-- 2. Mint b2bt_ token & probe --------->| POST /wallet/balance
     |                                        |<--   SC_OK + balance="1000.00" ---------|
     |<-- 3. Return { gameUrl, token } -------|                                         |
     |                                                                                  |
[Player Browser opens gameUrl]                                                          |
     |-- 4. Scrub ?token= from URL & POST /player/v1/auth/b2b-exchange (one-time) ----->|
     |-- 5. Place 100.00 USD bet on PLAYER during BETTING_OPEN ------------------------>|
     |                                        |-- 6. Lock-free debit (bet_<32hex>) ---->| POST /wallet/bet (amount="100.00")
     |                                        |<--   SC_OK + balance="900.00" ----------|
     |                                        |-- 7. Re-verify window open -> ACCEPTED  |
     |                                        |      (If closed mid-flight -> auto POST /wallet/rollback late_<txId>)
     |                                        |                                         |
     |                                  [Verified Shoe ValidatedResult]                 |
     |                                        |-- 8. Per-ticket settle (stl_<32hex>) -->| POST /wallet/bet_result
     |                                        |<--   SC_OK + balance="1100.00" ---------| (WIN: winAmount="200.00")
     |                                                                                  |
[Operator Reconciliation Cron]                                                          |
     |-- 9. POST /operator/v1/transaction/list (poll by settledAt window) ------------->|
POST · S2S /operator/v1/game/url

4.1 Issue Player Launch URL (POST /operator/v1/game/url)

Maps or creates the operator player, verifies table/currency permissions and responsible-gaming status, mints a b2bt_ token, and executes a synchronous POST {callbackUrl}/wallet/balance probe. If the balance check fails, no URL is issued. Single-use URL exchange TTL defaults to 900s.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required Unique request trace ID (UUID v4 recommended; not an idempotency key). [len 1..128]
username string Required Operator-side unique player identifier (mapped per operator to a platform player). [len 1..128]
tableId string Required Target live table ID (e.g. `"T-A2"` or `"T-A1"`). [len 1..64]
language string Optional UI locale (`"en"` or `"zh-CN"`). [default="en"]
platform string ("web" | "H5") Required Client form factor (`"web"` for desktop, `"H5"` for mobile webview).
currency string Required 3-letter uppercase ISO-4217 / platform currency code matching the table currency. [regex `^[A-Z]{3}$`]
lobbyUrl string Required Safe `http://` or `https://` return URL when the player exits the table.
ipAddress string Required Player client IPv4 or IPv6 address.

Success Response data Fields

Field Type / Enum Required Description & Constraints
gameUrl string Required One-time player launch URL (default 900s TTL for URL exchange).
token string Required Session wallet token (`b2bt_<48hex>`) echoed on all subsequent `/wallet/*` callbacks.

Request Example

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

Success Response Example (HTTP 200)

{
  "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 · S2S /operator/v1/game/tables

4.2 List Permitted Tables & Limits (POST /operator/v1/game/tables)

Returns paginated tables permitted for this operator. maxBet reflects the effective intersection of table override, global FX benchmark cap, and your operator risk template. gameCode is strictly {gameType}_{tableId}.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required [len 1..128]
currency string Optional Optional 3-letter currency filter. [regex `^[A-Z]{3}$`]
pageNo integer Optional [range 1..∞, default=1]
pageSize integer Optional [range 1..200, default=50]

Success Response data Fields

Field Type / Enum Required Description & Constraints
tableId string Required
gameCode string Required Canonical `{gameType}_{tableId}` identifier.
tableName string Required
gameType string Required
currency string Required [regex `^[A-Z]{3}$`]
status string ("OPEN" | "MAINTENANCE") Required
minBet UnsignedDecimalString | null Required
maxBet UnsignedDecimalString | null Required
chipUnit UnsignedDecimalString | null Required
languages array Required
platforms array Required
coverImageUrl string | null Required

Request Example

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

Success Response Example (HTTP 200)

{
  "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 · S2S /operator/v1/game/terminate

4.3 Terminate Player Sessions (POST /operator/v1/game/terminate)

Immediately revokes all active sessions and unredeemed launch tokens for username under your operator. Any already-accepted bets in an active round still settle or void cleanly without losing idempotency.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required [len 1..128]
username string Required [len 1..128]

Success Response data Fields

Field Type / Enum Required Description & Constraints
username string Required
terminatedSessions integer Required [range 0..∞]
revokedLaunchTokens integer Required [range 0..∞]

Request Example

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

Success Response Example (HTTP 200)

{
  "traceId": "9c8812d0-0420-4f71-8c1b-33a90012ef90",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "terminatedSessions": 1,
    "revokedLaunchTokens": 0
  }
}
POST · S2S /operator/v1/transaction/list

5.1 Paginated Reconciliation Feed (POST /operator/v1/transaction/list)

Fetches settled and voided tickets filtered inclusively by settledAt within [fromTime, toTime] (epoch ms), ordered by (settledAt ASC, ticketId ASC). Poll every 1–5 minutes with a 2-minute overlap window and deduplicate by betId.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required [len 1..128]
fromTime integer Required Inclusive settlement start timestamp in epoch milliseconds (`settledAt >= fromTime`). [range 0..∞]
toTime integer Required Inclusive settlement end timestamp in epoch milliseconds (`settledAt <= toTime`, `toTime >= fromTime`). [range 0..∞]
pageNo integer Optional [range 1..∞, default=1]
pageSize integer Optional [range 1..20000, default=2000]

Success Response data Fields

Field Type / Enum Required Description & Constraints
betId string Required Immutable platform ticket ID (`bet_tickets.id`).
roundId string Required Round identifier (`rounds.id`, or `{shoeId}:{roundNo}` fallback).
externalTransactionId string Required Mirrors `betId`.
username string Required Operator-side player username.
currencyCode string Required [regex `^[A-Z]{3}$`]
gameCode string Required `{gameType}_{tableId}` (e.g. `BACCARAT_T-A2`).
betSide BaccaratBetSide Required
betAmount UnsignedDecimalString Required
winAmount UnsignedDecimalString Required
winLoss DecimalString Required
effectiveTurnover UnsignedDecimalString Required
status ReconcileTicketStatus Required
vendorBetTime integer Required Ticket acceptance timestamp in epoch milliseconds.
vendorSettleTime integer | null Required Settlement timestamp in epoch milliseconds (`null` while unsettled).

Request Example

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

Success Response Example (HTTP 200)

{
  "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 · S2S /operator/v1/transaction/detail

5.2 Single Ticket & Card Result Detail (POST /operator/v1/transaction/detail)

Looks up a single ticket betId within a <= 7 days window (604800000 ms). Matches if either vendorBetTime or vendorSettleTime falls inside the window (including unsettled status = 0 tickets) and includes verified roundResult card points/pairs/natural.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required [len 1..128]
betId string Required Target `bet_tickets.id`. [len 1..∞]
fromTime integer Required Window start in epoch milliseconds. [range 0..∞]
toTime integer Required Window end in epoch milliseconds (`toTime - fromTime <= 604800000`, max 7 days). [range 0..∞]

Success Response data Fields

Field Type / Enum Required Description & Constraints
outcome BaccaratOutcome Required
playerPoints integer Required [range 0..9]
bankerPoints integer Required [range 0..9]
playerPair boolean Required
bankerPair boolean Required
natural boolean Required

Request Example

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

Success Response Example (HTTP 200)

{
  "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
    }
  }
}
POST · WEBHOOK {callbackUrl}/wallet/balance

6.1 Wallet Webhook: Query Balance (POST /wallet/balance)

Called by the platform during /operator/v1/game/url pre-launch checks and live balance refreshes. Strictly read-only: verify X-Signature, validate token and currency, and return HTTP 200 + SC_OK + current data.balance.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required
username string Required
currency string Required [regex `^[A-Z]{3}$`]
token string Required Launch wallet token (`b2bt_<48hex>`) issued by `/operator/v1/game/url`.

Success Response data Fields

Field Type / Enum Required Description & Constraints
username string Optional
currency string Optional [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number Required Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer Required Operator wallet posting timestamp in epoch milliseconds.

Request Example

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

Success Response Example (HTTP 200)

{
  "traceId": "e62ceec8-1c18-48fc-af0e-9f9f943b2554",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1000.00",
    "timestamp": 1763612005000
  }
}
POST · WEBHOOK {callbackUrl}/wallet/bet

6.2 Wallet Webhook: Deduct Bet Stake (POST /wallet/bet)

Called outside DB locks once risk and betting-window checks pass. Deduplicate strictly by transactionId (bet_<32hex>):
• Same transactionId + same payload: DO NOT deduct twice; return HTTP 200 + status: "SC_OK" + current data.balance.
• Same transactionId + different payload: Return SC_TRANSACTION_DUPLICATED.
• Insufficient funds: Return SC_INSUFFICIENT_FUNDS.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required Per-attempt HTTP trace UUID (may change on retry; NEVER use for idempotency).
username string Required
transactionId string Required Deterministic outbound idempotency key (`bet_<32hex>`). Must be deduplicated uniquely by the operator.
betId string Required Platform `bet_tickets.id`.
externalTransactionId string Required Same as `betId`.
amount UnsignedDecimalString Required
currency string Required [regex `^[A-Z]{3}$`]
token string Required
gameCode string Required
roundId string Required
timestamp integer Required Dispatch epoch milliseconds.

Success Response data Fields

Field Type / Enum Required Description & Constraints
username string Optional
currency string Optional [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number Required Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer Required Operator wallet posting timestamp in epoch milliseconds.

Request Example

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

Success Response Example (HTTP 200)

{
  "traceId": "3d55f1a9-7c80-4e11-b022-8f9910a4bc12",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "900.00",
    "timestamp": 1763612010185
  }
}
POST · WEBHOOK {callbackUrl}/wallet/bet_result

6.3 Wallet Webhook: Settle Ticket Result (POST /wallet/bet_result)

Dispatched per ticket upon verified round settlement. Deduplicate by transactionId (stl_<32hex>). Credit winAmount to the player (for LOSE, winAmount = "0.00" — record idempotently and return SC_OK + current balance).

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required
username string Required
transactionId string Required Deterministic settlement idempotency key (`stl_<32hex>`).
betId string Required
externalTransactionId string Required
roundId string Required
betAmount UnsignedDecimalString Required
winAmount UnsignedDecimalString Required
effectiveTurnover UnsignedDecimalString Required
winLoss DecimalString Required
jackpotAmount UnsignedDecimalString Required [default="0.00"]
resultType string ("WIN" | "LOSE") Required `WIN` (includes Tie PUSH with `winAmount = betAmount`, `winLoss = "0.00"`) or `LOSE` (`winAmount = "0.00"`).
isFreespin integer = 0 Required
isEndRound integer (0 | 1) Required
currency string Required [regex `^[A-Z]{3}$`]
token string Required
gameCode string Required
betTime integer Required Original bet timestamp in epoch milliseconds.
settledTime integer Required Round settlement timestamp in epoch milliseconds.

Success Response data Fields

Field Type / Enum Required Description & Constraints
username string Optional
currency string Optional [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number Required Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer Required Operator wallet posting timestamp in epoch milliseconds.

Request Example

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

Success Response Example (HTTP 200)

{
  "traceId": "8b7719c2-61a4-49d0-92ef-1102a3b4c5d6",
  "status": "SC_OK",
  "data": {
    "username": "player_9527",
    "currency": "USD",
    "balance": "1100.00",
    "timestamp": 1763612038510
  }
}
POST · WEBHOOK {callbackUrl}/wallet/rollback

6.4 Wallet Webhook: Void & Late-Close Rollback (POST /wallet/rollback)

Triggered on: (1) Round VOID, (2) Approved held-ticket void (rb_<ticketId>), or (3) Late-round-close race compensation (late_<betTxId>).
Empty-Success Contract: If betId was never deducted on your side, return SC_TRANSACTION_NOT_EXISTS (or SC_OK without crediting); both converge cleanly to COMPLETED.

Request Body Parameters (JSON)

Field Type / Enum Required Description & Constraints
traceId string Required
username string Required
transactionId string Required Deterministic rollback idempotency key (`rb_<ticketId>` for void or `late_<betTxId>` for late-round-close compensation).
betId string Required
externalTransactionId string Required
roundId string Required
amount UnsignedDecimalString Required
currency string Required [regex `^[A-Z]{3}$`]
token string Required
gameCode string Required
timestamp integer Required

Success Response data Fields

Field Type / Enum Required Description & Constraints
username string Optional
currency string Optional [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number Required Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer Required Operator wallet posting timestamp in epoch milliseconds.

Request Example

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

Success Response Example (HTTP 200)

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

7. HMAC-SHA256 Specification & Local Browser Verifier

100% Local Web Crypto Execution: This verifier uses native browser crypto.subtle to compute HMAC-SHA256(UTF8(rawBody), UTF8(secret)) locally. Nothing is transmitted over the network.
X-Signature: computing…

8. Decimal Money Precision & Baccarat Bet Sides

Internally the platform stores amounts in integer 1/1000 minor units (LEDGER_SCALE = 1000) and converts at the B2B boundary via pure BigInt string math. Wallet callback balance values accept up to displayExponent + 3 fractional digits (after trimming trailing zeros) and reject scientific notation, NaN, or negative balances. Common displayExponent: USD/USDT/EUR/PHP/CNY = 2 ("100.00"); JPY/KRW/VND = 0 ("1000").

Baccarat Bet Side Enum (BaccaratBetSide)

betSide Meaning & Ruleset Availability Reference Odds (Actual governed by table ruleset)
PLAYER Player Win (Main bet, mandatory in every ruleset) 1 : 1(和局退回本金 PUSH)
BANKER Banker Win (Main bet, mandatory in every ruleset) 0.95 : 1 抽水局 / 免佣局按桌台锁定规则集(和局退回本金 PUSH)
TIE Tie (Main bet, mandatory in every ruleset) 8 : 1
P_PAIR Player Pair (Optional side bet: first two Player cards match rank) 11 : 1(视桌台激活规则集)
B_PAIR Banker Pair (Optional side bet: first two Banker cards match rank) 11 : 1(视桌台激活规则集)
ANY_PAIR Either / Any Pair (Optional side bet: Player or Banker initial pair) 5 : 1(视桌台激活规则集)
SUPER_6 Super 6 (Optional tableau side bet: Banker wins with 6 points) 12 : 1 / 20 : 1(视桌台激活规则集)

9. Settlement Math Truth Table & Retry Rules

Scenario (Stake = 100.00) Webhook Path resultType winAmount winLoss effectiveTurnover status Accounting Rule
Winning Ticket (WIN, e.g., Stake 100.00 on PLAYER at 1:1, netPayout 100.00) POST {callbackUrl}/wallet/bet_result WIN 200.00 100.00 100.00 1 Operator has no hold account; winAmount = betAmount + netPayout (principal + net winnings).
Losing Ticket (LOSE, e.g., Stake 100.00 on BANKER, outcome PLAYER) POST {callbackUrl}/wallet/bet_result LOSE 0.00 -100.00 100.00 1 Stake was already deducted on /wallet/bet; credit 0.00, record transactionId idempotently, return SC_OK + balance.
Tie Push Refund on Main Side (PUSH, e.g., Stake 100.00 on PLAYER/BANKER, outcome TIE) POST {callbackUrl}/wallet/bet_result WIN 100.00 0.00 0.00 1 Uses bet_result with resultType="WIN", winAmount=betAmount, winLoss="0.00", effectiveTurnover="0.00" to return principal.
Round Void / Held Ticket Void / Late-Close Compensation (VOID / Rollback) POST {callbackUrl}/wallet/rollback — (rollback) 100.00 0.00 0.00 3 transactionId is rb_{ticketId} or late_{betTxId}; if original bet never deducted, SC_OK or SC_TRANSACTION_NOT_EXISTS both converge to empty-success.
Timeouts & Transient Retries (8000ms): If a webhook exceeds 8000ms, returns HTTP 408/429/5xx, or returns SC_OPERATOR_TIMEOUT / SC_TRANSACTION_STILL_PROCESSING, the platform treats it as transient and retries with the exact same transactionId. POST {callbackUrl}/wallet/adjustment (opadj:) is reserved and not enabled in v1.

10. Complete SC_ Status Code Reference (17 Codes)

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

11. Operator Go-Live Verification Checklist

  • Raw-byte HMAC: Middleware preserves raw UTF-8 request Buffer before JSON parsing and verifies X-Signature in constant time.
  • Idempotent replay returns SC_OK: Re-sending identical /wallet/bet, /wallet/bet_result, or /wallet/rollback payloads mutates balance only once and returns SC_OK + latest balance.
  • Conflict detection: Reusing a transactionId with a different amount returns SC_TRANSACTION_DUPLICATED.
  • Rollback empty-success: Calling /wallet/rollback for a non-existent betId returns SC_TRANSACTION_NOT_EXISTS (or SC_OK) without changing balance.
  • PUSH & LOSE accounting: Verify Tie PUSH credits back betAmount with zero turnover, and LOSE credits 0.00 cleanly.
  • Reconciliation cron: Poll POST /operator/v1/transaction/list after a settled round on T-A2 and verify exact ledger parity.