資料模型與列舉

@moosehq/provider-sdk 和錢包 API 共用的線上型別，其欄位層級規則彙整於此頁。這裡講的是語義；確切的 TypeScript 型別宣告在 SDK 參考文件裡。

金額與貨幣

• 金額永遠是該貨幣最小單位的整數（例如 USD 的分）——絕不用浮點數。300 代表 $3.00。這條規則適用於每一個出現金額的地方：TransactionRequest.amount、TransactionResponse.balance、BalanceResponse.balance，以及 @moosehq/game-client-sdk 裡每一個 amountMinor/balanceMinor 欄位。
• currency 必須是大寫的 3 字母 ISO-4217 代碼（例如 "USD"，不是 "usd"）——平台的校驗器是區分大小寫的。格式錯誤或小寫代碼會被 400 拒絕。

TransactionType

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

平台的規範模型裡還存在第四個值 ADJUSTMENT，但在廠商可呼叫的端點上會被 400 拒絕——那是僅限管理員手動修正用的操作，不屬於你的接入範圍。

TransactionRequest

欄位	型別	說明
transactionId	string	由你生成。同一次邏輯嘗試的重試要原樣複用——這是冪等性的錨點。ProviderClient 內部的重試已經會自動這樣做。
sessionToken	string	標識 verifySession 校驗過的那個 session。線上格式裡沒有單獨的 operatorId 欄位——運營商是從這個 token 在伺服端解析出來的。
type	TransactionType	'BET' | 'WIN' | 'ROLLBACK'
roundId	string	用來分組同一局裡的所有交易。
roundComplete	boolean	BET/WIN 之中結束該局的那一筆設為 true。僅對 BET/WIN 有意義；ROLLBACK 忽略此欄位。
originalTransactionId	string?	type === 'ROLLBACK' 時必填（要撤銷的那筆 BET 的 transactionId）。其他類型一律禁止填寫（會被拒絕）。
playerRef	string	必須和 session 的玩家一致——平台會校驗。
amount	number（int64）	最小貨幣單位，>= 0。金額為零的 WIN（沒有派彩）是合法的。
currency	string	大寫 ISO-4217，必須和 session 的貨幣一致。
gameId	string	必須和 session 的遊戲一致。
metadata	object?	不透明，上限 8 KiB——見下方說明。

Metadata

metadata 是廠商提供的一個 JSON 物件，平台會儲存它並原樣、不加解讀地轉發給運營商。典型用法：在 WIN 上附加彩池細節（彩池 ID、等級、彩金金額）。

• 必須是 JSON物件——陣列、字串、數字或 null 都會被拒絕。
• 上限 8 KiB；超出會被 400 拒絕。
• 選填——沒有東西要附加時就省略。
• 平台從不讀取裡面的任何鍵。任何交易類型都可以帶上它，不限於 WIN。

// 一個文件層面的約定，用於 WIN 彩池獎金的 metadata——平台並不會
// 校驗這個結構，任何 JSON 物件都會被接受；這純粹是為了讓其他
// 日後可能讀取 WIN metadata 的工具有個共通的命名慣例。
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 依設計永遠不會被 declined：這兩種類型上的技術性失敗會表現為逾時/5xx，並透過同一套冪等機制重試，而不是變成業務性拒絕。

VerifySessionResponse

type VerifySessionConfig = {
  rtpProfile: string     // 純展示用標籤；平台不會解讀它
  minBetMinor: number
  maxBetMinor: number     // 0 表示無上限
  language: string        // BCP-47（例如 "en"、"zh-TW"），若運營商未指定則為 ""——請回退到你自己的預設值
}

type VerifySessionResponse = {
  playerRef: string
  gameId: string
  operatorId: string
  currency: string
  config: VerifySessionConfig
}

BalanceResponse 與 VerifyReplayResponse

type BalanceResponse = { balance: number } // 最小貨幣單位

type VerifyReplayResponse = {
  roundId: string   // 用這個去查你自己的回放儲存
  gameId: string
  playerRef: string
  currency: string
  language: string  // 和 VerifySessionConfig.language 使用相同的約定
}

機器人偵測摘要不屬於這套資料模型——它是直接從瀏覽器送出的（見 BehaviorReporter 和行為採集端點），完全不經過 @moosehq/provider-sdk，也不對應這份參考文件裡的任何型別。

平台 → 廠商回呼請求體

RevokeSessionRequest 以及免費旋轉發放/查詢/取消的請求體，都記錄在各自的路由頁面——見Session 撤銷回呼和免費旋轉回呼。