跳到主要内容

单一钱包 API 簡介

什麼是单一钱包模式？​

单一钱包模式是一种游戏整合方案，会员的余额由营运商端统一管理。游戏商再进行下注、结算等操作时，会即时呼叫营运商提供的 API 来查询余额和处理交易。

与转账钱包的差异​

特性单一钱包转账钱包
余额管理营运商端管理游戏商管理
下注流程即时扣款先转账后下注
实作要求营运商需实作 4 个 API营运商呼叫游戏商 API
资金流动无需转账需要转入/转出
适用场景已有钱包系统的营运商新建立的营运商

在单一钱包模式下：

  1. 🎮 玩家 在游戏商上玩游戏
  2. 🔐 游戏商 向营运商 API 验证会员身份
  3. 💰 每次下注时，游戏商呼叫营运商 API 扣款和加奖
  4. 📊 所有余额和交易記录由营运商端管理

文档结构​

本文档分为兩大部分：

📘 营运商 API 实作说明（必须实作）​

营运商需提供游戏商一组回调网址(callbackURL)供游戏商呼叫使用，游戏商会透过 action 参数来区分不同操作：

Action说明文档
balance即时查询会员可用余额查看文档
betNSettle处理游戏下注和结算（扣款+加奖）查看文档
rollback回滾异常交易查看文档
retryBet专用于道具与平台卡重试的重试机制查看文档

统一端点示例: POST https://operator.example.com/api/wallet

👉 开始实作: 营运商 API 实作指南

📗 游戏商提供的 API（营运商呼叫）​

营运商可以呼叫以下游戏商 API 进行会员管理和查询：

版本资讯​

  • 版本: v2.0.0
  • 类型: 单一钱包模式
  • 加密方式: AES-256-GCM
  • 认证方式: JWT Token + SHA256 签名

解密后的请求內容通常包含:

  • token: 游戏商的认证 token
  • account: 会员账号
  • nonce: 唯一交易識别码 (UUID)
  • timestamp: 请求时间戳

通用回应格式​

成功回应（有数据）​

所有非营运商实作的 API 回应都为明文 JSON 格式，遵循以下结构：

{
  "code": 0,
  "message": "No error.",
  "data": {
    // 各 API 特定的回应资料
  },
  "logUUID": "042d4437-cbe3-440a-8acf-4baff3722fd6"
}
欄位类型说明
codenumber状态码，0 表示成功
messagestring状态讯息，成功时为 "No error."
dataobjectAPI 回应数据，內容因 API 而异
logUUIDstring请求追蹤 ID，用于问题排查和日誌查询

成功回应（无数据）​

对于无需返回数据的操作，回应格式如下：

{
  "code": 0,
  "message": "No error.",
  "logUUID": "042d4437-cbe3-440a-8acf-4baff3722fd6"
}

错误回应​

{
  "code": 7,
  "message": "Internal server error.",
  "logUUID": "6589bf8d-fe74-48bd-841a-71bf8f848f86"
}
欄位类型说明
codenumber错误代码（非 0），请参考各 API 的错误码表
messagestring错误说明讯息
logUUIDstring请求追蹤 ID，用于问题排查和日誌查询

测试建议​

  • 使用测试环境进行开发测试
  • 确认所有错误情境都有适当处理
  • 验证 nonce 的唯一性
  • 测试网路异常和超时情况