資料模型與列舉

本頁是 運營商 API 與 錢包回調介面 中使用的線上類型（wire types）背後的欄位級規則。本頁講的是語義；每個介面精確的請求/響應結構見那兩份 API 參考文件。

金額與幣別

• 金額永遠是該幣別最小貨幣單位下的整數（例如 USD 的分）——絕不是浮點數。500 代表 $5.00。這條規則適用於任何出現金額的地方：TransactionRequest.amount、TransactionResponse.balance、餘額回調的 balance，以及兩個 API 和 shell 端橋接裡每一個 betAmountMinor/amountMinor/balanceMinor 欄位。
• currency 必須是大寫、3 個字母的 ISO-4217 代碼（例如 "USD"，而不是 "usd"）——平台的校驗器區分大小寫。格式錯誤或小寫的代碼會以 400 被拒絕。

TransactionType

type TransactionType = 'BET' | 'WIN' | 'ROLLBACK' | 'ADJUSTMENT'

BET、WIN、ROLLBACK 是你在實踐中會遇到的——由遊戲廠商的伺服端提交，並轉發到你的錢包回調介面。ADJUSTMENT 存在於平台的標準模型裡，對應一種罕見的、平台內部的 admin 操作（人工調整餘額）；處理方式和其他類型一致（按 direction 給定的方向套用 amount）。

TransactionRequest

你的 POST /v1/wallet/transaction 實現所接收到的請求體：

Field	Type	Notes
transactionId	string	由廠商產生。重試時原樣複用——這是你的實現必須據以做冪等判斷的錨點。
sessionToken	string	對你不透明——標識由你自己呼叫 POST /v1/operator/games/launch 所建立的 session。原樣透傳即可；沒有另外的 operatorId/playerRef 欄位需要你拿來做交叉核對。
type	TransactionType	'BET' | 'WIN' | 'ROLLBACK' | 'ADJUSTMENT'
roundId	string	將屬於同一回合的交易分組。
roundComplete	boolean	在結束該回合的那一筆 BET/WIN 上為 true。只對 BET/WIN 有意義；ROLLBACK/ADJUSTMENT 上會被忽略。
originalTransactionId	string?	僅當 type === 'ROLLBACK' 時出現——指向被沖正的那筆 BET 的 transactionId。其他所有類型都不會出現。
playerRef	string	你內部的玩家識別碼，與你傳給 launchGame 的那個相同。
amount	number（int64）	最小貨幣單位，>= 0。金額為零的 WIN（無派彩）是合法的。
currency	string	大寫 ISO-4217，與啟動該 session 時使用的幣別一致。
gameId	string	與該 session 對應的遊戲一致。
direction	'DEBIT' | 'CREDIT'?	僅 ADJUSTMENT 才會出現——表示餘額異動的方向。BET/WIN/ROLLBACK 不會出現（它們的方向由 type 隱含）。
metadata	object?	不透明，上限 8 KiB——見下文。

Metadata 與 jackpot 派彩

metadata 是廠商提供的 JSON 物件，平台會儲存並原樣轉發給你，不做任何解讀。它是選填的，平台在任何交易類型上都接受它——典型用法是把 jackpot 詳情附加到一筆 WIN 上。

• 必須是 JSON 物件——陣列、字串、數字或 null 會在到達你這裡之前就被平台拒絕。
• 上限 8 KiB。
• 平台從不讀取其中的任何欄位——你可以自行決定如何顯示或儲存它；沒有任何內容是你被要求要處理的。

// 這只是文件層面對 jackpot WIN 的 metadata 的一種慣例約定——
// 平台不會強制這個結構，你也不必強制。任何 JSON 物件都會被接受；
// 遇到無法識別的結構時，當作「沒有可顯示的內容」處理即可。
type JackpotMetadata = {
  jackpot?: {
    won: boolean
    tier?: string
    amountMinor?: number
    poolId?: string
  }
}

TransactionResponse

你的實現需要返回：

type ResponseStatus = 'OK' | 'DECLINED'
type TransactionResponse = { status: ResponseStatus; balance: number }

DECLINED 只在 BET 上才是合法結果（例如餘額不足，或超出你自己設定的下注限額）——這是正常的業務結果，不是錯誤。WIN、ROLLBACK、ADJUSTMENT 絕不能被拒絕：如果你無法套用其中一筆，請改用非 200 狀態碼回應，交給平台的重試/核對機制去處理——見錯誤與重試。

Session

這是 POST /v1/operator/games/launch 建立的映射，之後每一次錢包呼叫裡的 sessionToken 都會解析回這個映射：

type Session = {
  token: string
  playerRef: string
  operatorId: string
  providerId: string
  gameId: string
  currency: string
  language: string
  createdAt: string
  expiresAt: string
  demo: boolean
}

你永遠不會直接看到這個結構——它是平台伺服端的內部狀態。之所以在這裡記錄它，是因為 TransactionRequest 上每一個看起來應該被交叉核對的欄位（playerRef、gameId、currency）在到達你這裡之前，其實都已經依據它校驗過了。

回合歸屬

roundId 只在 (providerId, operatorId) 這對組合內保證唯一——同一個 roundId 字串完全可能存在於不同的運營商之下，或不同廠商的不同遊戲之下，彼此不會衝突。這就是為什麼 POST /v1/operator/rounds/replay 只在你自己的運營商租戶範圍內查找，也是為什麼你在 TransactionRequest 上收到的 roundId，只有和同一個請求裡的 gameId 搭配時才有意義。

帳本方向

玩家餘額變動量 = Σ(CREDIT) − Σ(DEBIT)。BET 是借記（debit），WIN 是貸記（credit），ROLLBACK 沖正一筆 BET（貸記退回），ADJUSTMENT 則顯式攜帶自己的方向。你不需要自己推導這個公式——它只是給你在對照平台預期時，用來理解你自己帳本的背景知識。