接入流程图

选择钱包模式

	单一钱包（SEAMLESS）	转账钱包（TRANSFER）
玩家余额在哪里	商户钱包	平台账本
下注与派奖	平台实时调用商户的改变余额接口	平台直接在平台账本上扣款和加款，不回调商户
商户需要实现的接口	获取余额、改变余额、查询交易、对局结束通知	对局结束通知（可选）
进入游戏前	直接启动	先转入余额
适用场景	已有成熟的玩家钱包	希望在平台维护游戏余额

一个商户只开通一种模式，可以通过 GET /v1/capabilities 的 wallet_mode 确认。

单一钱包

玩家           商户服务端                    平台                        游戏客户端
 │  打开游戏  →  │                            │                             │
 │              │ POST /v1/players  ────────→ │  创建或取得玩家               │
 │              │ ←──────────────── player_id │                             │
 │              │ POST /v1/launches ────────→ │  签发启动票据                 │
 │              │ ←─────────────── launch_url │                             │
 │  ←── 跳转或嵌入 launch_url ───────────────────────────────────────────────→ │
 │              │                            │ ←── 游戏客户端兑换票据并连接 ──│
 │              │ ←── GET  /v1/wallets/balance              （获取余额）    │
 │              │ ←── POST /v1/wallet-transactions  BET     （扣下注）      │
 │              │ ←── POST /v1/wallet-transactions  PAYOUT  （派奖，输局不发）│
 │              │ ←── POST /v1/round-events  ROUND_ENDED    （本局结束）    │
 │              │ ←── GET  /v1/wallet-transactions/{id}     （结果不明时查单）│

要点：

• 平台发出的每一笔资金请求都有固定的 transaction_id。商户必须按这个 ID 永久去重，重复收到时返回首次结果。
• 如果平台没有拿到明确结果，会用同一个 transaction_id 查单或重发，不会换新 ID。
• 输局只扣下注，不发零金额派奖。

转账钱包

商户服务端                                   平台                          游戏客户端
 │ POST /v1/players ────────────────────────→ │  创建或取得玩家                 │
 │ POST /v1/transfers  direction=IN ────────→ │  转入：平台余额增加              │
 │ ←────────────────── transaction_id, status │                               │
 │ POST /v1/launches ───────────────────────→ │  签发启动票据                   │
 │ ←───────────────────────────── launch_url  │ ←── 游戏中下注和派奖都在平台账本 ─│
 │ ←── POST /v1/round-events  （可选，本局结束）│                               │
 │ GET  /v1/wallets?player_id=... ──────────→ │  查询余额                       │
 │ POST /v1/transfers  direction=OUT ───────→ │  转出：平台余额减少              │
 │ GET  /v1/transactions?external_id=... ───→ │  结果不明时，用原 external_id 查单 │

要点：

• 转入和转出只改变平台账本。商户要根据 transaction_id 和终态，自行完成自己一侧的加款或扣款。
• 转出和游戏下注会争用同一份可用余额。如果还有未确认的下注，转出会被拒绝。
• 超时后先查单，不要换新的 external_id 重转。

断线与刷新

玩家断线或刷新页面后，由游戏客户端自己恢复会话，商户不需要再次调用 /v1/launches。只有玩家从商户页面重新进入游戏时，才需要签发新的启动地址。