接收交易进度与结果 · OG 开发者中心

POSThttps://demo.staging.ewin-stg.com/notify

支付服务 → 接入方接收端

先验签，再处理并应答

接收端读取原始请求正文，按请求实际路径与 query 验签。完整处理步骤见配置端点。

接收说明

后端按通知更新同一笔业务，手机再读取你们自己的账本。每次只携带一个 type 和与它成对的一个 status；通知状态与查询状态分别按各自状态表处理。

接收时机

上线前实现并登记一个通知 URL 和独立通知凭据。同一个地址接收全部充值、提现进度和结果；/notify 仅是本页示例路径，不是让你调用的支付 API，登记 URL 不含 query。

接收步骤

保留原始请求 bytes。校验 Content-Type: application/json、唯一的 X-Access-Key、X-Timestamp、X-Signature，用通知凭据校验 300 秒时间窗与 METHOD|PATH|TIMESTAMP|QUERY|BODY 的 HMAC，QUERY 为空。验签前不处理业务，不把解析后重组的 JSON 当作签名原文。
严格校验对应事件的完整字段、类型及 type/status/phase 配对。按 eventId 识别重复通知，按 txRef 或 withdrawOrderId 锁定业务，核对玩家、登记链/合约和金额。
在持久事务中保存通知与账务结果，再在 5 秒内应答 HTTP 200。应答没有业务 JSON 字段，必须按下方应答头要求回签；只返回 200 不代表平台确认送达。保存失败不 ACK。

结果处理：按事件处理账务

通知	如何处理
deposit_detected、deposit_confirming（各为一条通知）	phase=progress，只展示确认进度，不入账
deposit_confirmed，status=confirmed	核对玩家、链、合约、金额和 txRef，再按你的入账策略处理一次
提现进度，phase=progress	更新展示，保留原预扣；不确认扣款、不释放预扣
withdrawal_succeeded，status=succeeded	按原订单确认扣款一次，不再次扣减可用余额
withdrawal_failed / withdrawal_refunded	按原订单释放预扣一次；refunded 表示取消后的账务结果，不表示链上自动退币
withdrawal_rejected，status=rejected	受理前明确拒绝，按下方独立事务核对后释放原预扣一次

提现进度 accepted、sending、confirming、held、manual_pending 都不是付款成功。sending 表示处理中、等待链上观察，不证明已广播；manual_pending 和 broadcast=false 也不能证明尚未广播。voucher_checking、voucher_failed 只用于已配置凭证流程，均非终态；auto_sending 仅用于兼容自动流程。进度可能跳过或迟到，不能覆盖已处理终态。

充值首次确认核对登记资产后按 txRef 入账。已失效或已冲正的充值须单笔查询确认当前仍为 confirmed 才能恢复，旧成功通知不是恢复证明；eventId 去重不能阻止查询驱动同一 txRef 的失效与恢复。未知订单、金额不符、同 ID 异文或终态冲突，保留原账并持久记录人工核查，不自动确认扣款或释放预扣。

字段和交易哈希

充值进度必含 eventId、type、playerId、chainName、chainId、txHash、logIndex、tokenContract、amount、status、blockNumber、txRef、phase、confirmations、confirmationsRequired。充值确认不带 phase 和确认计数。充值查询的 pending、invalidated 不是通知 status。

提现进度必含 eventId、type、withdrawOrderId、amount、status、phase；playerId、链/地址、确认数、txHash 与凭证信息只在有值时出现。

提现付款终态基础字段为 eventId、type、withdrawOrderId、amount、status，不带 playerId 或 phase。单笔成功另含 txHash；多笔付款成功可省略顶层 txHash，必须带 verificationStage=payments_succeeded 与 paymentDetails 完整事实。失败和退款不返回 txHash。当前快照保留非空凭证阶段时，成功、失败和退款终态都会附带 verificationStage 与原订单 chainId、chainName、tokenContract、toAddress；voucherTxHash、failureCode、payerAddress 非空时返回，confirmations、requiredConfirmations 已知时返回。退款可能保留 awaiting_proof，退款通知不能假定恰好只有 5 字段。账务按 status 处理，不能仅凭有无哈希判断结果。

每日上限拒绝通知

累计超过当日上限使用 USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED；若仍有剩余额度可减少金额，取消、失败或平台提额也可能提前恢复，以新申请的实际结果为准；没有足够剩余时可提示等待重置；单笔本身超过上限使用 REQUEST_AMOUNT_EXCEEDS_DAILY_LIMIT，应提示减少金额或联系平台，不能承诺明天相同金额可提。两者均 final=true、retryMode=new_order、accepted/broadcast/paymentInitiated=false。schemaVersion=2 是 JSON 格式版本，接收这类通知无需理解或启用其他通道。

quota 是拒绝发生时的历史快照，不是当前配置。spentBase 为当日已计入申请额，包含处理中和成功订单；reservedBase 为字符串 0、blocked=false，不表示没有在途提款。累计超限 retryAt=resetAt；单笔超限 retryAt/retryAfterSeconds 显式为 null。resetInSeconds 是生成快照时的秒数；晚到通知按 resetAt 减你方已校时后端的可信当前时间展示，最低为 0，不能从收件时重倒数。查看当前上限可调用查询每日上限接口，其 quota:null 表示明确不限额；拒绝通知自身的 quota 不为 null。

普通提交超限时仍可能只返回泛化 422。完整且已验签的拒绝通知，或原单 GET 200 返回的同一完整原文，才提供原单拒绝证据；旧泛化或损坏回执查询仍为 503。参数或链预校验错误可能没有拒绝通知，不能只等通知。严格校验全部包络并从可信配置绑定 environment/accessNamespace（scope）、原订单/玩家、登记链/合约、地址、金额、资产精度和事件派生 ID；accessNamespace 不是 API Access Key。只有没有受理、凭证或付款证据的接入方本地原预扣状态 held 才能转为 released 一次（不是平台 status=held），不额外加款。原 bytes、摘要、decisionId/eventId 和账务同事务提交后回签；不能只凭 code、final、HTTP 状态或当前额度查询释放。

通知可先于提交响应到达；重复、并发、重启后重投及原单查询共用一次释放事务，重复仍验签回签。晚到 422/503 不撤销已完成的拒绝处理。已拒绝原单不会因午夜、提额或清空重开；玩家主动新申请才用新单号。不自动排队付款，不发送额度重置通知。历史特殊通道的完整拒绝正文仍按首次保存契约处理，可能保留独立跨日占用或人工阻断，不改变当前每日上限查询语义。

失败与重试、补查与排查

通知可能重复、乱序或跳过中间进度。验签失败返回非 2xx 且不改账；事务失败不回签，保留任务重试。待投递事件跨重启保留，但首次历史观察、升级前记录及源同步仍可能有覆盖缺口，须用原单查询和对账补偿，不能承诺无限可靠投递。

提现终态含拒绝在累计 3 次确定投递失败后停止自动重试，前两次退避约 1 秒、2 秒。HTTP 发送尝试开始后的网络失败、发送超时、非 2xx、回签缺失/重复/错误、应答超过 4096 字节等消耗失败次数；发送端不跟随重定向。DNS 解析失败或超时属于发送前阻塞，不计失败；发送前检查失败、配置阻塞、进程取消或尝试结果尚未确认的“结果未知”不消耗失败次数。不能把发送超时一律视为未知；充值通知和提现进度没有相同的 3 次上限。缺通知继续原单补查；拒单查不到完整原文时请平台核查，不释放预扣。

预期重复处理只更新同一笔业务，持久提交后平台记录送达。失败先查通知 URL、独立凭据、请求/应答原文和回签，再查收件箱事务、原单身份及平台投递记录。

事件与状态对照

每次请求只对应下面一行。一个 type 只搭配一个 status；phase 只有 progress，且只出现在进度行。充值确认、提现终态和拒绝不返回 phase。各事件按实际场景与已开放能力发出，不是把查询状态放进同一条通知。

事件 · type	状态与阶段	适用范围与处理
发现充值`deposit_detected`	status`deposit_detected`phase`progress`	普通流程 / 充值进度已发现、尚未进入确认。记录 txRef，不入账。
充值确认中`deposit_confirming`	status`deposit_confirming`phase`progress`	普通流程 / 充值进度确认数增加中，尚未确认。只更新展示，不入账。
充值已确认`deposit_confirmed`	status`confirmed`phase不出现	普通流程 / 充值确认生成通知时已确认，status 为 confirmed，不返回 phase。核对资产后按 txRef 入账；失效或冲正后先单笔查询。
提现已受理`withdrawal_accepted`	status`accepted`phase`progress`	普通流程 / 提现进度提现仍在受理。保留预扣，等待后续结果。
提现监测中`withdrawal_sending`	status`sending`phase`progress`	普通流程 / 提现进度正在监测提现，不表示已经广播。保留预扣。
提现确认中`withdrawal_confirming`	status`confirming`phase`progress`	普通流程 / 提现进度已观察到链上交易，或凭证流程进入确认。保留预扣。
等待人工核查`withdrawal_held`	status`held`phase`progress`	普通流程 / 提现进度需要人工复核。保留预扣。
人工提现处理中`withdrawal_manual_pending`	status`manual_pending`phase`progress`	普通流程 / 提现进度人工提现仍在处理，且不属于受理、监测、确认或复核。保留预扣，不表示尚未广播。
自动提现处理中`withdrawal_auto_sending`	status`auto_sending`phase`progress`	兼容自动流程 / 提现进度兼容自动流程。平台未启用自动提现时不会发出。发出后保留预扣。
提现凭证核验中`withdrawal_voucher_checking`	status`voucher_checking`phase`progress`	已配置凭证流程 / 提现进度已配置凭证流程，正在核验。保留预扣，有哈希也不确认扣款。
提现凭证未通过`withdrawal_voucher_failed`	status`voucher_failed`phase`progress`	已配置凭证流程 / 提现进度凭证未通过，预扣保持，不是提现终态。
提现成功`withdrawal_succeeded`	status`succeeded`phase不出现	普通流程 / 提现终态提现成功；单笔带 txHash，多笔带 paymentDetails，不返回 phase。按 withdrawOrderId 确认扣款一次。
提现失败`withdrawal_failed`	status`failed`phase不出现	普通流程 / 提现终态提现失败，不返回 txHash 或 phase。按订单释放预扣一次；不同于提交 HTTP 422。
已作退款结算`withdrawal_refunded`	status`refunded`phase不出现	取消未广播提现 / 终态取消尚未广播的提现，或退款结算。不返回 txHash 或 phase。释放预扣一次，不是链上退回 USDT。
永久拒绝`withdrawal_rejected`	status`rejected`phase不出现	当前每日上限拒绝 / 历史兼容完整拒绝严格校验并绑定原单和可信接入身份；无受理付款证据才在持久事务中一次释放本地预扣，冲突隔离。

请求头

请求头	说明
`X-Access-Key`必填	通知专用 Access Key。你的接收端应核对平台为本环境配置的通知标识，不要默认使用 API Access Key。
`X-Timestamp`必填	本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。
`X-Signature`必填	通知请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用通知密钥签 METHOD\|PATH\|TIMESTAMP\|QUERY\|BODY；验证通过后，用同一请求原文生成回签。API 与通知密钥独立配置。

通知正文

application/json · 按 type 选择对应通知结构

正文须符合以下一种结构。

充值进度

充值进度，只展示确认情况，不入账或冲正。一条通知只有一对同名的 type 和 status，phase 固定为 progress，并必含确认数。确认数变化可能产生新 eventId，但不保证每次数值变化都送达。重复通知仍需验签并回签。

eventIdstring必含

本条通知的唯一标识。整段保存并去重，不解析其内容；可能包含冒号。同一事件重试保留此值和正文，但时间戳及签名会更新。业务账务还需按 txRef 或 withdrawOrderId 去重。

最少字符数：1

typestring必含

充值进度的事件类型。一条通知只取其中一个，并与 status 同名成对。

取值：deposit_detected、deposit_confirming；一条通知只取其中一个，并与 status 成对

playerIdstring必含

你们业务系统中的稳定玩家标识，与获取充值地址时保持一致。非空且不含空白或控制字符；建议使用简短 ASCII 标识，并避免 /，便于跨接口使用。

最少字符数：1

chainNamestring必含

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

chainIdstring必含

本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。

最少字符数：1

txHashstring必含

充值交易哈希。EVM 为小写 0x 加 64 个十六进制字符；TRON 为不带前缀的 64 个小写十六进制字符。用于查看交易，不单独作为充值去重键；同一交易可能有多笔充值。

格式规则：^(0x)?[0-9a-f]{64}$

logIndexstring必含

这笔转入在交易中的日志序号，以无前导零的十进制字符串返回，允许 0，范围 0–18446744073709551615，最多 20 位。与交易哈希一起区分同一交易中的不同充值；排序或比较须使用大整数。

格式规则：^(0|[1-9][0-9]{0,19})$；最少字符数：1；最多字符数：20；字符串表示的数值下限：0；字符串表示的数值上限：18446744073709551615；pattern 只校验规范十进制写法与位数；自定义整数上下界不是标准 JSON Schema 校验，须用大整数精确比较，不使用浮点。

tokenContractstring必含

这笔已同步充值的代币合约。仅接纳登记链名、链 ID 与代币合约匹配的记录；错误资产可能不会出现。入账前仍须逐笔核对 chainId 和本字段，再按登记资产精度换算；缺记录时先检查转账网络、合约和同步覆盖。

最少字符数：1

amountstring必含

充值记录中的代币最小单位正整数字符串，范围 1 到 uint256 最大值（2^256-1）。先核对链与合约，再按环境资产精度换算；使用任意精度整数或十进制库，不用浮点。例：USDT 精度为 6 时，1000000 表示 1 USDT。

格式规则：

^(?:[1-9][0-9]{0,76}|10[0-9]{76}|11[0-4][0-9]{75}|115[0-6][0-9]{74}|1157[0-8][0-9]{73}|11579[0-1][0-9]{72}|1157920[0-7][0-9]{70}|11579208[0-8][0-9]{69}|115792089[0-1][0-9]{68}|1157920892[0-2][0-9]{67}|11579208923[0-6][0-9]{66}|115792089237[0-2][0-9]{65}|11579208923730[0-9]{64}|11579208923731[0-5][0-9]{63}|1157920892373160[0-9]{62}|1157920892373161[0-8][0-9]{61}|11579208923731619[0-4][0-9]{60}|115792089237316195[0-3][0-9]{59}|1157920892373161954[0-1][0-9]{58}|11579208923731619542[0-2][0-9]{57}|115792089237316195423[0-4][0-9]{56}|1157920892373161954235[0-6][0-9]{55}|115792089237316195423570[0-8][0-9]{53}|1157920892373161954235709[0-7][0-9]{52}|11579208923731619542357098[0-4][0-9]{51}|11579208923731619542357098500[0-7][0-9]{48}|115792089237316195423570985008[0-5][0-9]{47}|1157920892373161954235709850086[0-7][0-9]{46}|11579208923731619542357098500868[0-6][0-9]{45}|115792089237316195423570985008687[0-8][0-9]{44}|11579208923731619542357098500868790[0-6][0-9]{42}|115792089237316195423570985008687907[0-7][0-9]{41}|1157920892373161954235709850086879078[0-4][0-9]{40}|11579208923731619542357098500868790785[0-2][0-9]{39}|115792089237316195423570985008687907853[0-1][0-9]{38}|1157920892373161954235709850086879078532[0-5][0-9]{37}|11579208923731619542357098500868790785326[0-8][0-9]{36}|115792089237316195423570985008687907853269[0-8][0-9]{35}|1157920892373161954235709850086879078532699[0-7][0-9]{34}|11579208923731619542357098500868790785326998[0-3][0-9]{33}|115792089237316195423570985008687907853269984[0-5][0-9]{32}|1157920892373161954235709850086879078532699846[0-5][0-9]{31}|11579208923731619542357098500868790785326998466[0-4][0-9]{30}|115792089237316195423570985008687907853269984665[0-5][0-9]{29}|1157920892373161954235709850086879078532699846656[0-3][0-9]{28}|115792089237316195423570985008687907853269984665640[0-4][0-9]{26}|1157920892373161954235709850086879078532699846656405[0-5][0-9]{25}|11579208923731619542357098500868790785326998466564056[0-3][0-9]{24}|1157920892373161954235709850086879078532699846656405640[0-2][0-9]{22}|11579208923731619542357098500868790785326998466564056403[0-8][0-9]{21}|115792089237316195423570985008687907853269984665640564039[0-3][0-9]{20}|1157920892373161954235709850086879078532699846656405640394[0-4][0-9]{19}|11579208923731619542357098500868790785326998466564056403945[0-6][0-9]{18}|115792089237316195423570985008687907853269984665640564039457[0-4][0-9]{17}|1157920892373161954235709850086879078532699846656405640394575[0-7][0-9]{16}|11579208923731619542357098500868790785326998466564056403945758[0-3][0-9]{15}|11579208923731619542357098500868790785326998466564056403945758400[0-6][0-9]{12}|115792089237316195423570985008687907853269984665640564039457584007[0-8][0-9]{11}|11579208923731619542357098500868790785326998466564056403945758400790[0-9]{10}|11579208923731619542357098500868790785326998466564056403945758400791[0-2][0-9]{9}|1157920892373161954235709850086879078532699846656405640394575840079130[0-9]{8}|1157920892373161954235709850086879078532699846656405640394575840079131[0-1][0-9]{7}|11579208923731619542357098500868790785326998466564056403945758400791312[0-8][0-9]{6}|115792089237316195423570985008687907853269984665640564039457584007913129[0-5][0-9]{5}|1157920892373161954235709850086879078532699846656405640394575840079131296[0-2][0-9]{4}|11579208923731619542357098500868790785326998466564056403945758400791312963[0-8][0-9]{3}|115792089237316195423570985008687907853269984665640564039457584007913129639[0-8][0-9]{2}|1157920892373161954235709850086879078532699846656405640394575840079131296399[0-2][0-9]{1}|11579208923731619542357098500868790785326998466564056403945758400791312963993[0-4]|115792089237316195423570985008687907853269984665640564039457584007913129639935)$

；最多字符数：78；字符串表示的数值下限：1；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935

statusstring必含

与本条 type 同名的唯一状态。它是充值进度，对应查询里的 pending，不能直接入账。

取值：deposit_detected、deposit_confirming；一条通知只取其中一个，并与 type 成对

blockNumberstring必含

首次观察到充值所在的区块高度，后续保留首次值，仅供展示，不作为充值去重键或重组后的最新位置。使用无前导零的十进制字符串，允许 0，范围 0–18446744073709551615，最多 20 位；排序或比较须使用大整数。

txRefstring必含

支付服务返回的充值唯一标识，直接保存，不自行计算。入账、查询、冲正和恢复都使用它。同一交易不同 logIndex 是不同充值，不能仅按 txHash 去重。

最少字符数：1

phasestring必含

固定为 progress，只更新进度，不改变余额。

取值：progress

confirmationsinteger必含

生成通知时已观察到的确认数。允许为 0，deposit_confirming 也可能返回 0；不能只凭此数入账。

最小值：0

confirmationsRequiredinteger必含

该链的目标确认数。以环境配置为准，不要把示例 12 写死。等待充值 confirmed 后再按规则入账。

最小值：1

不接受未定义字段。

正文须符合以下一种结构。

deposit_detected

typestring必含

取值：deposit_detected

statusstring必含

取值：deposit_detected

deposit_confirming

typestring必含

取值：deposit_confirming

statusstring必含

取值：deposit_confirming

deposit_confirmed

充值在生成通知时已确认，不保证接收时仍有效。先核对玩家、链和 USDT 合约，再按 txRef 防止重复入账。已排队通知不会因后续失效而撤销；如果该 txRef 已记录失效或已冲正，必须先单笔查询，只有当前为 confirmed 且资产匹配才恢复入账。查询失败、404、pending 或 invalidated 都不恢复。

查看完整说明

查询和通知应按同一 txRef 串行处理；若使用本地事务版本检查，查询放在事务外，版本改变后重新查询。已入账且未冲正的不重复入账，旧结果不能覆盖新状态。恢复时不保证另发成功通知，应以查询复核。status 固定为 confirmed，不是 deposit_confirmed。本通知不返回 phase 或确认数字段。

eventIdstring必含

最少字符数：1

typestring必含

固定为 deposit_confirmed，表示生成通知时充值已确认。失效或冲正后收到旧通知，须先查询再判断是否恢复。

取值：deposit_confirmed

playerIdstring必含

你们业务系统中的稳定玩家标识，与获取充值地址时保持一致。非空且不含空白或控制字符；建议使用简短 ASCII 标识，并避免 /，便于跨接口使用。

最少字符数：1

chainNamestring必含

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

chainIdstring必含

本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。

最少字符数：1

txHashstring必含

格式规则：^(0x)?[0-9a-f]{64}$

logIndexstring必含

tokenContractstring必含

最少字符数：1

amountstring必含

格式规则：

^(?:[1-9][0-9]{0,76}|10[0-9]{76}|11[0-4][0-9]{75}|115[0-6][0-9]{74}|1157[0-8][0-9]{73}|11579[0-1][0-9]{72}|1157920[0-7][0-9]{70}|11579208[0-8][0-9]{69}|115792089[0-1][0-9]{68}|1157920892[0-2][0-9]{67}|11579208923[0-6][0-9]{66}|115792089237[0-2][0-9]{65}|11579208923730[0-9]{64}|11579208923731[0-5][0-9]{63}|1157920892373160[0-9]{62}|1157920892373161[0-8][0-9]{61}|11579208923731619[0-4][0-9]{60}|115792089237316195[0-3][0-9]{59}|1157920892373161954[0-1][0-9]{58}|11579208923731619542[0-2][0-9]{57}|115792089237316195423[0-4][0-9]{56}|1157920892373161954235[0-6][0-9]{55}|115792089237316195423570[0-8][0-9]{53}|1157920892373161954235709[0-7][0-9]{52}|11579208923731619542357098[0-4][0-9]{51}|11579208923731619542357098500[0-7][0-9]{48}|115792089237316195423570985008[0-5][0-9]{47}|1157920892373161954235709850086[0-7][0-9]{46}|11579208923731619542357098500868[0-6][0-9]{45}|115792089237316195423570985008687[0-8][0-9]{44}|11579208923731619542357098500868790[0-6][0-9]{42}|115792089237316195423570985008687907[0-7][0-9]{41}|1157920892373161954235709850086879078[0-4][0-9]{40}|11579208923731619542357098500868790785[0-2][0-9]{39}|115792089237316195423570985008687907853[0-1][0-9]{38}|1157920892373161954235709850086879078532[0-5][0-9]{37}|11579208923731619542357098500868790785326[0-8][0-9]{36}|115792089237316195423570985008687907853269[0-8][0-9]{35}|1157920892373161954235709850086879078532699[0-7][0-9]{34}|11579208923731619542357098500868790785326998[0-3][0-9]{33}|115792089237316195423570985008687907853269984[0-5][0-9]{32}|1157920892373161954235709850086879078532699846[0-5][0-9]{31}|11579208923731619542357098500868790785326998466[0-4][0-9]{30}|115792089237316195423570985008687907853269984665[0-5][0-9]{29}|1157920892373161954235709850086879078532699846656[0-3][0-9]{28}|115792089237316195423570985008687907853269984665640[0-4][0-9]{26}|1157920892373161954235709850086879078532699846656405[0-5][0-9]{25}|11579208923731619542357098500868790785326998466564056[0-3][0-9]{24}|1157920892373161954235709850086879078532699846656405640[0-2][0-9]{22}|11579208923731619542357098500868790785326998466564056403[0-8][0-9]{21}|115792089237316195423570985008687907853269984665640564039[0-3][0-9]{20}|1157920892373161954235709850086879078532699846656405640394[0-4][0-9]{19}|11579208923731619542357098500868790785326998466564056403945[0-6][0-9]{18}|115792089237316195423570985008687907853269984665640564039457[0-4][0-9]{17}|1157920892373161954235709850086879078532699846656405640394575[0-7][0-9]{16}|11579208923731619542357098500868790785326998466564056403945758[0-3][0-9]{15}|11579208923731619542357098500868790785326998466564056403945758400[0-6][0-9]{12}|115792089237316195423570985008687907853269984665640564039457584007[0-8][0-9]{11}|11579208923731619542357098500868790785326998466564056403945758400790[0-9]{10}|11579208923731619542357098500868790785326998466564056403945758400791[0-2][0-9]{9}|1157920892373161954235709850086879078532699846656405640394575840079130[0-9]{8}|1157920892373161954235709850086879078532699846656405640394575840079131[0-1][0-9]{7}|11579208923731619542357098500868790785326998466564056403945758400791312[0-8][0-9]{6}|115792089237316195423570985008687907853269984665640564039457584007913129[0-5][0-9]{5}|1157920892373161954235709850086879078532699846656405640394575840079131296[0-2][0-9]{4}|11579208923731619542357098500868790785326998466564056403945758400791312963[0-8][0-9]{3}|115792089237316195423570985008687907853269984665640564039457584007913129639[0-8][0-9]{2}|1157920892373161954235709850086879078532699846656405640394575840079131296399[0-2][0-9]{1}|11579208923731619542357098500868790785326998466564056403945758400791312963993[0-4]|115792089237316195423570985008687907853269984665640564039457584007913129639935)$

；最多字符数：78；字符串表示的数值下限：1；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935

statusstring必含

固定为 confirmed，是生成通知时的状态；当前有效性和恢复规则见本类型说明。

取值：confirmed

blockNumberstring必含

txRefstring必含

支付服务返回的充值唯一标识，直接保存，不自行计算。入账、查询、冲正和恢复都使用它。同一交易不同 logIndex 是不同充值，不能仅按 txHash 去重。

最少字符数：1

不接受未定义字段。

提现进度

提现进度，只更新展示并保留预扣。一条通知只有一对 type/status，phase 固定为 progress。有交易哈希或确认数也不能确认扣款。通知可能重复或乱序，终态后的旧进度不能使订单回到处理中。confirmations、txHash、playerId、链和地址已知才返回；已配置凭证流程还可带 requiredConfirmations、verificationStage、voucherTxHash、failureCode、payerAddress。当前凭证尝试以查询结果为准。

eventIdstring必含

最少字符数：1

typestring必含

提现进度的事件类型。一条通知只取下列一个值，并且必须与 status 成对，不能任意组合。全部进度都保持预扣。

取值：withdrawal_accepted、withdrawal_sending、withdrawal_confirming、withdrawal_held、withdrawal_manual_pending、withdrawal_auto_sending、withdrawal_voucher_checking、withdrawal_voucher_failed；一条通知只取其中一个，并与 status 成对

withdrawOrderIdstring必含

你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。

格式规则：^[0-9]{30}$

amountstring必含

代币最小单位的正整数字符串。按当前环境的资产精度换算，使用整数或高精度十进制计算，禁止浮点。例：若 USDT 精度为 6，1 USDT 填 "1000000"。提交提现不允许 0、前导零、小数或科学计数，数值不得超过 uint256。充值入账前先核对链和合约，不能把其他代币按 USDT 精度换算。

格式规则：^[1-9][0-9]{0,77}$；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935；pattern 只检查十进制写法与位数；还需用高精度整数比较数值上限，不能使用浮点比较。

statusstring必含

与本条 type 成对的唯一状态。一条通知不会返回多个 status。accepted、sending、confirming 只用于进度，查询接口不返回它们；sending 不表示已经广播。

取值：accepted、sending、confirming、held、manual_pending、auto_sending、voucher_checking、voucher_failed；一条通知只取其中一个，并与 type 成对

phasestring必含

固定为 progress，不确认扣款或释放预扣。

取值：progress

confirmationsinteger可省略

生成通知时已观察到的确认数，允许为 0。仅用于展示，不是提现成功判断条件。

最小值：0

txHashstring可省略

进度中已观察到的交易哈希文本，有值时才返回。它尚不足以证明提现成功，也不能单凭其格式判断链或执行扣款。

最少字符数：1

playerIdstring可省略

你们业务系统中的稳定玩家标识，与获取充值地址时保持一致。非空且不含空白或控制字符；建议使用简短 ASCII 标识，并避免 /，便于跨接口使用。

最少字符数：1

chainNamestring可省略

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

chainIdstring可省略

本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。

最少字符数：1

tokenContractstring可省略

该环境登记的 USDT 合约。取址和提现响应由平台返回，请与链一起保存；请求不填写此字段。EVM 合约使用小写十六进制，TRON 使用区分大小写的 Base58Check。是否开放某条链，以平台提供的环境信息为准。

最少字符数：1

toAddressstring可省略

提现收款地址，必须与所选链类型一致，不能是全零地址。EVM 接受 0x/0X 加 40 位十六进制并转为小写；TRON 接受 34 位 Base58Check，或 41 开头的 21 字节十六进制（可带 0x/0X），统一转为 Base58Check。不要把 TRON 地址转为小写。

最少字符数：1

requiredConfirmationsinteger可省略

已配置凭证流程的确认阈值，已知时返回；不是充值字段 confirmationsRequired。

最小值：1

verificationStagestring可省略

可选提现凭证阶段：awaiting_proof 等待录入哈希，verifying 核验中，confirming 等待确认，proof_failed 凭证未通过，succeeded 核验成功；payments_managed 多笔付款处理中，payments_succeeded 多笔付款全部完成。阶段用于解释提现进度，账务始终按 status；proof_failed 不释放预扣。仅平台已配置并实际同步该流程时返回。

取值：awaiting_proof、verifying、confirming、proof_failed、succeeded、payments_managed、payments_succeeded

voucherTxHashstring可省略

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

failureCodestring可省略

凭证核验的原因信息，有值时返回；voucher_failed 仍保持预扣。

最少字符数：1

payerAddressstring可省略

已同步的出款地址，有值时返回。

最少字符数：1

不接受未定义字段。

正文须符合以下一种结构。

withdrawal_accepted

typestring必含

取值：withdrawal_accepted

statusstring必含

取值：accepted

withdrawal_sending

typestring必含

取值：withdrawal_sending

statusstring必含

取值：sending

withdrawal_confirming

typestring必含

取值：withdrawal_confirming

statusstring必含

取值：confirming

withdrawal_held

typestring必含

取值：withdrawal_held

statusstring必含

取值：held

withdrawal_manual_pending

typestring必含

取值：withdrawal_manual_pending

statusstring必含

取值：manual_pending

withdrawal_auto_sending

typestring必含

取值：withdrawal_auto_sending

statusstring必含

取值：auto_sending

withdrawal_voucher_checking

typestring必含

取值：withdrawal_voucher_checking

statusstring必含

取值：voucher_checking

withdrawal_voucher_failed

typestring必含

取值：withdrawal_voucher_failed

statusstring必含

取值：voucher_failed

withdrawal_succeeded

提现成功终态。单笔带 txHash；多笔以 verificationStage=payments_succeeded 和完整 paymentDetails 表示，可无顶层 txHash。按 withdrawOrderId 将预扣确认为已扣款，只执行一次。普通通知使用基础字段；本次终态快照保留非空凭证阶段时还附带 verificationStage、原订单链/合约/收款地址，非空凭证信息与已知确认数。不返回 playerId 或 phase。保存通知与账务结果后回签，查询已处理过的成功结果不再重复处理。

paymentDetailsvalue可省略

成功付款摘要没有待确认项；跨字段总额相等、每笔确认阈值、地址及精度仍须业务适配器精确核对。

查看结构与约束

须同时符合以下结构。

PaymentDetails

查询与多笔付款成功通知的完整付款摘要，不含内部命令、账户、游标或钱包标识。成功须 paymentState=succeeded、已确认总额等于 requiredAmountBase=原单金额、remaining/excess 均为 0，无待确认付款；每条事实同原单收款地址及冻结资产精度，交易不重复。partial/overpaid/manual_review 均不按成功结清。顶层 txHash 可省略，不得把缺失单一哈希当失败。

paymentStatestring必含

取值：unpaid、partial、verifying、succeeded、overpaid、manual_review

requiredAmountBasestring必含

格式规则：^[1-9][0-9]{0,80}$；最多字符数：81

confirmedAmountBasestring必含

多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。

格式规则：^(0|[1-9][0-9]{0,80})$；最多字符数：81

remainingAmountBasestring必含

多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。

格式规则：^(0|[1-9][0-9]{0,80})$；最多字符数：81

excessAmountBasestring必含

多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。

格式规则：^(0|[1-9][0-9]{0,80})$；最多字符数：81

assetDecimalsinteger必含

最小值：0；最大值：77

paymentsarray<object>必含

最多项数：1000

查看每项字段

txHashstring必含

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

statestring必含

取值：verifying、confirming、confirmed、invalid

amountBasestring可省略

未确认实际金额时省略，不能补零；confirmed 时必含。

格式规则：^[1-9][0-9]{0,80}$；最多字符数：81

payerAddressstring必含

最少字符数：1

toAddressstring必含

最少字符数：1

confirmationsinteger可省略

最小值：0

requiredConfirmationsinteger必含

最小值：1

failureCodestring可省略

最少字符数：1

不接受未定义字段。

object

paymentStatevalue必含

取值：succeeded

remainingAmountBasevalue必含

取值：0

excessAmountBasevalue必含

取值：0

paymentsarray<object>必含

最少项数：1

查看每项字段

statevalue可省略

取值：confirmed、invalid

eventIdstring必含

最少字符数：1

typestring必含

固定为 withdrawal_succeeded。按订单确认扣款一次。

取值：withdrawal_succeeded

withdrawOrderIdstring必含

你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。

格式规则：^[0-9]{30}$

amountstring必含

statusstring必含

固定为 succeeded，提现终态。按订单确认扣款一次。

取值：succeeded

txHashstring可省略

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

voucherTxHashstring可省略

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

chainIdstring可省略

凭证终态附带的原订单链 ID；有值时与本地订单核对。

最少字符数：1

chainNamestring可省略

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

tokenContractstring可省略

最少字符数：1

toAddressstring可省略

最少字符数：1

verificationStagestring可省略

取值：awaiting_proof、verifying、confirming、proof_failed、succeeded、payments_managed、payments_succeeded

failureCodestring可省略

已同步的凭证核验原因；仅在凭证阶段存在且原因非空时返回。不能据此把 voucher_failed 当作提现终态。

最少字符数：1

payerAddressstring可省略

已同步的出款地址，有值时返回；用于核对凭证，不是玩家的充值地址。

最少字符数：1

confirmationsinteger可省略

已同步的确认数，0 是已知值；未提供有效计数时省略，不能默认补 0。

最小值：0

requiredConfirmationsinteger可省略

已配置凭证流程的确认阈值，已知时返回。字段名与充值的 confirmationsRequired 不同；缺失时不补默认值。

最小值：1

不接受未定义字段。

至少符合以下一种结构。

value

此分支另要求字段：txHash。

object

此分支另要求字段：paymentDetails。

verificationStagevalue必含

取值：payments_succeeded

withdrawal_failed

提现失败终态。基础 5 字段，不返回 txHash、playerId 或 phase；本次终态快照保留非空凭证阶段时附带 verificationStage、原订单链信息、非空凭证字段与已知确认数。按 withdrawOrderId 释放预扣一次；提交 HTTP 422 或查询 404/503 均不能代替本终态。

eventIdstring必含

最少字符数：1

typestring必含

固定为 withdrawal_failed。按订单释放预扣一次，不同于提交 HTTP 422。

取值：withdrawal_failed

withdrawOrderIdstring必含

你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。

格式规则：^[0-9]{30}$

amountstring必含

statusstring必含

固定为 failed，提现终态。按订单释放预扣一次，不同于提交 HTTP 422。

取值：failed

voucherTxHashstring可省略

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

chainIdstring可省略

凭证终态附带的原订单链 ID；有值时与本地订单核对。

最少字符数：1

chainNamestring可省略

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

tokenContractstring可省略

最少字符数：1

toAddressstring可省略

最少字符数：1

verificationStagestring可省略

取值：awaiting_proof、verifying、confirming、proof_failed、succeeded、payments_managed、payments_succeeded

failureCodestring可省略

已同步的凭证核验原因；仅在凭证阶段存在且原因非空时返回。不能据此把 voucher_failed 当作提现终态。

最少字符数：1

payerAddressstring可省略

已同步的出款地址，有值时返回；用于核对凭证，不是玩家的充值地址。

最少字符数：1

confirmationsinteger可省略

已同步的确认数，0 是已知值；未提供有效计数时省略，不能默认补 0。

最小值：0

requiredConfirmationsinteger可省略

已配置凭证流程的确认阈值，已知时返回。字段名与充值的 confirmationsRequired 不同；缺失时不补默认值。

最小值：1

不接受未定义字段。

withdrawal_refunded

取消尚未广播的提现后的终态，也用于退款结算。基础 5 字段，不返回 txHash、playerId 或 phase；本次终态快照保留非空凭证阶段时附带 verificationStage、原订单链信息、非空凭证字段与已知确认数。取消也可保留 awaiting_proof 信息，不能假定恰好只有 5 字段。按 withdrawOrderId 释放预扣一次，不表示链上自动退回 USDT。

eventIdstring必含

最少字符数：1

typestring必含

固定为 withdrawal_refunded。按订单释放预扣一次，不表示链上自动退款。

取值：withdrawal_refunded

withdrawOrderIdstring必含

你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。

格式规则：^[0-9]{30}$

amountstring必含

statusstring必含

固定为 refunded，提现终态。按订单释放预扣一次，不表示链上自动退款。

取值：refunded

voucherTxHashstring可省略

提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。

格式规则：^(0x)?[0-9a-f]{64}$

chainIdstring可省略

凭证终态附带的原订单链 ID；有值时与本地订单核对。

最少字符数：1

chainNamestring可省略

平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。

最少字符数：1

tokenContractstring可省略

最少字符数：1

toAddressstring可省略

最少字符数：1

verificationStagestring可省略

取值：awaiting_proof、verifying、confirming、proof_failed、succeeded、payments_managed、payments_succeeded

failureCodestring可省略

已同步的凭证核验原因；仅在凭证阶段存在且原因非空时返回。不能据此把 voucher_failed 当作提现终态。

最少字符数：1

payerAddressstring可省略

已同步的出款地址，有值时返回；用于核对凭证，不是玩家的充值地址。

最少字符数：1

confirmationsinteger可省略

已同步的确认数，0 是已知值；未提供有效计数时省略，不能默认补 0。

最小值：0

requiredConfirmationsinteger可省略

已配置凭证流程的确认阈值，已知时返回。字段名与充值的 confirmationsRequired 不同；缺失时不补默认值。

最小值：1

不接受未定义字段。

withdrawal_rejected

schemaVersion=2 是完整拒绝包络版本。当前简单上限通过 Webhook 和保存完整回执的原单 GET 200 提供该包络，同步为泛化 422；旧泛化拒单或损坏回执查询为 503。另行启用额度 v2 的原单由 POST 422、GET 200 和通知共享冻结正文。完整形状禁止 phase/acceptedAt/route/txHash 等字段。可信环境/接入方、原订单/玩家/链/登记合约/地址/金额/资产精度、eventId 派生与 decisionId 必须由持久业务事务核对；无 accepted/付款证据才一次 held→released。原文/摘要/决定和账务同事务保存后 ACK，异文或矛盾持久隔离；不能把 rejected 加入通用 RELEASE。页面按 resetAt 与可信服务端当前时间展示快照，不从收件时重新倒数，不自动重发或跨日重开。

schemaVersioninteger必含

取值：2

typestring必含

取值：withdrawal_rejected

statusstring必含

取值：rejected

acceptedboolean必含

取值：false

broadcastboolean必含

取值：false

finalboolean必含

取值：true

paymentInitiatedboolean必含

取值：false

retryModestring必含

取值：new_order

decisionIdstring必含

格式规则：^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

eventIdstring必含

格式规则：^[0-9a-f]{64}$

withdrawOrderIdstring必含

你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。

格式规则：^[0-9]{30}$

playerIdstring必含

最少字符数：1；最多字符数：128

chainNamestring必含

最少字符数：1；最多字符数：128

chainIdstring必含

格式规则：^[1-9][0-9]{0,77}$

tokenContractstring必含

最少字符数：1

amountstring必含

正 uint256 基础单位字符串；不能用浮点。

格式规则：^[1-9][0-9]{0,77}$

toAddressstring必含

最少字符数：1

codestring必含

当前简单上限只产生前两种原因；须先验签和校验完整包络，不能只按本字段释放预扣。

取值：USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED、REQUEST_AMOUNT_EXCEEDS_DAILY_LIMIT、USER_WITHDRAWAL_QUOTA_BLOCKED

quotavalue必含

查看结构与约束

须同时符合以下结构。

WithdrawalQuota

所有字段必含，nullable 显式保留。金额为代币最小单位字符串。当前简单上限按用户与链、按申请所属北京时间日计入，昨天未完成订单不占今天；reservedBase=0、blocked=false。available=max(0,limit-spent-reserved)。resetAt 是评估日下一次北京时间 00:00，秒数向上取整。累计超限 retry 字段为 resetAt/秒数，单笔超过总上限两者 null；另行启用的额度 v2 通道有独立跨日占用及阻断语义。OpenAPI 不能证明跨字段语义、JSON 重复键或 UTF-8 正确性，须使用完整协议校验。

scopestring必含

取值：user_chain

currencystring必含

取值：USDT

decimalsinteger必含

最小值：0；最大值：255

limitBasestring必含

该链每个用户分别适用的每日上限，代币最小单位整数字符串；按 decimals 换算展示。

格式规则：^[1-9][0-9]*$；最多字符数：1024

spentBasestring必含

当前简单上限为当日已计入的申请总额，含处理中和成功订单，不仅是已付款；按申请日统计，排除已取消、已拒绝和失败订单。另行启用的额度 v2 通道才表示当日已确认付款额。

格式规则：^(0|[1-9][0-9]*)$；最多字符数：1024

reservedBasestring必含

当前简单上限固定为字符串 0，处理中金额已含在 spentBase，不表示没有在途提款。额度 v2 通道为独立未决占用，并跨日保留。

格式规则：^(0|[1-9][0-9]*)$；最多字符数：1024

availableBasestring必含

拒绝评估时的可用额度，max(0,limitBase-spentBase-reservedBase)；是历史快照，不是用户余额，也不是当前受理保证。

格式规则：^(0|[1-9][0-9]*)$；最多字符数：1024

requestedBasestring必含

拒绝时为正 uint256 字符串且等于 amount；额度查询时显式 null。

格式规则：^[1-9][0-9]*$；最多字符数：78；允许 null

policyVersionstring必含

正 uint64 十进制字符串，最大 18446744073709551615。当前简单上限再次保存金额不递增此值，不能用作通知新旧排序或配置变更序号；范围由 codec 校验。

格式规则：^[1-9][0-9]*$；最多字符数：20

windowstring必含

取值：fixed_day

timezonestring必含

取值：Asia/Shanghai

evaluatedAtstring必含

规范 UTC RFC3339Nano；1–9999 年、有效日期、无尾零小数，由共享 codec 校验。

格式规则：^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,8}[1-9])?Z$

resetAtstring必含

evaluatedAt 所属北京时间自然日的下一次 00:00，使用 UTC RFC3339Nano 表达。用此绝对时间减可信服务端当前时间展示等待时长；到点不重开旧单。

格式规则：^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,8}[1-9])?Z$

resetInSecondsinteger必含

生成快照时距 resetAt 的向上取整秒数。延迟或重试通知不能从收件时重新倒数此值。

最小值：1；最大值：86400

retryAtstring必含

本次快照建议的重置参考时间，不是禁止此前申请的期限或受理保证。当前简单上限累计超限时等于 resetAt，单笔超过上限时为 null；取消、失败或提额使额度提前恢复时，玩家可以主动发起新申请，旧订单不自动重试。

格式规则：^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,8}[1-9])?Z$；允许 null

retryAfterSecondsinteger必含

与 retryAt 配对的评估时等待秒数；retryAt 为 null 时本字段也显式为 null。

最小值：1；最大值：86400；允许 null

blockedboolean必含

当前简单上限固定 false。只有另行启用的额度 v2 通道可能存在人工核查阻断。

不接受未定义字段。

object

requestedBasestring必含

不接受未定义字段。

通知正文 Go struct

下方联合结构对应充值/提现进度与付款结果；withdrawal_rejected 拒绝通知必须使用独立严格解码器。金额、区块高度和链上序号保持字符串，避免精度或格式损失。

package ognotice

import "encoding/json"

// TerminalNotice 对应充值/提现进度与付款结果；withdrawal_rejected 拒绝通知另用 quota.DecodeRejection。
// 每条只有一个 type，以及与它成对的一个 status。
// 进度通知带 phase=progress；充值确认和提现终态不发送 phase，以指针表达字段可选。
// 这是各类通知字段的联合结构；指针表示可选，实际必含字段与出现条件仍按当前事件的 OpenAPI 校验。
// 提现终态的凭证扩展在本次终态快照保留非空 verificationStage 时出现，包含原订单链信息。
// 金额、区块和日志序号保留字符串并用大整数精确比较；确认数为非负整数，缺失不补 0。
// 账务按 status 与本地原单处理；本结构不替代验签、完整字段校验或持久事务。
type TerminalNotice struct {
	EventID               string  `json:"eventId"`
	Type                  string  `json:"type"`
	Status                string  `json:"status"`
	Amount                string  `json:"amount"`
	Phase                 *string `json:"phase,omitempty"`
	PlayerID              *string `json:"playerId,omitempty"`
	ChainName             *string `json:"chainName,omitempty"`
	ChainID               *string `json:"chainId,omitempty"`
	TxHash                *string `json:"txHash,omitempty"`
	LogIndex              *string `json:"logIndex,omitempty"`
	TokenContract         *string `json:"tokenContract,omitempty"`
	ToAddress             *string `json:"toAddress,omitempty"`
	BlockNumber           *string `json:"blockNumber,omitempty"`
	TxRef                 *string `json:"txRef,omitempty"`
	WithdrawOrderID       *string `json:"withdrawOrderId,omitempty"`
	Confirmations         *int    `json:"confirmations,omitempty"`
	ConfirmationsRequired *int    `json:"confirmationsRequired,omitempty"`
	RequiredConfirmations *int    `json:"requiredConfirmations,omitempty"`
	VerificationStage     *string `json:"verificationStage,omitempty"`
	VoucherTxHash         *string `json:"voucherTxHash,omitempty"`
	FailureCode           *string `json:"failureCode,omitempty"`
	PayerAddress          *string `json:"payerAddress,omitempty"`
	PaymentDetails        json.RawMessage `json:"paymentDetails,omitempty"` // 按公开 PaymentDetails 校验完整付款事实。
}

// 新拒绝不得反序列化到上面的可选字段联合结构。
import "walletprotocol/quota"

// 严格原始 bytes 校验，不允许重复/未知/缺失字段和 nullable 漂移。
rejection, err := quota.DecodeRejection(rawBody)
// err != nil 时不提交、不回签。成功也须由真实 commit 完成原单/scope 绑定、
// 受理/付款冲突核对及一次 held→released 持久事务；不能凭解析成功直接改账。
_ = rejection
_ = err

应答要求

200 接收端应答

先提交本地业务结果，再回签。应答没有 type、status、phase 等业务字段。接受任一 2xx，建议 200；正文可为空或短的 {}，不得超过 4096 字节。必须恰好一个 X-Signature，用通知密钥签本次请求的 METHOD|PATH|TIMESTAMP|QUERY|BODY，不签应答正文。缺失、重复或错误签名都是投递失败，并且不能因此改账。重复通知也应返回有效回签。

X-Signaturestring必返

处理成功的回签。恰好返回一个；缺失、重复或错误都会导致发送方判定失败。

64 个小写十六进制字符 HMAC-SHA256。用通知密钥签原请求的 METHOD|PATH|TIMESTAMP|QUERY|BODY，不能改用应答正文。

接口规范与环境配置

规范包含当前主动接口、每日提现上限查询和一个通知接收操作。高级 24 小时充值对账接口仅收起展示，旧直链和下载规范保留；每日上限查询读取与后台相同的当前规则；仍须核对本环境服务版本与数据库依赖。字段、必填项、枚举和示例见各接口；机器可读版本为 OpenAPI 3.0 规范。

操作	方法与路径	用途
createDepositAddress	`POST /v1/addresses`	获取玩家充值地址
listPlayerDeposits	`GET /v1/players/{playerId}/deposits?chainId=...`	充值页查进度
queryDeposit	`GET /v1/deposits/{txRef}`	复核单笔充值
submitWithdrawal	`POST /v1/withdrawals`	提交提现申请
listPlayerWithdrawals	`GET /v1/players/{playerId}/withdrawals?chainId=...&page=1&pageSize=20`	分页补查玩家该链已受理提现
queryWithdrawal	`GET /v1/withdrawals/{withdrawOrderId}`	查询提现最新状态
cancelWithdrawal	`POST /v1/withdrawals/{withdrawOrderId}/cancel`	取消尚未进入链上处理的提现，成功后为 `refunded`
queryWithdrawalQuota	`GET /v1/withdrawal-quota?playerId=...&chainId=...`	读取与后台相同的当前每日上限和当日申请额；quota:null 表示不限额
getWebhookConfig	`GET /v1/webhook-config`	只读核对通知 URL、启用状态、凭据是否配置、可用性及配置版本；不代表已送达
receiveTerminalNotice	`POST {notifyUrl}`	你的端点接收交易通知

导入 API 工具后，将 servers[0].variables.baseUrl.default 设为平台发放的 API 接入地址；每次调用都重新签名。通知操作独立使用你的完整通知 URL：notifyOrigin 只填协议、主机和端口，操作路径填写接收端的实际路径。默认 /notify 只是示意，不要在已有路径后再次追加，也不能把它当作业务 API 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。

通知与应答示例

REPLACE_ 为环境或业务标识占位符。金额与状态仅演示格式，不代表实际交易。

通知正文

普通流程 / 充值进度。记录 txRef，展示待确认，不入账。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "deposit_detected",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "txHash": "REPLACE_TX_HASH",
  "logIndex": "0",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "1000000",
  "status": "deposit_detected",
  "blockNumber": "250",
  "txRef": "REPLACE_TX_REF",
  "phase": "progress",
  "confirmations": 0,
  "confirmationsRequired": 12
}

普通流程 / 充值进度。更新确认进度，不入账。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "deposit_confirming",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "txHash": "REPLACE_TX_HASH",
  "logIndex": "0",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "1000000",
  "status": "deposit_confirming",
  "blockNumber": "250",
  "txRef": "REPLACE_TX_REF",
  "phase": "progress",
  "confirmations": 3,
  "confirmationsRequired": 12
}

普通流程 / 充值确认。status 为 confirmed，不返回 phase。核对资产并按 txRef 入账；失效或冲正后先单笔查询。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "deposit_confirmed",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "txHash": "REPLACE_TX_HASH",
  "logIndex": "0",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "1000000",
  "status": "confirmed",
  "blockNumber": "250",
  "txRef": "REPLACE_TX_REF"
}

普通流程 / 提现进度。保留预扣，等待后续提现结果。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_accepted",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "accepted",
  "phase": "progress",
  "confirmations": 0
}

普通流程 / 提现进度。保留预扣，等待链上观察结果；不证明已广播。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_sending",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "sending",
  "phase": "progress",
  "confirmations": 0
}

普通流程 / 提现进度。已观察到链上交易，或凭证流程进入确认。保留预扣，不确认扣款。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_confirming",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "confirming",
  "phase": "progress",
  "confirmations": 4,
  "txHash": "REPLACE_TX_HASH"
}

普通流程 / 提现进度。保留预扣，不因等待时间长而释放。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_held",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "held",
  "phase": "progress",
  "confirmations": 0
}

普通流程 / 提现进度。人工提现仍在处理，且不属于受理、监测、确认或复核。保留预扣，不表示尚未广播。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_manual_pending",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "manual_pending",
  "phase": "progress",
  "confirmations": 0
}

兼容自动流程 / 提现进度。平台未启用自动提现时不会发出。发出后保留预扣，等待终态。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_auto_sending",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "auto_sending",
  "phase": "progress",
  "confirmations": 0
}

已配置凭证流程 / 提现进度。保留预扣，有哈希也不确认扣款。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_voucher_checking",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "voucher_checking",
  "phase": "progress",
  "confirmations": 0
}

已配置凭证流程 / 提现进度。保留预扣，仍不能按终态处理。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_voucher_failed",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "voucher_failed",
  "phase": "progress",
  "confirmations": 0
}

单笔付款 / 提现终态。此单笔示例含 txHash，不返回 phase。按 withdrawOrderId 确认扣款一次。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_succeeded",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "succeeded",
  "txHash": "REPLACE_TX_HASH"
}

普通流程 / 提现终态。不返回 txHash、playerId 或 phase。按原订单释放预扣一次；提交 HTTP 422 不等于此终态。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_failed",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "failed"
}

取消未广播提现 / 提现终态。此例展示保留 awaiting_proof 的可选元数据分支，附带原订单链信息和已知的 0 次确认；凭证哈希尚未录入，因此省略 voucherTxHash。未记录凭证阶段时仍使用基础 5 字段。按订单释放预扣一次，不表示链上自动退款。

{
  "eventId": "REPLACE_EVENT_ID",
  "type": "withdrawal_refunded",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "amount": "1000000",
  "status": "refunded",
  "verificationStage": "awaiting_proof",
  "chainId": "REPLACE_CHAIN_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "toAddress": "REPLACE_TO_ADDRESS",
  "confirmations": 0,
  "requiredConfirmations": 12
}

由既有 TEST_ONLY 身份夹具派生的独立离线场景，不是真实地址、配置或交易。精度为 6，上限为 10 USDT；评估时间为北京时间 23:55，5 分钟后零点重置。当前通道通过 Webhook 提供此完整正文，POST 仍为泛化 422。

{
  "schemaVersion": 2,
  "type": "withdrawal_rejected",
  "status": "rejected",
  "accepted": false,
  "broadcast": false,
  "final": true,
  "paymentInitiated": false,
  "retryMode": "new_order",
  "decisionId": "00000000-0000-4000-8000-000000000001",
  "eventId": "REPLACE_EVENT_ID",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "2000000",
  "toAddress": "REPLACE_TO_ADDRESS",
  "code": "USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED",
  "quota": {
    "scope": "user_chain",
    "currency": "USDT",
    "decimals": 6,
    "limitBase": "10000000",
    "spentBase": "9000000",
    "reservedBase": "0",
    "availableBase": "1000000",
    "requestedBase": "2000000",
    "policyVersion": "1",
    "window": "fixed_day",
    "timezone": "Asia/Shanghai",
    "evaluatedAt": "2026-10-26T15:55:00Z",
    "resetAt": "2026-10-26T16:00:00Z",
    "resetInSeconds": 300,
    "retryAt": "2026-10-26T16:00:00Z",
    "retryAfterSeconds": 300,
    "blocked": false
  }
}

{
  "schemaVersion": 2,
  "type": "withdrawal_rejected",
  "status": "rejected",
  "accepted": false,
  "broadcast": false,
  "final": true,
  "paymentInitiated": false,
  "retryMode": "new_order",
  "decisionId": "00000000-0000-4000-8000-000000000001",
  "eventId": "REPLACE_EVENT_ID",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "11000000",
  "toAddress": "REPLACE_TO_ADDRESS",
  "code": "REQUEST_AMOUNT_EXCEEDS_DAILY_LIMIT",
  "quota": {
    "scope": "user_chain",
    "currency": "USDT",
    "decimals": 6,
    "limitBase": "10000000",
    "spentBase": "0",
    "reservedBase": "0",
    "availableBase": "10000000",
    "requestedBase": "11000000",
    "policyVersion": "1",
    "window": "fixed_day",
    "timezone": "Asia/Shanghai",
    "evaluatedAt": "2026-10-26T15:55:00Z",
    "resetAt": "2026-10-26T16:00:00Z",
    "resetInSeconds": 300,
    "retryAt": null,
    "retryAfterSeconds": null,
    "blocked": false
  }
}

仅为旧额度 v2 的离线黄金样本，包含独立占用，不代表当前简单上限或真实配置。仅该通道三渠道正文相同；完整绑定与持久提交后一次释放。

{
  "schemaVersion": 2,
  "type": "withdrawal_rejected",
  "status": "rejected",
  "accepted": false,
  "broadcast": false,
  "final": true,
  "paymentInitiated": false,
  "retryMode": "new_order",
  "decisionId": "00000000-0000-4000-8000-000000000001",
  "eventId": "REPLACE_EVENT_ID",
  "withdrawOrderId": "REPLACE_WITHDRAW_ORDER_ID",
  "playerId": "REPLACE_PLAYER_ID",
  "chainName": "REPLACE_CHAIN_NAME",
  "chainId": "REPLACE_CHAIN_ID",
  "tokenContract": "REPLACE_TOKEN_CONTRACT",
  "amount": "20",
  "toAddress": "REPLACE_TO_ADDRESS",
  "code": "USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED",
  "quota": {
    "scope": "user_chain",
    "currency": "USDT",
    "decimals": 6,
    "limitBase": "100",
    "spentBase": "80",
    "reservedBase": "10",
    "availableBase": "10",
    "requestedBase": "20",
    "policyVersion": "1",
    "window": "fixed_day",
    "timezone": "Asia/Shanghai",
    "evaluatedAt": "2026-10-24T15:59:59.5Z",
    "resetAt": "2026-10-24T16:00:00Z",
    "resetInSeconds": 1,
    "retryAt": "2026-10-24T16:00:00Z",
    "retryAfterSeconds": 1,
    "blocked": false
  }
}

接收方应持久化通知并完成该场景要求的处理后再应答。应答签名覆盖原请求，不覆盖应答体。

HTTP/1.1 200 OK
X-Signature: REPLACE_COMPUTED_REQUEST_HMAC
Content-Length: 0

查看完整验签、去重与回签实现 →