开发指南
事件类型
每次通知只占下表一行。一个 type 只搭配一个 status，不能交叉组合。原 14 种 type 与新增 withdrawal_rejected 按对应场景发出，但不是同一条正文里的多个取值，也不能把查询状态 pending、invalidated 或查询里的 8 个提现状态当成这一条通知的可选 status。phase 只有 progress；写着“不出现”的行不会带 phase，也不发送 null 或 terminal。字段详情见接收交易通知。
“当前流程”表示普通人工提现流程可能产生；“已配置凭证流程”表示平台启用并同步了提现凭证核验后可能产生；“兼容”表示协议保留范围，平台未启用自动提现时不会发出 withdrawal_auto_sending。所有进度只记录，不改账；终态可能重复投递，不等于一次 HTTP 请求。refunded 是取消尚未广播提现的真实终态，不是兼容占位。
| 事件 · type | 状态与阶段 | 适用范围与处理 |
|---|---|---|
已发现充值deposit_detected | statusdeposit_detectedphaseprogress | 当前流程 记录进度，不入账 |
充值确认中deposit_confirming | statusdeposit_confirmingphaseprogress | 当前流程 记录确认数，不入账；确认数可为 0 |
充值生成时已确认deposit_confirmed | statusconfirmedphase不出现 | 当前流程 校验资产，按 |
提现已受理withdrawal_accepted | statusacceptedphaseprogress | 当前流程 保持预扣 |
提现监测中，不表示已经广播withdrawal_sending | statussendingphaseprogress | 当前流程 保持预扣 |
已观察到链上交易，或凭证流程进入确认withdrawal_confirming | statusconfirmingphaseprogress | 当前流程 保持预扣 |
提现需要人工复核withdrawal_held | statusheldphaseprogress | 当前流程 保持预扣 |
人工提现仍在处理，且不是受理、监测、确认或复核withdrawal_manual_pending | statusmanual_pendingphaseprogress | 当前流程 保持预扣，不表示尚未广播 |
自动提现处理中withdrawal_auto_sending | statusauto_sendingphaseprogress | 兼容 未启用时不会发出；发出后保持预扣 |
提现凭证校验中withdrawal_voucher_checking | statusvoucher_checkingphaseprogress | 已配置凭证流程 保持预扣 |
凭证未通过，订单未终结withdrawal_voucher_failed | statusvoucher_failedphaseprogress | 已配置凭证流程 保持预扣，不当作终态 |
提现成功，单笔含 txHash，多笔含 paymentDetailswithdrawal_succeeded | statussucceededphase不出现 | 当前流程 按 |
提现失败终结，不返回 txHashwithdrawal_failed | statusfailedphase不出现 | 当前流程 按 |
未广播提现已取消，订单以已退款终结withdrawal_refunded | statusrefundedphase不出现 | 当前流程 释放预扣一次，不表示链上转回 USDT |
提现受理前永久拒绝，含原因及额度快照withdrawal_rejected | statusrejectedphase不出现 | 已配置每日上限；兼容历史特殊通道 完整校验并绑定原单/scope 后专用事务一次释放 |
充值进度必含 confirmations 和 confirmationsRequired。充值确认的 status 是 confirmed，不是 deposit_confirmed，并且不带 phase 或确认数。提现进度必含 eventId、type、withdrawOrderId、amount、status、phase；confirmations、txHash、playerId、链和地址只在有值时出现。已配置凭证流程还可能带 requiredConfirmations、verificationStage、voucherTxHash、payerAddress、failureCode。
提现终态基础字段为 eventId、type、withdrawOrderId、amount、status，单笔成功另含 txHash；多笔付款成功可无顶层 txHash，须带 verificationStage=payments_succeeded 与完整 paymentDetails，失败或退款基础 5 字段。失败和退款不返回 txHash；旧付款终态都不返回 playerId 或 phase；withdrawal_rejected 必须带 playerId 且不带 phase。当本次终态快照保留非空凭证阶段时，成功、失败和退款终态都会附带 verificationStage 和原订单的 chainId、chainName、tokenContract、toAddress；voucherTxHash、failureCode、payerAddress 非空时返回，confirmations、requiredConfirmations 已知时返回。取消时可能保留 awaiting_proof 等尚未接管提现的凭证信息，取消响应也可带这些可选字段，不能假定退款通知恰好只有 5 字段。账务始终按 status；终态按本地原订单关联玩家。充值失效只通过查询 invalidated 表达，没有 deposit_failed 事件。
应答没有业务 JSON 字段。任一 HTTP 2xx 都可以，建议 200；恰好一个 X-Signature，签的是原请求，不签应答正文。正文可为空或短的 {}，不得超过 4096 字节。
充值恢复仍沿用原 txRef 和原成功事件 ID，不能只靠“收到新通知”判断恢复。预期重复事件和查询同时到达也只产生一次账务动作；不符时先查三种幂等标识是否混用，再核对本地事务和最新查询状态。