Licensee 實作需求

S2S 伺服器間認證

所有由 Game Provider 發送至 Licensee 的請求，由雙方後端服務直接互相呼叫。因此，Licensee 需要提供一套可驗證來源的認證機制，以確保請求確實來自授權的 Game Provider 系統。

在實際營運環境中，錢包操作（如扣款、入帳或取消交易）會直接影響玩家資金。如果沒有驗證請求來源，任何能夠存取該 API 的第三方都可能偽造交易請求，例如提交虛假的 credit 或 debit，造成資金風險。

在實務整合中，這類 API 通常使用 HTTP Header 攜帶客戶識別與簽章資訊，並透過共享密鑰或公私鑰機制進行驗證。許多線上博弈平台的錢包整合 API 亦採用相同模式，即由 Licensee 提供 API Endpoint，而 Game Provider 在呼叫時附帶簽章資料供對方驗證。

完成 S2S 認證後，Licensee 需要實作以下 API 以支援交易流程。

Game Service 持有資訊

當 Licensee 讓 Player 使用啟動遊戲流程取得的網址，Game Service 將建立資訊：

{
  "id": "Player-uniqueID",
  "currency": "USD",
  "playMode": "credit",
  "session": "<OPTIONAL>",
  "language": "<OPTIONAL>",
  "nickname": "<OPTIONAL>",
  "launch": {
    "mode": "direct",
    "licensee": "asia-platform-1",
    "agents": [
      // ... Agent Layer
    ],
    "gameId": "baccarat001",
    "units": [
      // ... Game Units
    ],
    "params": {
      "category": "vip",
      "campaign": "summer2026",
      // ...More Params
    }
  }
}

Licensee 可參考以上內容，與 Game Provider 協商HTTP Request應發送哪些負載。

---

API Define

Request

Game Provider 將會在 Body 包含以下資訊：

Debit 與 Credit 分開請求Debit 與 Credit 合併請求

{
  "walletTarget": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "amount": 1000.00
}

{
  "walletTarget": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "debit": 1000.00,
  "credit": 50
}

欄位	意義
walletTarget	本次請求對應錢包持有人，視 Licensee 要求，通常為 player.id 或 player.session 其一。細節請參考遊戲啟動流程
gameId	遊戲的識別碼
roundId	遊戲一回合的最小單位
currency	幣別代碼
amount ,bet, credit	操作金額，最高支援精度至小數後四點

更多資訊

以上欄位是 Game Provider 會包含的最少訊息，若 Licensee 無特別要求，僅會送出以上負載。
若 Licensee 需要 Game Provider 發送其他資料，將會在 context 附加內容：

{
  "walletTarget": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "amount": 1000.00,
  "context": {
    "aud": <Licensee Identifier>,
    /* 其他要求欄位 */
  }
}

context.aud 將會記載 Licensee 的 Identifier 供查核；其他資料則放置於 context.*

若需要 Game Provider 處理額外的欄位，請和 KAM 進行聯繫。

Response

Game Provider 對於 Response 無嚴格要求，但還是有最低限制的要求：

若 Licensee 不保證遊戲期間 Player 不會變動，需要包含 balance。

{
  "balance": 1000.00
} 

錯誤回應格式

下方定義 Licensee 在請求失敗時回傳的錯誤格式，與參考用的錯誤碼：

• 若 Licensee 已經有自訂錯誤碼，請提供給 Game Provider 進行處理。
• 若 Licensee 使用以下錯誤碼，但還需要擴充其他錯誤，請提供給 Game Provider 進行處理。
• error.reason 可留空字串。

{
  "code": "<ERROR_CODE>",
  "reason": "<ERROR_REASON>"
}

錯誤碼	類型	意義	Game Provider 處理
OK	Success	無錯誤	交易請求成功處理。
DEBIT_EXISTS	Complete	此下注交易已存在。	該交易以處理完成，不重複扣款。
CREDIT_EXISTS	Complete	此下注交易已存在。	該交易以處理完成，不重複入帳。
DEBIT_INSUFFICIENT_FUNDS	Complete	餘額不足，無法完成下注。	本次下注失敗；顯示餘額不足提示。
ERR_INVAILD_PARAMETER	Complete	請求參數錯誤。	本次請求失敗；顯示錯誤提示。
FATAL_UNAVAILABLE	Fatal	系統暫時無法處理請求，請稍後再試。	本次下注失敗；顯示系統暫時錯誤提示。
FATAL_SESSION_INVALID	Fatal	玩家登入狀態已失效，請重新登入。	本次請求失敗；顯示重新登入提示。
FATAL_SESSION_LOCKED	Fatal	玩家帳戶已被停用，請聯繫客服。	本次請求失敗；顯示帳戶被停用提示。

• Success：請求成功發出，且結果如同預期 (e.g. Player 發出下注請求，且下注成功)。
• Complete：請求成功發出，非預期結果，但是不屬於嚴重錯誤 (e.g. Player 發出下注請求，但因為餘額不足下注失敗)。
• Fatal：嚴重錯誤，Game Provider 應該立即中止 Player 的遊戲流程或拒絕 Player 的所有請求。
  1. Game Provider 會優先嘗試讓 Player 退出遊戲

POST /api/check

REQUIRED

餘額預留

Licensee 可於遊戲開始前將餘額 Deposit API 或是身份驗證的attributes帶入，並在遊戲結束時由 Game Provider 返還至 Licensee。
此模式建議使用於長局遊戲，且遊戲中不可隨意更動餘額的方式：Texas hold'em、Baccarat、BlackJack 等有加注邏輯的遊戲。
在該情況下，建議使用 player.session 與實作 /api/close 明確定義餘額保留的時長以及 Game Provider 如何餘額返還至 Licensee。

請 Licensee 與 KAM 聯繫

當玩家進入遊戲、重新連線，或在下注前需要確認餘額時，Game Provider 會呼叫此 API。

Licensee 在處理該請求時，應完成：

1. 驗證玩家身份是否存在於營運商系統中。若玩家不存在，Licensee 應回傳錯誤狀態，使 Game Provider 中止該玩家的遊戲流程。
2. 確認玩家帳戶是否允許遊戲交易。例如玩家可能因為風控、帳戶凍結、地區限制或資金問題而被禁止下注。
   若玩家不允許進行交易，Licensee 應回覆拒絕狀態。
3. 回傳玩家的當前餘額以及幣別資訊。此餘額將作為 Game Provider 顯示於遊戲畫面中的可用資金。

此 API 不涉及任何資金變動，僅用於確認玩家狀態與餘額。

POST /api/debit

REQUIRED

當玩家在遊戲中進行下注時，Game Provider 會發送請求至 Licensee 的錢包系統。

Licensee 在處理該請求時，應完成：

1. Game Provider 應該在請求欄位放置隨機值 (e.g. uuid 或是 nonce) 用以檢查重複下注。
   • 建議您根據希望檢查重複下注的時間長度進行設定，建議您使用可設定 TTL 的 Cache 機制。
   • 若一局遊戲時間是 30s，可以將 Game Provider 發送的 nonce 設定 TTL=30s，下一次遊戲開始時，允許使用過的 nonce 在新一局重新使用。
   • 如果希望 nonce 在一天內不重複，則將 nonce TTL 設定為 1 days。
2. 其次確認玩家餘額是否足夠。若餘額不足，Licensee 應拒絕該交易並回覆錯誤狀態。
3. 若餘額足夠，Licensee 應從玩家帳戶扣除指定金額，並將該交易記錄為一筆有效的下注交易。
4. 完成扣款後，Licensee 應回傳新的玩家餘額以及交易結果。Game Provider 將依此決定玩家是否成功下注。

POST /api/credit

REQUIRED

必定回覆

對於 Game Provider 的處理，若 Player 的 bet 請求已經成功，無論 Licensee 是否回覆 credit，即便失敗或超時，Game Provider 都會先從上一次的扣款金額重新處理。

• bet 必定使 Player 的餘額不變或減少。
• credit 必定使 Player 的餘額不變或增加。

Game Provider 會以此為基本邏輯處理遊戲流程。

在遊戲回合結束後，Game Provider 會根據遊戲結果計算派彩金額並發送 credit 請求。

Licensee 在處理該請求時，應完成：

1. 若同一筆 credit 請求因為網路問題被重送，系統必須避免重複入帳。(參考 debit 的重複下注)
2. 在 Mixed Settlement 模式中，每一筆 debit 通常對應一筆 credit 或 cancel。
3. 在 Gamewise Settlement 模式中，玩家可能在同一回合發送多次 debit，最後僅收到一次聚合的 credit。

無論結算模式如何，Licensee 都需要確保玩家餘額正確增加並回傳新的餘額資訊。

POST /api/cancel

OPTIONAL

此 API 用於取消先前成功執行的 debit 交易，並將扣除的資金退回玩家帳戶。

取消交易通常發生在以下情況：

1. 遊戲回合未能正常完成，例如遊戲服務故障或網路中斷。
2. 下注操作在邏輯上被判定為無效。
3. 遊戲系統在下注後發現狀態異常，需要回滾交易。

當 Licensee 收到 cancel 請求時，應找到對應的 debit 交易並確認該交易確實存在且尚未結算。若該 debit 已被取消或已完成結算，Licensee 應避免重複退款並回覆適當狀態。

是否需要 cancel，取決於交易時序與失敗模型。系統若能在下注前完全阻止重複請求，應盡量避免使用該 API。

• 在 debit 與 credit 進行重複下注的檢查。
• 回合判斷無效時使用，但是在電子遊戲的情境比較少。
• 玩家下注後、結算前斷線，明確定義此注是否應該繼續結算。

POST /api/promo_payout

OPTIONAL

此 API 用於發放促銷獎勵或活動獎金。

與 credit 不同，promo_payout 並不對應任何遊戲下注行為，而是由 Game Provider 或營運活動產生的獎勵。

• 玩家完成活動任務
• 排行榜獎勵
• 比賽或錦標賽獎金
• 行銷活動贈送的免費資金

Licensee 在收到此請求時，應將指定金額增加至玩家錢包並記錄該交易為促銷性質的入帳。由於促銷獎金通常涉及活動統計與財務追蹤，Licensee 的系統應能區分該類交易與一般遊戲派彩。

POST /api/close

OPTIONAL

此 API 用於通知 Licensee 某一遊戲回合已經結束。

在某些遊戲類型中，玩家可以在同一回合內進行多次下注，例如輪盤或百家樂。此時系統通常採用 Gamewise Settlement 模式，在回合結束時統一進行結算。

close API 的主要用途是讓 Licensee 的系統得知該遊戲回合已經完成，並可用於以下用途：

• 確認該回合相關交易已全部處理完成。
• 更新回合狀態或結算統計資料。
• 釋放與該回合相關的系統資源。

此 API 本身通常不涉及資金變動，但在營運系統中具有重要的狀態同步作用。

---