跳到主要内容

转账钱包 API 簡介

什麼是转账钱包模式？​

转账钱包模式是一种游戏整合方案，会员的余额分为主钱包和游戏钱包兩个部分。玩家需要先将资金从主钱包转入游戏钱包，才能在VP进行下注。游戏结束后，可将游戏钱包的余额转出至主钱包。

与单一钱包的差异​

特性转账钱包单一钱包
余额管理VP管理平台端端管理
下注流程先转账后下注即时扣款
实作要求平台端呼叫VP API平台端需实作 4 个 API
资金流动需要转入/转出无需转账
适用场景需要资金隔离的平台端已有钱包系统的平台端

在转账钱包模式下：

  1. 🎮 玩家 先将主钱包资金转入游戏钱包
  2. 🔐 VP 使用转入的资金进行游戏
  3. 💰 下注和结算都在游戏钱包內进行
  4. 📊 游戏结束后可将余额转出至主钱包

文档结构​

本文档包含以下功能模组：

📗 VP提供的 API（平台端呼叫）​

平台端可以呼叫以下VP API 进行会员管理、资金转账和查询：

版本资讯​

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

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

  • token: VP的认证 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": 6,
  "message": "The username already exist.",
  "logUUID": "6589bf8d-fe74-48bd-841a-71bf8f848f86"
}
欄位类型说明
codenumber错误代码（非 0），请参考各 API 的错误码表
messagestring错误说明讯息
logUUIDstring请求追蹤 ID，用于问题排查和日誌查询

常見回应码​

以下为常見的回应码，详细错误码请参考「附录」页面。

常見问题​

Q1: 钱包余额精度应该设定多少位小数?​

A: 支援到小数后 6 位 (0.000001)。

资金流程​

测试建议​

  • 使用测试环境进行开发测试
  • 确认所有错误情境都有适当处理
  • 验证 nonce 的唯一性
  • 测试网路异常和超时情况
  • 定期查询余额确保资金正确

注意事项​

  1. 双层钱包: 需要管理主钱包和游戏钱包兩个余额
  2. 转账确认: 转入/提領操作完成后建议使用余额查询 API 确认
  3. 余额管理: 确保游戏钱包有足夠余额才能进行游戏
  4. 交易追蹤: 保存所有转账記录以便对账
  5. 异常处理: 转账失敗时需要妥善处理并通知玩家