营运商 API 实作说明
单一钱包模式下,营运商需要实作统一的 API 供游戏商呼叫,以实现余额查询、下注结算和交易处理。
架构概述
在单一钱包模式中,会员的余额由营运商端管理,游戏商作为游戏服务提供者,需要向营运商查询余额和处理交易。
API 实作说明
营运商需要在自己的伺服器上提供一组 callBack URL，营运商需根据请求中的 action 参数来决定执行的操作：
| Action | 说明 | 優先级 |
|---|---|---|
| balance | 即时查询会员可用余额 | 必须 |
| betNSettle | 处理游戏下注和结算 | 必须 |
| rollback | 回滾异常交易 | 必须 |
| retryBet | 下注重试机制 | 必须 |
统一端点
营运商只需提供一组 callBack URL，例如：
POST https://operator.example.com/api/wallet
游戏商会在请求的解密后参数中带上 action 欄位来区分不同操作
实作要求
1. 安全性要求
- ✅ 加密传输: 所有请求內容使用 AES-256-GCM 加密，响应使用明文 JSON 格式
- ✅ HTTPS: 生产环境必须使用 HTTPS
加密说明
算法: AES-256-GCM
- 密鑰長度：256 位（32 字節）
- IV 長度：96 位（12 字節）
- 认证标签長度：128 位（16 字節）
cipherText 格式:
ivBase64(16字元) + authTagBase64(24字元) + encryptedDataBase64
2. 响应格式要求
响应格式说明
所有营运商 API 的响应格式统一为明文 JSON，固定格式如下：
{
status: '0000',
errText: '',
balance: 12345.67,
responseTime: '2024-12-11T01:23:38.271Z'
}
| 欄位 | 类型 | 说明 |
|---|---|---|
| status | string | 状态码，详見各 API 说明 |
| errText | string | 错误讯息，成功时为空字串 |
| balance | number | 操作后的会员余额 |
| responseTime | string | 回应时间 |
3. 效能要求
- ⚡ 回应时间: 平均回应时间应 < 3000ms，超过则是为超时
常見问题
Q1: 如何区分不同的操作?
A: 游戏商会在请求的解密后参数中带上 action 欄位 (balance、betNSettle、rollback、retryBet)，营运商根据此欄位路由到对应的处理邏輯。
Q2: Token 有效期应该设定多久?
A: 建议 24 小时。会员关闭游戏或登出后,应该使 Token 失效。
Q3: 余额精度应该设定多少位小数?
A: 支援到小数后 4 位 (0.0001)，至少要支援到小数后 2 位 (0.01)。
Q4: 交易多久后会是为超时?
A: 3 秒
Q5: 那些交易会进入下注重试流程?
A: 道具与平台卡之交易不会觸发取消下注，会透过「下注重试」API 持续重试
Q6: callBack Url 可以调整嗎?
A: 可以，交易回传的 calBack Url 我方并未指定任何格式，具体可透过后台设定与验证
技术支援
如在实作过程中遇到问题,请聯繫 TG 技术支援团队