开发指南
最小接入路径
这一页给出从第一行代码到完成账务闭环的最短路径。先按顺序跑通主线，再回到后续章节补齐字段边界、异常处理、通知和对账。
接入主线
| 步骤 | 你要做什么 | 成功标准 | 下一步 |
|---|---|---|---|
| 1 | 准备环境材料 | 拿到 API 接入地址、API 凭据、Webhook 凭据、开放链与通知 URL | 实现签名 |
| 2 | 实现 HMAC 签名 | GET 和 POST 都能使用真实请求原文生成正确签名 | 获取充值地址 |
| 3 | 建立 OG 用户账本并取址 | 后端授权玩家，保存地址/链/资产；充值页自动展示地址二维码 | 独立接入两条资金流程 |
| 4 | 处理充值结果 | 玩家列表发现记录，按 txRef 幂等入账、等待或冲正 | 在同一条充值记录展示进度 |
| 5 | 提交新提现 | 保存唯一原单与预扣；校验平台受理事实并持久保存后，手机清空下一笔 | 保留本笔处理中的记录 |
| 6 | 同步历史与提现结果 | 玩家提现列表补充已受理记录，单笔查询/通知按原单结账一次 | 手机按原订单号更新同一条记录 |
| 7 | 建立持续补偿 | Webhook 持久提交后通知手机重读；断连/漏通知继续查询，与原账务共用幂等 | 上线前验收 |
两条账务规则
- 充值按
txRef处理同一笔业务。confirmed可入账一次，pending不改账，invalidated对已入账记录冲正一次。 - 提现按
withdrawOrderId维持同一笔预扣。提交、重试、查询和通知都围绕这个订单号；成功才确认扣款，明确的失败或退款终态才释放原预扣。
通知与查询的关系
Webhook 用于主动推送充值和提现事件；查询接口用于玩家页面轮询、异常补偿和定期对账。两者不是互相替代的关系：接收端应把 eventId、txRef、withdrawOrderId 写入同一套业务去重记录，先在本地事务里完成幂等处理，再返回正确回签。
手机历史一笔业务只显示一条：充值按 txRef，提现按 withdrawOrderId。OG 后端提交账务后，可通过自己实现的 SSE 或短轮询通知手机重读该玩家该网络的账本；Webhook 事件不能作为新的交易卡片追加。完整历史、未知提现及预扣都由 OG 持久保存，不依赖浏览器内存或一次平台列表。
查询通道轮询查询
玩家页面轮询、异常补偿和定时对账
读取按业务标识读取状态
使用 txRef 或 withdrawOrderId 查询最新结果
通知通道Webhook 推送
平台主动发送充值、提现进度和终态事件
接收按事件标识接收
使用 eventId 识别重复通知
汇合处理同一套本地去重与账务事务
统一完成入账、冲正、确认扣款或释放预扣
联调建议：先跑通签名、玩家准备和 Webhook 验签回签；分别验证充值入账、提现从提交到终态，以及两类历史和断连补偿，不以先发生充值作为提现接口前提。