API 参考 / 提现
查询提现结果
按提现订单号读取当前已同步的处理状态。
/v1/withdrawals/{withdrawOrderId}接入方服务端 → 支付服务
查询显示最近同步的提现状态，可能存在延迟。当前人工流程会返回 manual_pending、held、succeeded、failed，取消未广播提现后还会返回 refunded。已配置凭证流程还会返回凭证阶段与状态。auto_sending 只属于兼容自动流程，当前未启用时不会出现。succeeded 确认扣款，failed 或 refunded 释放原预扣；其余状态保持预扣。
调用说明
调用时机
提交提现后查询进度，或在响应丢失、通知遗漏时复核结果。
调用步骤
- 将原 withdrawOrderId 放入路径，不传 query 或 body。
- 发送签名 GET 请求，读取 status，并与本地订单关联。
- 与通知共用订单去重：succeeded 确认扣款，failed 或 refunded 释放原预扣，各只执行一次。
结果处理
普通人工提现使用 manual_pending、held、succeeded、failed。取消尚未广播的提现后，查询返回 refunded，按该订单释放原预扣一次，不表示链上自动退回 USDT。已配置凭证流程可能返回 voucher_checking、voucher_failed。auto_sending 只用于兼容自动流程，当前未启用自动提现时不会出现。各状态的处理见状态表。manual_pending 也可能涵盖提现监测或链上确认阶段；broadcast=false 只表示本响应未携带交易哈希，不能证明未广播。进度通知里的 accepted、sending、confirming 不属于查询状态，不能直接覆盖本字段。
失败与重试
401 检查签名；422 检查订单号及空 query/body。404 仅表示查询当时未找到接入记录，在途提交仍可能随后受理。当前普通通道保存完整每日上限拒绝回执时返回 200 和与 withdrawal_rejected Webhook 相同的原文；旧泛化拒单、损坏或身份不匹配回执返回 503。GET 只读，不重算额度、不重开原单、不调用钱包付款。额度 v2 原单仍返回原 POST 422 的同一完整正文，能力暂停后保留原回应。
503 也可能是结果未就绪或依赖异常，不能据此释放预扣；已经通过有效通知完成一次释放的订单，也不能被晚到 503 改回预扣。缺少明确结果时保持原单并请平台查拒绝回执和通知投递记录，勿自行换号提交或释放余额。
请求头
| 请求头 | 说明 |
|---|---|
X-Access-Key必填 | 平台发放的 API Access Key，用于识别你的业务后端。每个请求发送一次；只在服务端保存。 |
X-Timestamp必填 | 本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。 |
X-Signature必填 | 本次 API 请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用 API 密钥签 METHOD|PATH|TIMESTAMP|QUERY|BODY，保留实际路径、query 和 body 字节；每个请求发送一次。 |
路径参数
你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。
^[0-9]{30}$GET 请求的 body 必须为空；只发送本页列出的路径和 query 参数。
响应字段
200 成功响应
返回最新已同步状态，与 POST 保存的首次受理响应不同。按状态表处理，已通过通知完成的账务操作不再重复执行。
paymentDetails.remainingAmountBase | 0 |
|---|---|
paymentDetails.excessAmountBase | 0 |
schemaVersion | 2 |
type | withdrawal_rejected |
final | true |
paymentInitiated | false |
retryMode | new_order |
quota.scope | user_chain |
quota.currency | USDT |
quota.window | fixed_day |
quota.timezone | Asia/Shanghai |
| 含义与取值 |
|---|
unpaid |
partial |
verifying |
succeeded |
overpaid |
manual_review |
| 含义与取值 |
|---|
verifying |
confirming |
confirmed |
invalid |
| 含义与取值 |
|---|
true |
false |
| 含义与取值 | 适用范围与处理 |
|---|---|
人工流程处理中manual_pending | 普通流程 继续保留预扣；可能处于审批、提现监测或链上确认，不代表未广播。 |
等待人工核查held | 普通流程 继续保留预扣，等待处理结果。 |
提现成功succeeded | 普通流程 / 终态 按 withdrawOrderId 确认扣款一次。 |
提现失败failed | 普通流程 / 终态 按 withdrawOrderId 释放原预扣一次；不同于提交 HTTP 422。 |
自动提现处理中auto_sending | 兼容自动流程 继续保留预扣，等待终态。 |
提现凭证核验中voucher_checking | 已配置凭证流程 继续保留预扣，有哈希也不确认扣款。 |
提现凭证未通过voucher_failed | 已配置凭证流程 仍是处理中，继续保留预扣，不按终态处理。 |
已作退款结算refunded | 取消未广播提现 / 终态 按订单释放预扣一次，不表示链上自动转币退款。 |
rejected |
| 含义与取值 | 适用范围与处理 |
|---|---|
人工提现manual | 普通流程 保存流程信息，按 status 判断账务动作。 |
自动提现auto | 兼容自动流程 保存流程信息，按 status 判断账务动作。 |
| 含义与取值 |
|---|
awaiting_proof |
verifying |
confirming |
proof_failed |
succeeded |
payments_managed |
payments_succeeded |
| 含义与取值 |
|---|
true |
false |
| 含义与取值 | 适用范围与处理 |
|---|---|
用户当日累计提现超限USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED | 当前用户每日提现上限 / 兼容额度 v2 展示 resetAt 与剩余等待时间；条件恢复后由用户主动发起新申请，旧单不重开。 |
单笔金额超过每日上限REQUEST_AMOUNT_EXCEEDS_DAILY_LIMIT | 当前用户每日提现上限 / 兼容额度 v2 提示减少金额或联系平台；retryAt 为 null，不承诺次日可受理。 |
需要人工核查USER_WITHDRAWAL_QUOTA_BLOCKED | 仅兼容额度 v2，当前简单上限不产生 联系平台核查；不能仅等待零点或自动重提。 |
正文须符合以下一种结构。
Withdrawal
订单的最新已同步查询结果。终态按订单幂等处理；非终态继续保留预扣。已配置凭证流程按当前快照返回可选阶段、出款地址、凭证哈希与确认数；字段缺失表示未知，不能沿用旧尝试的值。
查询与多笔付款成功通知的完整付款摘要，不含内部命令、账户、游标或钱包标识。成功须 paymentState=succeeded、已确认总额等于 requiredAmountBase=原单金额、remaining/excess 均为 0，无待确认付款；每条事实同原单收款地址及冻结资产精度，交易不重复。partial/overpaid/manual_review 均不按成功结清。顶层 txHash 可省略，不得把缺失单一哈希当失败。
查看结构与约束
unpaid、partial、verifying、succeeded、overpaid、manual_review^[1-9][0-9]{0,80}$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：810；最大值：771000查看每项字段
提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。
^(0x)?[0-9a-f]{64}$verifying、confirming、confirmed、invalid未确认实际金额时省略，不能补零；confirmed 时必含。
^[1-9][0-9]{0,80}$；最多字符数：8111011不接受未定义字段。
不接受未定义字段。
你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。
^[0-9]{30}$固定为 true，表示订单已受理，不等于提现成功。
truetrue 表示本响应带有 txHash 或多笔付款已成功；false 不能证明链上尚未广播。该字段不决定扣款或释放预扣。
提现查询状态。普通人工流程使用 manual_pending、held、succeeded、failed；已配置凭证流程还可能返回 voucher_checking、voucher_failed。accepted、sending、confirming 仅用于进度通知，不属于本字段。succeeded 确认扣款，failed 或 refunded 释放原预扣，其余状态继续保持预扣。
manual_pending、held、succeeded、failed、auto_sending、voucher_checking、voucher_failed、refunded平台返回的链名称，用于保存和展示。取址和提交提现时只传 chainId，不自行填写此字段。
1本条记录所属链的数字字符串。与当前环境约定的链核对，并与记录一起保存。
1该环境登记的 USDT 合约。取址和提现响应由平台返回，请与链一起保存；请求不填写此字段。EVM 合约使用小写十六进制，TRON 使用区分大小写的 Base58Check。是否开放某条链，以平台提供的环境信息为准。
1提现收款地址，必须与所选链类型一致，不能是全零地址。EVM 接受 0x/0X 加 40 位十六进制并转为小写；TRON 接受 34 位 Base58Check，或 41 开头的 21 字节十六进制（可带 0x/0X），统一转为 Base58Check。不要把 TRON 地址转为小写。
1代币最小单位的正整数字符串。按当前环境的资产精度换算，使用整数或高精度十进制计算，禁止浮点。例：若 USDT 精度为 6，1 USDT 填 "1000000"。提交提现不允许 0、前导零、小数或科学计数，数值不得超过 uint256。充值入账前先核对链和合约，不能把其他代币按 USDT 精度换算。
^[1-9][0-9]{0,77}$；字符串表示的数值上限：115792089237316195423570985008687907853269984665640564039457584007913129639935；pattern 只检查十进制写法与位数；还需用高精度整数比较数值上限，不能使用浮点比较。首次受理时间，Unix 秒整数。重复提交时保持不变；不是链上提现完成时间。
0提现路径。manual_pending 对应 manual，auto_sending 对应 auto，其他状态返回实际流程。按 status 处理余额，不按 route 判断成功或退款。
manual、auto；最少字符数：1提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。
^(0x)?[0-9a-f]{64}$已配置凭证流程的交易哈希。voucher_checking 时必返，其他状态有值才返回。可带小写 0x，后接 64 个小写十六进制字符；有凭证哈希不等于提现成功。
^(0x)?[0-9a-f]{64}$可选提现凭证阶段：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已同步的凭证核验原因；仅在凭证阶段存在且原因非空时返回。不能据此把 voucher_failed 当作提现终态。
1已同步的出款地址，有值时返回；用于核对凭证，不是玩家的充值地址。
1已同步的确认数，0 是已知值；未提供有效计数时省略，不能默认补 0。
0已配置凭证流程的确认阈值，已知时返回。字段名与充值的 confirmationsRequired 不同；缺失时不补默认值。
1不接受未定义字段。
须同时符合以下结构。
状态与提现路径、交易字段的对应关系
正文须符合以下一种结构。
人工流程处理中
manual_pendingmanual自动流程处理中
auto_sendingauto凭证校验中必须有凭证交易哈希
此分支另要求字段：voucherTxHash。
voucher_checking提现成功具有单笔或多笔付款事实
成功付款摘要没有待确认项；跨字段总额相等、每笔确认阈值、地址及精度仍须业务适配器精确核对。
查看结构与约束
须同时符合以下结构。
PaymentDetails
查询与多笔付款成功通知的完整付款摘要，不含内部命令、账户、游标或钱包标识。成功须 paymentState=succeeded、已确认总额等于 requiredAmountBase=原单金额、remaining/excess 均为 0，无待确认付款；每条事实同原单收款地址及冻结资产精度，交易不重复。partial/overpaid/manual_review 均不按成功结清。顶层 txHash 可省略，不得把缺失单一哈希当失败。
unpaid、partial、verifying、succeeded、overpaid、manual_review^[1-9][0-9]{0,80}$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：81多笔付款聚合基础单位整数，允许 0；与原单冻结精度一致，须精确计算，不用浮点。
^(0|[1-9][0-9]{0,80})$；最多字符数：810；最大值：771000查看每项字段
提现交易哈希，可带小写 0x 前缀，后接 64 个小写十六进制字符。成功终态必须返回；所属链以订单记录为准，不按前缀推断。
^(0x)?[0-9a-f]{64}$verifying、confirming、confirmed、invalid未确认实际金额时省略，不能补零；confirmed 时必含。
^[1-9][0-9]{0,80}$；最多字符数：8111011不接受未定义字段。
不接受未定义字段。
object
succeeded001查看每项字段
confirmed、invalidsucceeded至少符合以下一种结构。
value
此分支另要求字段：txHash。
object
此分支另要求字段：paymentDetails。
payments_succeeded其余状态沿用实际 route
held、voucher_failed、failed、refundedbroadcast 表示已知单笔交易或多笔付款成功
正文须符合以下一种结构。
value | object
true至少符合以下一种结构。
value
此分支另要求字段：txHash。
object
此分支另要求字段：paymentDetails。
payments_succeededobject
此分支不得出现字段：txHash。
false须同时符合以下结构。
value
value
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 与可信服务端当前时间展示快照，不从收件时重新倒数，不自动重发或跨日重开。
2withdrawal_rejectedrejectedfalsefalsetruefalsenew_order^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$^[0-9a-f]{64}$你的业务后端生成的提现订单号，恰好 30 位数字，必须作为字符串传输以保留前导零。提交、重试、查询和账务去重使用同一个值。
^[0-9]{30}$1；最多字符数：1281；最多字符数：128^[1-9][0-9]{0,77}$1正 uint256 基础单位字符串；不能用浮点。
^[1-9][0-9]{0,77}$1当前简单上限只产生前两种原因；须先验签和校验完整包络，不能只按本字段释放预扣。
USER_DAILY_WITHDRAWAL_LIMIT_EXCEEDED、REQUEST_AMOUNT_EXCEEDS_DAILY_LIMIT、USER_WITHDRAWAL_QUOTA_BLOCKED查看结构与约束
须同时符合以下结构。
WithdrawalQuota
所有字段必含，nullable 显式保留。金额为代币最小单位字符串。当前简单上限按用户与链、按申请所属北京时间日计入，昨天未完成订单不占今天；reservedBase=0、blocked=false。available=max(0,limit-spent-reserved)。resetAt 是评估日下一次北京时间 00:00，秒数向上取整。累计超限 retry 字段为 resetAt/秒数，单笔超过总上限两者 null；另行启用的额度 v2 通道有独立跨日占用及阻断语义。OpenAPI 不能证明跨字段语义、JSON 重复键或 UTF-8 正确性，须使用完整协议校验。
user_chainUSDT0；最大值：255该链每个用户分别适用的每日上限，代币最小单位整数字符串；按 decimals 换算展示。
^[1-9][0-9]*$；最多字符数：1024当前简单上限为当日已计入的申请总额，含处理中和成功订单，不仅是已付款；按申请日统计，排除已取消、已拒绝和失败订单。另行启用的额度 v2 通道才表示当日已确认付款额。
^(0|[1-9][0-9]*)$；最多字符数：1024当前简单上限固定为字符串 0，处理中金额已含在 spentBase，不表示没有在途提款。额度 v2 通道为独立未决占用，并跨日保留。
^(0|[1-9][0-9]*)$；最多字符数：1024拒绝评估时的可用额度，max(0,limitBase-spentBase-reservedBase)；是历史快照，不是用户余额，也不是当前受理保证。
^(0|[1-9][0-9]*)$；最多字符数：1024拒绝时为正 uint256 字符串且等于 amount；额度查询时显式 null。
^[1-9][0-9]*$；最多字符数：78；允许 null正 uint64 十进制字符串，最大 18446744073709551615。当前简单上限再次保存金额不递增此值，不能用作通知新旧排序或配置变更序号；范围由 codec 校验。
^[1-9][0-9]*$；最多字符数：20fixed_dayAsia/Shanghai规范 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$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$生成快照时距 resetAt 的向上取整秒数。延迟或重试通知不能从收件时重新倒数此值。
1；最大值：86400本次快照建议的重置参考时间，不是禁止此前申请的期限或受理保证。当前简单上限累计超限时等于 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与 retryAt 配对的评估时等待秒数；retryAt 为 null 时本字段也显式为 null。
1；最大值：86400；允许 null当前简单上限固定 false。只有另行启用的额度 v2 通道可能存在人工核查阻断。
不接受未定义字段。
object
不接受未定义字段。
HTTP 状态码
| 状态码 | 含义与处理 |
|---|---|
200 | 返回最新已同步状态，与 POST 保存的首次受理响应不同。按状态表处理，已通过通知完成的账务操作不再重复执行。 |
401 | 请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。 |
404 | 查询此刻没有该接入方与订单号的接入记录。在途 POST 仍可能随后受理，不能单凭 404 释放预扣。检查环境、订单号与提交记录，再使用原订单查询。 |
422 | 查询格式不正确。检查路径参数，仅保留接口允许的 query，并保证 GET body 为空；修正后可重新查询。 |
503 | 暂时无法确定结果，或查询结果尚未就绪。保留预扣，使用原订单号查询或同内容重试。500、502、504、超时和断连也按未知结果处理，不换新订单号。 |
失败时先核对 HTTP 状态、原始签名内容和环境配置，见 错误处理。
接口规范与环境配置
规范包含当前主动接口、每日提现上限查询和一个通知接收操作。高级 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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。