跳至主要内容

轉帳錢包 API 簡介

什麼是轉帳錢包模式？​

轉帳錢包模式是一種遊戲整合方案，會員的餘額分為主錢包和遊戲錢包兩個部分。玩家需要先將資金從主錢包轉入遊戲錢包，才能在遊戲商進行下注。遊戲結束後，可將遊戲錢包的餘額轉出至主錢包。

與單一錢包的差異​

特性轉帳錢包單一錢包
餘額管理遊戲商管理營運商端管理
下注流程先轉帳後下注即時扣款
實作要求營運商呼叫遊戲商 API營運商需實作 4 個 API
資金流動需要轉入/轉出無需轉帳
適用場景需要資金隔離的營運商已有錢包系統的營運商

在轉帳錢包模式下：

  1. 🎮 玩家 先將主錢包資金轉入遊戲錢包
  2. 🔐 遊戲商 使用轉入的資金進行遊戲
  3. 💰 下注和結算都在遊戲錢包內進行
  4. 📊 遊戲結束後可將餘額轉出至主錢包

文檔結構​

本文檔包含以下功能模組：

📗 遊戲商提供的 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": 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. 異常處理: 轉帳失敗時需要妥善處理並通知玩家