跳至主要内容

單一錢包 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 的唯一性
  • 測試網路異常和超時情況