联调与上线

凭据与环境

平台为测试环境和生产环境分别交付一套：

项	说明
{API_URL}	平台 API 地址
商户 ID	请求头 X-Merchant-Id
密钥	签名用的 43 位 secret

商户需要向平台提供：

项	说明
钱包模式	单一钱包或转账钱包
币种	需要开通的币种
{MERCHANT_URL}	回调地址的 HTTPS origin。单一钱包必须提供；转账钱包需要对局结束通知时提供
return_url 范围	玩家退出游戏后可以返回的地址

• 测试环境的凭据不能用于生产环境，反之亦然。
• 密钥轮换时，平台会交付新的密钥，并告知新旧密钥的重叠期。重叠期内平台同时接受新旧密钥签名的请求；商户验证回调时也应同时接受新旧密钥。
• 密钥只放在服务端的密钥管理或环境变量中，不要写进代码仓库、前端或日志。

第一条请求

先调用 GET /v1/capabilities。这个接口只读，没有副作用，适合验证签名：

• 返回 200：签名正确，并能看到钱包模式和币种。
• 返回 401 AUTHENTICATION_FAILED：对照签名示例，逐行检查签名串。
• 返回 401 REQUEST_EXPIRED：服务器时钟偏差超过 300 秒，请开启 NTP。

单一钱包回调核验

单一钱包商户的回调接口，必须通过平台的自动核验后才能开通新业务。核验使用正式的签名和接口，不需要商户做额外开发，但会产生一笔真实的最小金额下注。

回调连接检查

步骤	平台请求	商户应返回
1	用错误签名查询一个随机的 transaction_id	401 AUTHENTICATION_FAILED
2	用正确签名查询同一个 ID	404 TRANSACTION_NOT_FOUND，retryable=false

两次都必须是标准的 JSON 错误格式。统一返回 404 页面、重定向、超时都不算通过。

业务能力核验

核验前请准备一个测试玩家，余额不少于该币种的最小单位（例如 decimal_scale=4 时为 0.0001）。

步骤	平台请求	商户应返回
1	用错误签名查询交易	401 AUTHENTICATION_FAILED
2	查询一个不存在的 transaction_id	404 TRANSACTION_NOT_FOUND
3	用过期的 X-Timestamp（超出 ±300 秒，签名正确）再查一次	401 REQUEST_EXPIRED
4	改变玩家余额：BET 最小单位金额，round_id=seamless-capability-probe-v1	201，status=SUCCEEDED，带 balance
5	查询第 4 步的交易	200，结果和余额与第 4 步相同
6	原样重发第 4 步	201，响应头 Idempotency-Replayed: true，余额与第 4 步相同
7	同一个 transaction_id，但 round_id 改为 seamless-capability-probe-v1-conflict	409 IDEMPOTENCY_CONFLICT
8	获取玩家余额	200，余额与第 4 步相同

核验会扣款

第 4 步是一笔真实的最小金额下注，会从测试玩家余额中扣除，平台不会为它派奖或退款。

上线检查清单

签名与安全

• [ ] 签名对最终发出的 body 字节计算，签名后不再重新序列化 JSON。
• [ ] 每次请求（包括重试）都使用新的 X-Timestamp 并重新签名。
• [ ] 服务器开启 NTP 时间同步。
• [ ] 日志中没有密钥、完整签名和启动地址。

资金

• [ ] 每笔转账或奖励都有稳定的 external_id，并且 Idempotency-Key 等于它。
• [ ] 超时、5xx、UNKNOWN 时按原 ID 查单或原样重发，从不换新 ID 重做。
• [ ] 以交易的 status 判断结果，而不是 HTTP 状态或余额差值。
• [ ] 金额使用十进制字符串，小数位不超过 decimal_scale。

单一钱包回调

• [ ] 按 transaction_id 永久去重；重放时返回首次结果和 Idempotency-Replayed: true。
• [ ] 余额变化、交易记录和终态在同一个数据库事务中提交。
• [ ] 余额不足返回 201 + FAILED + INSUFFICIENT_FUNDS，而不是错误格式。
• [ ] 响应回显 transaction_id、external_player_id、currency、kind、amount，data 中没有多余字段。
• [ ] 查单接口读取权威记录，查不到返回 404 TRANSACTION_NOT_FOUND。
• [ ] 退款校验累计金额不超过原下注。
• [ ] 对局结束通知按 event_id 去重。

注单

• [ ] 持久化 record-changes 的 next_cursor，按 record_id + revision 覆盖。
• [ ] 知道游标过期后如何重建。