开发指南
充值
选择合适的接口
| 你的场景 | 调用接口 | 结果与下一步 |
|---|---|---|
| 展示充值入口 | 获取充值地址 | 只传 playerId/chainId，保存地址、链名、链 ID、合约，展示对应网络和资产 |
玩家等待到账，还不知道 txRef | 按玩家查询充值 | 使用路径中的 playerId 和唯一 query chainId，展示状态，保存返回的 txRef |
| 复核已知充值、处理失效与恢复 | 查询单笔充值 | 用 txRef 查询当前已同步状态；已入账的充值也需持续复核 |
同一玩家、同一条链、同一 USDT 合约，在收款合约未更换时会复用地址。平台更换该链的 USDT 合约或收款合约后，以最新成功响应更新地址簿，不将地址永久不变作为业务前提。玩家注册时不必取址，可以在打开充值页时获取。
手机进入充值页或切换玩家/网络时，由 OG 后端自动获取或复用对应地址，使用同一地址生成二维码；页面日常刷新交易状态不反复取址。二维码可以只包含地址，玩家仍须在外部钱包核对网络、资产并填写金额。
玩家查询示意为 GET /v1/players/{playerId}/deposits?chainId={chainId}；路径按实际发送的转义形式签名，query 原样参与签名，body 为空。可以每隔几秒轮询。返回 200 + items:[] 时先核对玩家和链，再核对同步情况，不显示为“充值失败”。
此列表最多 1000 条、无下一页，是当前同步视图。它不提供精确链上时间、每笔历史充值地址，也不支持时间或地址筛选；当前地址不能代表全部旧记录。完整充值历史由 OG 持久保存；显示按链上先后排序时，在同一网络内精确比较区块号和日志序号，不把 Webhook 接收时间当作充值时间。详细边界见历史查询与分页。
入账、失效与恢复使用同一套记录
首次处理充值也要由接入方明确资金策略：参考包要求显式选择“查询复核后入账”。成功通知只创建持久复核任务；以当前可信查询结果、原 txRef 和本地版本条件更新，查询仍是同步快照，不承诺消除链重组风险。已消费充值失效且可用余额不足以冲正时，参考策略持久记录人工核查并阻止该账户新增预扣；不自动造欠款、不动其他订单的 held。其他负余额/冻结政策必须由接入方明确提供。
取址、建单与首次接收充值时，冻结环境、接入方、玩家、链、合约及资产精度；新配置只影响新业务。旧单查询与迟到通知按该单历史快照校验，不能使用当前合约替换旧单快照，也不能放行没有历史绑定的任意旧资产。
展示进度，不入账
核对玩家、链和合约后入账一次
已入账则冲正一次，未入账则继续不入账
只有单笔查询再次为 confirmed 才能恢复，仍使用原 txRef
- 验证通知签名，或通过签名请求取得查询结果；核对
playerId、环境chainId和登记tokenContract。资产不匹配的记录不得按 USDT 换算或入账。 - 按充值状态表处理。只有有效的
confirmed可以入账，pending只展示进度；invalidated对已入账记录冲正。 - 查询和通知共用同一份以
txRef为键的账务记录。已入账且未冲正的，不再入账；同一失效结果不重复冲正。金额使用字符串或高精度整数计算。
成功通知可能迟到。 deposit_confirmed 是生成时的快照，之后即使充值失效，旧通知仍可能到达。已经观察到 invalidated 或已经冲正时，不能因为再次收到成功通知就恢复入账。
恢复时先在本地账务事务之外调用单笔查询。只有查询为 confirmed，且玩家、链、合约和该笔记录一致，才允许恢复；查询失败、404、pending 或 invalidated 都不恢复。随后按 txRef 串行处理，或在事务内锁定记录并检查查询前记录的版本；版本已变则退出事务后重新复核，不能套用旧查询结果。
预期同一有效充值只保留一次入账结果。从 invalidated 恢复后仍用原 txRef，不等待新的成功通知。对账列表里消失也不能直接冲正；先单笔复核。重复或差异出现时，先查本地 txRef 记录及最新状态，再核对平台同步情况。