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.
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 base64urlHMAC 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.
[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).
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}.
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.
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.
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..∞]
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.
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.
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).
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.
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.
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.