SSG Gaming

產品API 單一錢包與轉帳錢包

單一錢包與轉帳錢包

這是對接線上遊戲API時兩種錢包模式的技術對比:資金由誰保管、投注過程中有哪些網路呼叫、故障如何恢復,以及營運商一側需要開發什麼。

概覽對比

對比項單一錢包轉帳錢包
資金保管玩家餘額只存放在營運商資料庫,遊戲商不持有玩家資金。遊戲商儲存獨立的遊戲餘額,資金通過轉入、轉出介面流轉。
投注期間的呼叫每一次投注和派彩都會觸發對營運商的伺服器回呼(餘額、扣款、加款、回滾)。無。遊戲在遊戲商側餘額上執行,僅在轉入和轉出時產生呼叫。
可用性要求錢包介面必須響應每次回呼,通常需在數百毫秒內返回;一旦宕機,遊戲即中斷。僅轉帳時需要營運商線上;營運商系統短暫離線時,牌局仍可繼續。
一致性模型營運商帳本是即時的唯一事實來源,只需對帳牌局,無需對帳餘額。兩本帳僅在轉帳節點保持一致,需要按轉帳記錄對帳。
故障恢復逾時通過按交易ID冪等重試和回滾呼叫來處理。轉帳分兩階段:處理中,然後成功或失敗;結果未知時通過狀態查詢確認。
對接工作量較高。需自行開發並運維低延遲迴調服務,並實現冪等和帳本。較低。僅需呼叫三四個 REST 介面,無需處理入站流量的安全與擴容。
玩家體驗只有一個餘額,無需轉帳步驟,適合紅利、跨產品遊玩和即時餘額顯示。遊戲前轉入、結束後轉出,會有短暫延遲;玩家中途離開可能造成餘額滯留遊戲商。
適用場景擁有自有錢包或平台,並需嚴格掌控資金與行銷活動的營運商。希望快速上線,或尚無即時錢包服務的營運商。

單一錢包(無縫錢包)

在單一錢包(無縫錢包)模式下,營運商系統就是錢包。玩家下注時,SSG API 會呼叫你的回呼介面,你在自己的帳本中變更餘額並返回最新余額,資金始終不離開你的資料庫。

呼叫流程

PlayerOperatorSSG APIloop1. open game2. launch(playerId, token)3. launchUrl4. spin5. debit(txId, roundId, amount)6. OK, balance7. credit(txId, roundId, win)8. OK, balance9. rollback(txId) [on timeout]
  1. 啟動:營運商後端攜帶玩家ID和會話令牌向 SSG 請求遊戲連結。
  2. 投注:每一局 SSG 都會攜帶唯一 txId 呼叫 debit;你校驗餘額、寫入帳本並返回最新余額。
  3. 派彩:同一局結束後,SSG 呼叫 credit 加款(金額可為 0)。
  4. 故障:呼叫逾時時 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 呼叫。

呼叫流程

PlayerOperatorSSG APIplay1. transferIn(txId, amount)2. PENDING or SUCCESS3. launch(playerId)4. launchUrl5. spin (no callbacks to Operator)6. getBalance(playerId)7. balance8. transferOut(txId, all)9. SUCCESS, amount
  1. 轉入:營運商後端攜帶唯一 txId 和金額呼叫 transferIn,結果為處理中或成功。
  2. 遊戲:啟動遊戲。所有投注和派彩都只變更遊戲商側餘額,不會回呼營運商。
  3. 轉出:玩家離開時呼叫 transferOut 轉出全部餘額,成功後再記入營運商自己的帳本。
  4. 結果未知:轉帳呼叫逾時後,先用同一 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(轉帳錢包)執行每日對帳任務
  • 監控與告警:回呼延遲、錯誤率、處理中轉帳、滯留餘額

聯絡對接工程師

我們可以帶領你的工程師熟悉測試環境,並幫助你選擇適合平台的錢包模式。對接保證在七天內完成。

傳送郵件 Telegram 聯絡 返回產品API

sales@ssggaming.com