整合文件

Client 平台接入

所有請求使用 X-Api-Key、X-Timestamp、X-Signature。簽名字串為 timestamp\\nMETHOD\\npath\\nsha256(body)，HMAC-SHA256 hex，時鐘偏移 ±300 秒。

1. POST /api/v1/client/channels/discover — 用 country / currency / filters 取得通道與收銀員。
2. 玩家選 channel 再選 cashier，進入金額頁。
3. POST /api/v1/client/checkout — 以 clientOrderRef 冪等建單，回 paymentUrl 與 expiresAt。
4. 新分頁打開連結；被攔截時提供文字按鈕。提醒連結會過期。
5. 收到 deposit-completed 回調後，可 POST /api/v1/client/verify 代驗證，或自行打 gocash /public/verify。

curl -X POST "$TERMINAL/api/v1/client/channels/discover" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d '{"type":"deposit","country":"HK","currency":"CNY"}'

curl -X POST "$TERMINAL/api/v1/client/checkout" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d '{
    "clientOrderRef":"sess-uuid",
    "type":"deposit",
    "amountMinor":50000,
    "currency":"CNY",
    "country":"HK",
    "channelId":"<channel uuid>",
    "cashierId":"<cashier uuid>",
    "userRef":"<player uuid>"
  }'

回調路徑與既有 Spark 合約相同，打到你設定的 callback_url： /api/internal/gocash/voucher-deposit 等。payload 使用你的訂單編號（clientOrderRef），不是 attempt id。

Cashier 收銀接入

收銀端不與平台交談。Terminal 用你的 HMAC 呼叫既有 session API；你用同一把密鑰回調 Terminal。

1. 接收 POST /api/internal/sessions。sparkSessionId = Terminal attempt id（att_…）。
2. 回傳 { id, url }，url 必須是可開啟的 http(s)。無效 URL 會觸發 failover。
3. 完成購券 / redeem 後回調 Terminal（相容路徑）：POST /api/internal/gocash/voucher-deposit，sessionId 仍為 attempt id。
4. Terminal 會把 verifySecret 存檔、轉發給平台，並可代打 gocash public verify。

{
  "sessionId": "att_...",
  "userId": "player-or-order-ref",
  "amountMinor": 50000,
  "currency": "CNY",
  "paymentMethod": "wechat",
  "voucherNo": "GC-...",
  "verifySecret": "XXXX-XXXX-XXXX-XXXX"
}