B Baccarat OpenAPIB2B Seamless v1
OpenAPI 交互调试器 YAML JSON Markdown AI 提示词
中文English

OpenAPI 3.1.0 · B2B Single Seamless Wallet (C01)

真人视讯百家乐 · B2B 运营商对接文档

面向外部接入运营商(Merchant / Operator)的标准 S2S 进桌、桌台限红发现、结算流水对账与单一无缝钱包(Seamless Wallet)回调契约。玩家资金全程保留在运营商自有钱包,零额度转入转出摩擦。

双向统一 HMAC-SHA256

入站 /operator/v1/* 与出站 /wallet/* 均使用 X-API-Key + X-Signature(对原始 UTF-8 JSON 字节签名)。

无锁三段式扣款与自动冲正

外部 HTTP 不占数据库锁;若扣款返回瞬间牌局恰好封盘,平台立即自动发送 late_ 回滚补单,绝不吞款。

精确十进制金额字符串

所有出站金额与对账字段统一为精确十进制字符串(如 "100.00"),彻底杜绝 IEEE-754 浮点舍入误差。

24×7 真视觉演播沙箱桌 T-A2

测试环境常驻 1280×720 LL-HLS + WebRTC WHEP 实况推流与真牌靴发牌结算,随时实盘联调。

1. 环境域名与商户凭证

用途 Dev / 联调沙箱地址 说明
S2S OpenAPI 网关 https://api.lt.cniia.cloud 承载全部 POST /operator/v1/game/* 与 /operator/v1/transaction/* 请求(HTTPS)
玩家端 H5 / Web 大厅 https://play.lt.cniia.cloud game/url 返回的进桌链接域名;内置常驻真视觉桌 T-A2 与演示桌 T-A1
商户控制台 https://admin.lt.cniia.cloud/merchant/ 查看商户注单流水、玩家外部 ID(external_user_id)、费率与商业预存账单
OpenAPI 规范直链 https://openapi.lt.cniia.cloud/openapi.yaml 支持 CORS 跨域直连,可直接导入 Apifox / Postman / Insomnia / AI Coding 工具
凭证格式与安全约定: 商户开通后由后台签发一对凭证:X-API-Key(格式 ak_<32位十六进制>)与 HMAC Secret(32 随机字节 base64url 明文,仅在签发/轮换当次展示一次)。商户编码 operatorId 遵循正则 ^[A-Z0-9_-]{1,64}$(严禁冒号)。同时须向平台报备:① 出站回调根地址 callbackUrl(例如 https://wallet.merchant.com/baccarat,不含末尾斜杠与 /wallet/*);② 调用源服务器 IP / CIDR 白名单。

2. 5 语言签名与进桌快速开始

计算签名唯一铁律:将请求 JSON 序列化为确切的 UTF-8 字节数组 rawBody,使用 HMAC-SHA256(rawBody, hmacSecret) 输出 64 位小写十六进制字符串填入 X-Signature,并将完全相同的 rawBody 作为 HTTP 请求体发出。验签商户回调时同样必须读取原始请求体字节(切勿 JSON.parse 后再 JSON.stringify)。

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. 一局完整交互与资金时序

[商户服务端]                     [百家乐平台 S2S / 结算引擎]                 [商户无缝钱包 callbackUrl]
     |                                        |                                         |
     |-- 1. POST /operator/v1/game/url ------>|                                         |
     |      (username, tableId=T-A2, USD)     |-- 2. 签发 b2bt_ 令牌并同步探活 -------->| POST /wallet/balance
     |                                        |<--   SC_OK + balance="1000.00" ---------|
     |<-- 3. 返回 { gameUrl, token } ---------|                                         |
     |                                                                                  |
[玩家浏览器打开 gameUrl]                                                                |
     |-- 4. 前端剥离 URL ?token= 并调 POST /player/v1/auth/b2b-exchange (一次性核销) -->|
     |-- 5. 玩家在 BETTING_OPEN 窗口下注 100.00 USD (PLAYER) -------------------------->|
     |                                        |-- 6. 事务外扣款 (bet_<32hex>) --------->| POST /wallet/bet (amount="100.00")
     |                                        |<--   SC_OK + balance="900.00" ----------|
     |                                        |-- 7. 复核仍未封盘 -> 落 ACCEPTED 票     |
     |                                        |      (若途中已封盘 -> 立即调 /wallet/rollback late_<txId> 退回 100.00)
     |                                        |                                         |
     |                                  [荷官/演播厅验签开奖 ValidatedResult]           |
     |                                        |-- 8. 逐票结算 (stl_<32hex>) ----------->| POST /wallet/bet_result
     |                                        |<--   SC_OK + balance="1100.00" ---------| (WIN: winAmount="200.00")
     |                                                                                  |
[商户对账定时任务]                                                                      |
     |-- 9. POST /operator/v1/transaction/list (按 settledAt 拉取终局注单核对) -------->|
POST · S2S /operator/v1/game/url

4.1 获取玩家进桌 URL(POST /operator/v1/game/url)

为指定运营商玩家创建(或复用)平台映射账号,校验桌台权限、币种一致性与负责任博彩状态,生成 b2bt_ 会话令牌并同步向商户 /wallet/balance 发起余额探针——若余额探针失败将直接返回对应 SC_* 错误且不会签发 URL。一次性进桌兑换有效期默认 900 秒(15 分钟)。

请求体参数(JSON)

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

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
gameUrl string 必填 One-time player launch URL (default 900s TTL for URL exchange).
token string 必填 Session wallet token (`b2bt_<48hex>`) echoed on all subsequent `/wallet/*` callbacks.

请求示例

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

成功响应示例(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 查询可进牌桌与动态限红(POST /operator/v1/game/tables)

分页返回当前商户有权访问的已配置/维护中牌桌列表。maxBet 已自动按「桌台单桌覆盖限红 ∩ 全局币种/USD 基准折算限红 ∩ 商户绑定风控限额模板」取最严交集并格式化为十进制字符串;gameCode 固定为 {gameType}_{tableId}(如 BACCARAT_T-A2)。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填 [len 1..128]
currency string 可选 Optional 3-letter currency filter. [regex `^[A-Z]{3}$`]
pageNo integer 可选 [range 1..∞, default=1]
pageSize integer 可选 [range 1..200, default=50]

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
tableId string 必填
gameCode string 必填 Canonical `{gameType}_{tableId}` identifier.
tableName string 必填
gameType string 必填
currency string 必填 [regex `^[A-Z]{3}$`]
status string ("OPEN" | "MAINTENANCE") 必填
minBet UnsignedDecimalString | null 必填
maxBet UnsignedDecimalString | null 必填
chipUnit UnsignedDecimalString | null 必填
languages array 必填
platforms array 必填
coverImageUrl string | null 必填

请求示例

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

成功响应示例(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 强制踢出玩家会话(POST /operator/v1/game/terminate)

立即吊销该 username 在当前商户下的所有活跃玩家会话及尚未兑换的进桌令牌。若玩家在被踢前已有本局已扣款成功的在途注单(ACCEPTED),该注单仍随本局正常开奖结算或按桌规作废退款,绝不丢失幂等键。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填 [len 1..128]
username string 必填 [len 1..128]

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
username string 必填
terminatedSessions integer 必填 [range 0..∞]
revokedLaunchTokens integer 必填 [range 0..∞]

请求示例

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

成功响应示例(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 分页查询结算对账流水(POST /operator/v1/transaction/list)

按注单结算时间 settledAt 闭区间 [fromTime, toTime](Unix 毫秒时间戳)升序分页拉取本商户全部已结算/已作废注单。默认每页 2000 条,单页最大 20000 条。建议商户每 1~5 分钟以至少 2 分钟重叠窗口增量拉取,按 betId 幂等去重入库。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填 [len 1..128]
fromTime integer 必填 Inclusive settlement start timestamp in epoch milliseconds (`settledAt >= fromTime`). [range 0..∞]
toTime integer 必填 Inclusive settlement end timestamp in epoch milliseconds (`settledAt <= toTime`, `toTime >= fromTime`). [range 0..∞]
pageNo integer 可选 [range 1..∞, default=1]
pageSize integer 可选 [range 1..20000, default=2000]

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
betId string 必填 Immutable platform ticket ID (`bet_tickets.id`).
roundId string 必填 Round identifier (`rounds.id`, or `{shoeId}:{roundNo}` fallback).
externalTransactionId string 必填 Mirrors `betId`.
username string 必填 Operator-side player username.
currencyCode string 必填 [regex `^[A-Z]{3}$`]
gameCode string 必填 `{gameType}_{tableId}` (e.g. `BACCARAT_T-A2`).
betSide BaccaratBetSide 必填
betAmount UnsignedDecimalString 必填
winAmount UnsignedDecimalString 必填
winLoss DecimalString 必填
effectiveTurnover UnsignedDecimalString 必填
status ReconcileTicketStatus 必填
vendorBetTime integer 必填 Ticket acceptance timestamp in epoch milliseconds.
vendorSettleTime integer | null 必填 Settlement timestamp in epoch milliseconds (`null` while unsettled).

请求示例

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

成功响应示例(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 查询单笔注单详情与牌面结果(POST /operator/v1/transaction/detail)

按 betId 与时间窗口反查单张注单(toTime - fromTime 必须 ≤ 7 天,即 604800000 毫秒)。只要下注时间 vendorBetTime 或结算时间 vendorSettleTime 任一落在窗口内即命中(含未结注单 status = 0),并在已开奖时附带经边缘硬件签名核验的闲庄点数、对子与天牌结果 roundResult。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填 [len 1..128]
betId string 必填 Target `bet_tickets.id`. [len 1..∞]
fromTime integer 必填 Window start in epoch milliseconds. [range 0..∞]
toTime integer 必填 Window end in epoch milliseconds (`toTime - fromTime <= 604800000`, max 7 days). [range 0..∞]

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
outcome BaccaratOutcome 必填
playerPoints integer 必填 [range 0..9]
bankerPoints integer 必填 [range 0..9]
playerPair boolean 必填
bankerPair boolean 必填
natural boolean 必填

请求示例

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

成功响应示例(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 无缝钱包回调:查询可用余额(POST /wallet/balance)

平台在签发进桌链接(/operator/v1/game/url)及玩家在桌内刷新余额时调用。纯只读接口,商户必须先使用 HMAC Secret 校验请求头 X-Signature,核验 token 与 currency 后返回 HTTP 200 + SC_OK + 最新可用余额。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填
username string 必填
currency string 必填 [regex `^[A-Z]{3}$`]
token string 必填 Launch wallet token (`b2bt_<48hex>`) issued by `/operator/v1/game/url`.

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
username string 可选
currency string 可选 [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number 必填 Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer 必填 Operator wallet posting timestamp in epoch milliseconds.

请求示例

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

成功响应示例(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 无缝钱包回调:下注扣款(POST /wallet/bet)

玩家下注通过风控与开盘窗口检查后,平台在数据库事务外调用商户扣款。幂等主键为 transactionId(格式 bet_<32位十六进制>):
• 同键同内容重试:绝不可二次扣款,必须直接返回 HTTP 200 + status: "SC_OK" + 当前最新 data.balance(切勿返回 SC_TRANSACTION_DUPLICATED);
• 同键不同内容:返回 SC_TRANSACTION_DUPLICATED;
• 余额不足:返回 SC_INSUFFICIENT_FUNDS。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填 Per-attempt HTTP trace UUID (may change on retry; NEVER use for idempotency).
username string 必填
transactionId string 必填 Deterministic outbound idempotency key (`bet_<32hex>`). Must be deduplicated uniquely by the operator.
betId string 必填 Platform `bet_tickets.id`.
externalTransactionId string 必填 Same as `betId`.
amount UnsignedDecimalString 必填
currency string 必填 [regex `^[A-Z]{3}$`]
token string 必填
gameCode string 必填
roundId string 必填
timestamp integer 必填 Dispatch epoch milliseconds.

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
username string 可选
currency string 可选 [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number 必填 Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer 必填 Operator wallet posting timestamp in epoch milliseconds.

请求示例

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

成功响应示例(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 无缝钱包回调:逐票结算派彩(POST /wallet/bet_result)

牌局经硬件验签开奖后按每张注单逐笔调用(不合并整局多票)。幂等主键为 transactionId(格式 stl_<32位十六进制>)。商户按 winAmount 给玩家账户加款(LOSE 时 winAmount = "0.00",仍需记录该 transactionId 已结算并返回 SC_OK + 当前余额)。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填
username string 必填
transactionId string 必填 Deterministic settlement idempotency key (`stl_<32hex>`).
betId string 必填
externalTransactionId string 必填
roundId string 必填
betAmount UnsignedDecimalString 必填
winAmount UnsignedDecimalString 必填
effectiveTurnover UnsignedDecimalString 必填
winLoss DecimalString 必填
jackpotAmount UnsignedDecimalString 必填 [default="0.00"]
resultType string ("WIN" | "LOSE") 必填 `WIN` (includes Tie PUSH with `winAmount = betAmount`, `winLoss = "0.00"`) or `LOSE` (`winAmount = "0.00"`).
isFreespin integer = 0 必填
isEndRound integer (0 | 1) 必填
currency string 必填 [regex `^[A-Z]{3}$`]
token string 必填
gameCode string 必填
betTime integer 必填 Original bet timestamp in epoch milliseconds.
settledTime integer 必填 Round settlement timestamp in epoch milliseconds.

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
username string 可选
currency string 可选 [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number 必填 Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer 必填 Operator wallet posting timestamp in epoch milliseconds.

请求示例

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

成功响应示例(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 无缝钱包回调:作废与关窗自动冲正(POST /wallet/rollback)

用于三种冲正场景:① 整局作废(VOID);② 异常挂起注单经运营审批作废(rb_<ticketId>);③ 下注途中封盘竞态自动补偿(late_<betTxId>)。
空成功契约(Empty-Success):若商户侧查不到原 betId 的成功扣款记录(例如原扣款网络超时未到达商户或已被拒),商户返回 SC_TRANSACTION_NOT_EXISTS 或不加款返回 SC_OK,平台均收敛为已完成(COMPLETED)。

请求体参数(JSON)

字段 类型 / 枚举 必填 说明与约束
traceId string 必填
username string 必填
transactionId string 必填 Deterministic rollback idempotency key (`rb_<ticketId>` for void or `late_<betTxId>` for late-round-close compensation).
betId string 必填
externalTransactionId string 必填
roundId string 必填
amount UnsignedDecimalString 必填
currency string 必填 [regex `^[A-Z]{3}$`]
token string 必填
gameCode string 必填
timestamp integer 必填

成功响应 data 结构

字段 类型 / 枚举 必填 说明与约束
username string 可选
currency string 可选 [regex `^[A-Z]{3}$`]
balance UnsignedDecimalString | number 必填 Player available balance after applying the operation (Decimal string strongly recommended).
timestamp integer 必填 Operator wallet posting timestamp in epoch milliseconds.

请求示例

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

成功响应示例(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 签名规范与浏览器本地验签器

100% 浏览器本地计算: 下方工具直接调用浏览器原生 crypto.subtle API 计算 HMAC-SHA256(UTF8(rawBody), UTF8(secret)),密钥与报文不会离开你的浏览器,可直接用来对拍你的服务端签名实现。
X-Signature: computing…

8. 金额十进制精度与百家乐可下注边枚举

平台内部采用币种最小展示单位 1/1000 的 BigInt 整数账本(LEDGER_SCALE = 1000),在 B2B 对接层通过纯字符串整数运算换算为标准十进制字符串(正则 ^-?\d+(?:\.\d+)?$)。商户回调返回的 balance 最多允许 displayExponent + 3 位有效小数(去尾零后),严禁返回科学计数法(如 1e5)、NaN 或负数。常见币种 displayExponent:USD / USDT / EUR / PHP / CNY / THB / MYR 为 2(如 "100.00");JPY / KRW / VND 为 0(如 "1000")。

百家乐注型代码(BaccaratBetSide)

betSide 含义与规则集约束 典型赔率参考(实际以桌台锁定规则集为准)
PLAYER 闲赢(主注,必配) 1 : 1(和局退回本金 PUSH)
BANKER 庄赢(主注,必配) 0.95 : 1 抽水局 / 免佣局按桌台锁定规则集(和局退回本金 PUSH)
TIE 和局(主注,必配) 8 : 1
P_PAIR 闲对(可选边注,首两张同点) 11 : 1(视桌台激活规则集)
B_PAIR 庄对(可选边注,首两张同点) 11 : 1(视桌台激活规则集)
ANY_PAIR 任意对(可选边注,闲或庄首两张成对) 5 : 1(视桌台激活规则集)
SUPER_6 幸运六 Super 6(可选边注,庄以 6 点胜) 12 : 1 / 20 : 1(视桌台激活规则集)

9. 结算派彩真值表与超时幂等重试规则

结算场景(设本金 100.00) 出站回调路径 resultType winAmount winLoss effectiveTurnover status 入账要点
押中获胜(WIN,例:押闲 100.00,1:1 净赢 100.00) POST {callbackUrl}/wallet/bet_result WIN 200.00 100.00 100.00 1 商户侧无冻结科目,winAmount = betAmount + netPayout(含退回本金 + 净派彩)
未押中判负(LOSE,例:押庄 100.00,闲赢) POST {callbackUrl}/wallet/bet_result LOSE 0.00 -100.00 100.00 1 下注时已扣 100.00,结算 winAmount=0.00 不加款,仍须落幂等记录并返回 SC_OK + 当前余额
和局退回主注本金(PUSH,例:押闲/押庄 100.00,开出 TIE) POST {callbackUrl}/wallet/bet_result WIN 100.00 0.00 0.00 1 固定采用 bet_result(resultType="WIN", winAmount=betAmount, winLoss="0.00", effectiveTurnover="0.00") 原路退回本金
局作废 / 挂起单人工取消 / 下注途中封盘冲正(VOID / Late Rollback) POST {callbackUrl}/wallet/rollback — (rollback) 100.00 0.00 0.00 3 transactionId 为 rb_{ticketId} 或 late_{betTxId};若原注未扣成返回 SC_OK 或 SC_TRANSACTION_NOT_EXISTS 均收敛为空成功
超时与瞬态错误(8000ms): 当商户钱包回调耗时超过 8000ms、返回 HTTP 408 / 429 / 5xx,或返回业务码 SC_OPERATOR_TIMEOUT / SC_TRANSACTION_STILL_PROCESSING 时,平台将其判定为瞬态未决(Transient),绝不会更换 transactionId 重新扣款,而是以完全相同的 transactionId 重试结算/回滚,直至收敛。POST {callbackUrl}/wallet/adjustment(opadj: 错牌改派)当前版本预留未启用。

10. SC_ 状态码完整字典(共 17 项)

status 分类 重试策略 触发条件与对接处置说明
SC_OK SUCCESS 终态不重试 请求成功,或相同业务内容的资金幂等重放(重放必须返回最新余额 + SC_OK)
SC_INVALID_REQUEST VALIDATION 终态不重试 请求体缺少必填参数、类型/长度/格式非法,或分页/时间窗口越界(附 validation 字段明细)
SC_AUTHENTICATION_FAILED AUTH 终态不重试 缺少/无效/已停用的 X-API-Key、来源 IP 不在白名单,或商户未配置 callbackUrl
SC_INVALID_SIGNATURE AUTH 终态不重试 X-Signature HMAC-SHA256 校验失败(请确保对原始 UTF-8 JSON 请求体字节签名,64 位十六进制)
SC_INVALID_TOKEN SESSION 终态不重试 进桌会话令牌 token 无效、已过期或不属于当前用户/商户
SC_INVALID_GAME GAME 终态不重试 桌台 tableId 不存在、尚未完成初始化配置,或未授权给当前商户(allowedTables)
SC_USER_NOT_EXISTS USER 终态不重试 指定 username 在当前商户下不存在映射玩家(如 /game/terminate 踢人时)
SC_USER_DISABLED USER 终态不重试 玩家账号已被禁用,或处于负责任博彩冷静期(COOLING_OFF)/ 自我排除(SELF_EXCLUSION)期内
SC_WRONG_CURRENCY CURRENCY 终态不重试 请求币种与桌台运行币种不一致,或商户钱包回调返回的 data.currency 与请求币种不符
SC_CURRENCY_NOT_SUPPORTED CURRENCY 终态不重试 平台未配置该币种,或该币种未对当前商户开通(allowedCurrencies)
SC_INSUFFICIENT_FUNDS WALLET 终态不重试 玩家在商户无缝钱包中的可用余额不足以扣除本次下注金额
SC_TRANSACTION_DUPLICATED IDEMPOTENCY 终态不重试 幂等冲突:同一 transactionId 被用于不同业务内容的请求(同键同体重放严禁返回此码,应返回 SC_OK)
SC_TRANSACTION_NOT_EXISTS RECONCILE 终态不重试 查询单笔注单不存在/超出请求时间窗;或在 /wallet/rollback 时原注从未扣款成功(平台按空成功收敛)
SC_TRANSACTION_STILL_PROCESSING TRANSIENT 同键重试 同一幂等键正在处理中(租约期内),调用方应保持原 transactionId 稍后重试
SC_OPERATOR_TIMEOUT TRANSIENT 同键重试 平台出站调用商户无缝钱包超时(默认 8000ms)或收到 HTTP 408/429/5xx 瞬态错误,后续将同键重试/冲正
SC_UNDER_MAINTENANCE MAINTENANCE 终态不重试 目标桌台处于维护挂起状态(SUSPENDED),或商户绑定的风控限额模板当前不可用
SC_GAME_DISABLED MAINTENANCE 终态不重试 对应游戏类型在当前站点已停用

11. 商户上线前联调自检清单(Go-Live Checklist)

  • 原始字节验签:确认 Web 框架中间件已保留原始请求体 Buffer 计算 X-Signature,并使用恒定时间比较(timingSafeEqual / hmac.compare_digest)。
  • 同键同体重放返回 SC_OK:对同一 transactionId 连续发送两遍相同内容的 /wallet/bet、/wallet/bet_result、/wallet/rollback,确认玩家余额只变动一次且第二次仍返回 SC_OK + 最新余额。
  • 同键异体返回 SC_TRANSACTION_DUPLICATED:同一 transactionId 篡改 amount 重发,确认返回 SC_TRANSACTION_DUPLICATED。
  • 未扣成回滚空成功:构造从未出现过的 betId 调用 /wallet/rollback,确认商户返回 SC_TRANSACTION_NOT_EXISTS(或 SC_OK)且余额不变。
  • 和局 PUSH 与输局 LOSE 入账核对:确认 PUSH(resultType="WIN", winAmount=betAmount, winLoss="0.00")正确退回本金,LOSE(winAmount="0.00")不加款且正常落库。
  • 对账定时任务跑通:通过 POST /operator/v1/transaction/list 拉取 T-A2 沙箱实盘完局记录,核对 betId、winAmount、winLoss 与本地钱包流水一致。