核心概念
玩家余额只存在于你的系统中，Star Game 从不托管玩家资金：玩家投注时，平台请求你的钱包扣款（debit）；一局派奖时，请求你加款（credit）；扣款结果不确定时，请求你冲正（rollback）。金额是以十进制字符串表示的最小单位整数（"1500"），配合你在「商户控制台 → 接入」配置的币种和小数位。永远不使用浮点数。
玩家每次打开游戏时，你的 App 向你的后端申请一个启动码，并通过宿主桥（getConfig → code）交给游戏页面。平台通过 POST /players/authenticate 兑换它，且只兑换一次，从不保存。
- 不透明、随机、一次性。
- 有效期要短：≤ 5 分钟。
- 在你的系统里绑定到一名玩家；不要把 App 自己的访问令牌放进网址或
getConfig。
可重复使用的启动码（例如为了页面刷新后仍可进入）也能工作，但自测工具会把「一次性」作为建议项给出警告。
session_id
Section titled “session_id”authenticate 返回一个由你定义的 session_id。平台会在每一笔扣款中原样带回，你可以据此在玩家登出、被封禁或超出限额后拒绝新的投注（session_invalid、player_blocked、limit_exceeded）。
规则：
- 加款和冲正永远不校验会话。 已经进行的对局必须能结算，即使玩家在此期间登出或被封禁。
- 扣款或查余额请求带有会话时，请延长该会话。对仍在游戏中的玩家，平台至少每 20 分钟调用一次
balance，所以只看不下注的玩家会话也不会过期。
按 transaction_id 幂等
Section titled “按 transaction_id 幂等”每笔交易都带有全局唯一的 transaction_id（≤ 128 字符）。
- 重复的
transaction_id必须返回首次处理的结果（包括insufficient_funds这样的失败结果），并且绝不重复记账。 - 同一
transaction_id但type、player_id、amount、currency或reference_transaction_id不同时，返回duplicate_mismatch，不记账。 - 交易记录至少保留 180 天用于对账。
rollback 冲正 reference_transaction_id 指向的扣款：
| 你这边的情况 | 处理 | 返回 |
|---|---|---|
| 扣款已记账且未冲正 | 退款 | ok |
| 扣款已冲正，或当时就失败未记账 | 不动 | ok |
| 从未收到该扣款 | 为该交易号记录一条墓碑 | ok |
| 带墓碑的扣款之后才到达 | 不记账 | rolled_back |
对每一笔结果未知的扣款（超时、连接重置、5xx），平台都会发送冲正并持续重试，直到收到 ok。有了墓碑，双方一定会收敛一致，不需要翻对账单。
引用的扣款从未记账或已被冲正的 credit，返回 reference_not_found。
分段扣款（同一玩家一局多笔扣款）
Section titled “分段扣款（同一玩家一局多笔扣款）”下注期内，平台每隔几秒把新下的注合并扣一次，所以同一玩家在同一局里可能有多笔扣款：
lantern:59666:p_123:bet 第一段投注lantern:59666:p_123:bet:1 几秒后新下的注lantern:59666:p_123:bet:2 ...- 不要按局或「一人一局一笔」去重或拒绝。
- 每笔扣款各自独立：其中一笔可能被拒（
insufficient_funds）或被冲正，其余照常有效。 - 派彩
credit引用该玩家本局第一笔已记账的扣款，金额是本局全部已记账投注的合计派彩。 round_id把一局的所有交易归在一起，可用于你的客服工具。
POST /transactions 携带 1–500 笔交易（不会超过你配置的单批最大笔数）。
- 各项相互独立、不是原子的，你可以并行处理。
- 同一玩家的多项必须按数组顺序处理。
- 只有当每一项都有结果时才返回 HTTP 200；某一项失败不会让整批失败。
- 结果按请求顺序逐项返回。
- 平台对 HTTP 408、429、5xx 和超时使用相同的交易号重试，并遵守
Retry-After。 - 状态为
retry（暂时失败、未记账）的项会以同一交易号重发。 - 每次 HTTP 尝试都带新的
webhook-id和新签名；资金幂等键是transaction_id，不是webhook-id。 - 平台的并行请求数不会超过你设置的最大并发请求数。