OpenAPI 3.1.0 · B2B Single Seamless Wallet (C01)
真人视讯百家乐 · B2B 运营商对接文档
面向外部接入运营商(Merchant / Operator)的标准 S2S 进桌、桌台限红发现、结算流水对账与单一无缝钱包(Seamless Wallet)回调契约。玩家资金全程保留在运营商自有钱包,零额度转入转出摩擦。
入站 /operator/v1/* 与出站 /wallet/* 均使用 X-API-Key + X-Signature(对原始 UTF-8 JSON 字节签名)。
外部 HTTP 不占数据库锁;若扣款返回瞬间牌局恰好封盘,平台立即自动发送 late_ 回滚补单,绝不吞款。
所有出站金额与对账字段统一为精确十进制字符串(如 "100.00"),彻底杜绝 IEEE-754 浮点舍入误差。
测试环境常驻 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 }
}import hashlib
import hmac
import json
import os
import uuid
import urllib.request
BASE_URL = "https://api.lt.cniia.cloud"
API_KEY = os.environ["B2B_API_KEY"] # e.g. "ak_8f12c4e9..."
HMAC_SECRET = os.environ["B2B_SECRET"] # 32-byte base64url secret
def sign_raw_body(raw_body: bytes, secret: str) -> str:
return hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
def verify_webhook_signature(raw_body: bytes, sig_header: str, secret: str) -> bool:
if not sig_header or len(sig_header.strip()) != 64:
return False
expected = sign_raw_body(raw_body, secret)
return hmac.compare_digest(expected, sig_header.strip().lower())
def launch_baccarat_table() -> dict:
payload = {
"traceId": str(uuid.uuid4()),
"username": "player_9527",
"tableId": "T-A2",
"language": "zh-CN",
"platform": "H5",
"currency": "USD",
"lobbyUrl": "https://merchant.example.com/lobby",
"ipAddress": "203.0.113.42",
}
# IMPORTANT: serialize once to exact UTF-8 bytes and send those exact bytes
raw_body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
req = urllib.request.Request(
f"{BASE_URL}/operator/v1/game/url",
data=raw_body,
headers={
"Content-Type": "application/json",
"X-API-Key": API_KEY,
"X-Signature": sign_raw_body(raw_body, HMAC_SECRET),
},
method="POST",
)
with urllib.request.urlopen(req, timeout=10) as resp:
body = json.loads(resp.read().decode("utf-8"))
if body.get("status") != "SC_OK":
raise RuntimeError(f"Launch rejected [{body.get('status')}]: {body.get('message')}")
return body["data"]package b2bclient
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"net/http"
"strings"
)
func SignRawBody(rawBody []byte, secret string) string {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
return hex.EncodeToString(mac.Sum(nil))
}
func VerifyWebhookSignature(rawBody []byte, sigHeader string, secret string) bool {
actual, err := hex.DecodeString(strings.ToLower(strings.TrimSpace(sigHeader)))
if err != nil || len(actual) != 32 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
return hmac.Equal(mac.Sum(nil), actual)
}
func PostOperatorS2S(baseURL, apiKey, secret, path string, reqPayload any) (map[string]any, error) {
rawBody, err := json.Marshal(reqPayload)
if err != nil {
return nil, err
}
req, err := http.NewRequest(http.MethodPost, baseURL+path, bytes.NewReader(rawBody))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("X-Signature", SignRawBody(rawBody, secret))
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var envelope map[string]any
if err := json.NewDecoder(resp.Body).Decode(&envelope); err != nil {
return nil, err
}
if envelope["status"] != "SC_OK" {
return envelope, fmt.Errorf("operator status=%v msg=%v", envelope["status"], envelope["message"])
}
return envelope, nil
}<?php
declare(strict_types=1);
function signRawBody(string $rawBody, string $secret): string {
return hash_hmac('sha256', $rawBody, $secret);
}
function verifyWebhookSignature(string $rawBody, ?string $sigHeader, string $secret): bool {
$trimmed = strtolower(trim((string)$sigHeader));
if (!preg_match('/^[0-9a-f]{64}$/', $trimmed)) {
return false;
}
return hash_equals(signRawBody($rawBody, $secret), $trimmed);
}
$baseUrl = 'https://api.lt.cniia.cloud';
$apiKey = getenv('B2B_API_KEY');
$secret = getenv('B2B_SECRET');
$rawBody = json_encode([
'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_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$ch = curl_init($baseUrl . '/operator/v1/game/url');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $rawBody,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . $apiKey,
'X-Signature: ' . signRawBody($rawBody, $secret),
],
]);
$res = json_decode((string)curl_exec($ch), true);# 1. 准备原始 JSON 请求体(务必对发送的完全相同字节计算 HMAC-SHA256)
BODY='{"traceId":"e62ceec8-1c18-48fc-af0e-9f9f943b2554","currency":"USD","pageNo":1,"pageSize":50}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$B2B_SECRET" -hex | awk '{print $NF}')
# 2. 调用查询桌台接口 POST /operator/v1/game/tables
curl -sS -X POST "https://api.lt.cniia.cloud/operator/v1/game/tables" \
-H "Content-Type: application/json" \
-H "X-API-Key: $B2B_API_KEY" \
-H "X-Signature: $SIG" \
--data-binary "$BODY"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 拉取终局注单核对) -------->|
/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"
}
}
/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
}
}
/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
}
}
/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
}
}
/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
}
}
}
{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
}
}
{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
}
}
{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
}
}
{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 签名规范与浏览器本地验签器
crypto.subtle API 计算 HMAC-SHA256(UTF8(rawBody), UTF8(secret)),密钥与报文不会离开你的浏览器,可直接用来对拍你的服务端签名实现。
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、返回 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与本地钱包流水一致。