概覽對比
| 對比項 | 單一錢包 | 轉帳錢包 |
|---|---|---|
| 資金保管 | 玩家餘額只存放在營運商資料庫,遊戲商不持有玩家資金。 | 遊戲商儲存獨立的遊戲餘額,資金通過轉入、轉出介面流轉。 |
| 投注期間的呼叫 | 每一次投注和派彩都會觸發對營運商的伺服器回呼(餘額、扣款、加款、回滾)。 | 無。遊戲在遊戲商側餘額上執行,僅在轉入和轉出時產生呼叫。 |
| 可用性要求 | 錢包介面必須響應每次回呼,通常需在數百毫秒內返回;一旦宕機,遊戲即中斷。 | 僅轉帳時需要營運商線上;營運商系統短暫離線時,牌局仍可繼續。 |
| 一致性模型 | 營運商帳本是即時的唯一事實來源,只需對帳牌局,無需對帳餘額。 | 兩本帳僅在轉帳節點保持一致,需要按轉帳記錄對帳。 |
| 故障恢復 | 逾時通過按交易ID冪等重試和回滾呼叫來處理。 | 轉帳分兩階段:處理中,然後成功或失敗;結果未知時通過狀態查詢確認。 |
| 對接工作量 | 較高。需自行開發並運維低延遲迴調服務,並實現冪等和帳本。 | 較低。僅需呼叫三四個 REST 介面,無需處理入站流量的安全與擴容。 |
| 玩家體驗 | 只有一個餘額,無需轉帳步驟,適合紅利、跨產品遊玩和即時餘額顯示。 | 遊戲前轉入、結束後轉出,會有短暫延遲;玩家中途離開可能造成餘額滯留遊戲商。 |
| 適用場景 | 擁有自有錢包或平台,並需嚴格掌控資金與行銷活動的營運商。 | 希望快速上線,或尚無即時錢包服務的營運商。 |
單一錢包(無縫錢包)
在單一錢包(無縫錢包)模式下,營運商系統就是錢包。玩家下注時,SSG API 會呼叫你的回呼介面,你在自己的帳本中變更餘額並返回最新余額,資金始終不離開你的資料庫。
呼叫流程
- 啟動:營運商後端攜帶玩家ID和會話令牌向 SSG 請求遊戲連結。
- 投注:每一局 SSG 都會攜帶唯一 txId 呼叫 debit;你校驗餘額、寫入帳本並返回最新余額。
- 派彩:同一局結束後,SSG 呼叫 credit 加款(金額可為 0)。
- 故障:呼叫逾時時 SSG 會用同一 txId 重試,超過重試次數後傳送 rollback。
回呼方法(示例)
| 方法 | 用途 | 關鍵欄位 | 冪等 |
|---|---|---|---|
balance | 返回玩家當前餘額。 | playerId, currency | 是(只讀) |
debit | 下注:扣除金額。 | playerId, txId, roundId, gameId, amount, currency | 按 txId |
credit | 派彩:增加金額。 | playerId, txId, roundId, amount, currency | 按 txId |
rollback | 出現錯誤後,撤銷此前的扣款或加款。 | txId, refTxId | 按 txId |
debit 請求示例
{
"method": "debit",
"playerId": "p_839201",
"txId": "tx_20261007_000184",
"roundId": "r_77f3a1",
"gameId": "slots_fruit_01",
"currency": "MYR",
"amount": "2.50",
"ts": 1791338577,
"sign": "hex(HMAC-SHA256(secret, canonical))"
}響應示例
{
"status": "OK",
"txId": "tx_20261007_000184",
"balance": "97.50",
"currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
// DUPLICATE_TX (return original result), INTERNAL_ERROR錢包服務必須遵守的規則
- 冪等性
- 相同 txId 的 debit 或 credit 重複到達時,必須返回原結果,且不得再次變動資金。請在 txId 上建立唯一索引來保證。
- 帳本原子寫入
- 在同一個資料庫事務內完成餘額校驗、帳本插入和餘額更新,避免併發投注導致透支。
- 先收到回滾
- 原始 debit 逾時後,可能先收到一個你從未見過的 txId 的 rollback。請記錄一條標記,使隨後遲到的同 txId debit 被拒絕。
- 延遲預算
- 含網路耗時,目標 p99 低於 500 毫秒。回呼路徑只做一次索引讀取和一次寫入,報表查詢不要走這條路徑。
- 金額格式
- 金額使用十進位制字串或整數最小單位,禁止使用浮點數,並校驗幣種與玩家帳戶一致。
- 紅利與免費旋轉
- 免費旋轉表現為金額 0 的 debit,隨後是派彩的 credit。請在帳本中將紅利餘額與現金餘額分開。
- 安全
- 校驗對規範化請求計算的 HMAC-SHA256 簽名,拒絕過期時間戳,僅放行 SSG 源 IP,並要求 TLS 1.2 及以上。
- 對帳
- 按 roundId 將 SSG 的每日牌局報表與你的帳本逐筆對比,差異通常源於漏掉的回呼或回滾。
轉帳錢包
在轉帳錢包模式下,遊戲商為每位玩家儲存一份遊戲餘額。營運商後端在遊戲前轉入資金、遊戲後轉出資金。遊戲過程中不會回呼營運商系統,因此只需要發起出站 REST 呼叫。
呼叫流程
- 轉入:營運商後端攜帶唯一 txId 和金額呼叫 transferIn,結果為處理中或成功。
- 遊戲:啟動遊戲。所有投注和派彩都只變更遊戲商側餘額,不會回呼營運商。
- 轉出:玩家離開時呼叫 transferOut 轉出全部餘額,成功後再記入營運商自己的帳本。
- 結果未知:轉帳呼叫逾時後,先用同一 txId 呼叫 getTransferStatus 查詢,再決定後續操作。
介面方法(示例)
| 方法 | 用途 | 關鍵欄位 | 冪等 |
|---|---|---|---|
transferIn | 將資金從營運商錢包轉入玩家遊戲餘額。 | playerId, txId, amount, currency | 按 txId |
transferOut | 將遊戲餘額轉回營運商錢包。 | playerId, txId, amount | all | 按 txId |
getBalance | 查詢玩家遊戲餘額。 | playerId | 是(只讀) |
getTransferStatus | 返回某個 txId 的狀態:處理中、成功或失敗。 | txId | 是(只讀) |
營運商後端必須遵守的規則
- 一個意圖一個 txId
- 在首次呼叫前生成 txId,所有重試都複用它;在上一筆狀態確定之前,絕不要生成新的 txId。
- 先扣本地帳本
- 轉入時,先在自己的帳本中凍結該金額再呼叫 SSG,待狀態終態後確認或釋放。
- 清掃滯留餘額
- 執行定時任務,找出有遊戲餘額但沒有活躍會話的玩家並轉出,覆蓋中途關閉瀏覽器的情況。
- 流水與報表
- 由於即時看不到投注,請通過從 SSG 拉取的牌局報表來計算流水、紅利打碼和風控限額,而不是依賴回呼。
- 對帳
- 按 txId 將每筆轉入、轉出與 SSG 記錄核對,對超過逾時閾值仍處於處理中的記錄告警。
- 安全
- 使用 HMAC-SHA256 對請求籤名,僅通過 TLS 1.2 及以上呼叫,API 金鑰存放在金鑰管理系統,並限制可呼叫 SSG 的伺服器。
故障場景
| 場景 | 單一錢包 | 轉帳錢包 |
|---|---|---|
| 網路逾時 | 投注期間 SSG 會用同一 txId 重試,超過次數後傳送 rollback,營運商必須保證冪等。 | 僅轉帳受影響。用同一 txId 呼叫 getTransferStatus 查詢後再處理。 |
| 營運商系統宕機 | 玩家無法開始或繼續牌局,未完成牌局將被回滾。 | 玩家可用現有遊戲餘額繼續遊戲,新的轉帳會被阻止。 |
| 重複請求 | 按該 txId 返回已儲存的響應,不做任何變更。 | 按該 txId 返回已儲存的結果,不做任何變更。 |
| 玩家中途斷線 | 牌局在遊戲商側正常結束,並按常規傳送 credit。 | 牌局正常結束,資金留在遊戲餘額中,直到轉出或被清掃任務轉出。 |
| 餘額不一致 | 通常由遺漏的回呼或回滾造成,可按 roundId 對比牌局報表發現。 | 通常由滯留或處理中的轉帳造成,可按 txId 對比轉帳記錄發現。 |
如何選擇
在以下情況選擇單一錢包
- 你已有即時錢包或帳本服務。
- 需要體育、娛樂場和行銷活動共用同一個餘額。
- 需要即時投注資料來做風控、紅利打碼或責任博彩限額。
- 團隊能夠運維高可用、低延遲的服務。
在以下情況選擇轉帳錢包
- 希望以最少的開發量快速上線。
- 尚無即時錢包服務。
- 只希望發起出站呼叫,不想暴露並保護公網回呼介面。
- 可以接受餘額短暫滯留,並能執行清掃任務。
許多營運商先用轉帳錢包快速上線,待自有錢包服務就緒後再切換到單一錢包。歡迎諮詢如何分階段切換。
對接檢查清單
- 所有涉及資金的呼叫都在 txId 上建唯一索引並實現冪等處理
- HMAC 簽名校驗、時間戳容差和 IP 白名單
- 金額使用十進位制安全型別,並校驗幣種
- 在測試環境驗證逾時、重試和回滾,包括遲到的重試
- 按 roundId(單一錢包)或 txId(轉帳錢包)執行每日對帳任務
- 監控與告警:回呼延遲、錯誤率、處理中轉帳、滯留餘額
聯絡對接工程師
我們可以帶領你的工程師熟悉測試環境,並幫助你選擇適合平台的錢包模式。對接保證在七天內完成。
sales@ssggaming.com