取消未广播提现 · OG 开发者中心

POST/v1/withdrawals/{withdrawOrderId}/cancel

接入方服务端 → 支付服务

对接提示

只取消尚未进入链上处理的外部提现。成功后公开状态为 refunded，并通知 withdrawal_refunded。已进入处理、已有交易行或钱包返回的状态没有变成 cancelled 时返回 409，尚未终态的预扣保持。钱包不可读时返回 503。

服务端签名认证

每次请求按方法、路径、时间戳、原始 query 与原始正文计算 HMAC。先完成身份验证和环境配置。

调用说明

调用时机

钱包仍待审批、玩家或业务方需要撤回这笔提现时调用。已经广播、进入人工凭证，或无法确认是否已处理时，不要在调用后自行释放预扣。

调用步骤

将原 withdrawOrderId 放入路径，不传 query 或 body。
发送签名 POST 请求。签名正文使用空字符串。
成功时按返回的 refunded 释放原订单预扣一次，并与 withdrawal_refunded 通知共用同一条终态去重。

结果处理

成功响应的 status 固定为 refunded，route 固定为 manual，broadcast 固定为 false，且不携带 txHash。按该订单释放预扣一次。同一笔已经是 refunded 时，再次调用返回已保存的同一份 refunded 响应，不再释放第二次，也不再发第二条终态通知。409 表示当前不能取消，公开状态不变。订单尚未终态时预扣保持；已经是 failed 或 succeeded 时保持该终态，不新增通知。钱包不可读时是 503，不是 409。

失败与重试

401 检查签名；422 检查订单号以及空 query 和空 body。404 与查询缺失相同，不能据此释放预扣。409 正文固定为 {"error":"conflict"}，保持预扣，不要把未改变的状态当成已取消。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 字节；每个请求发送一次。

路径参数

withdrawOrderIdstring必填

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

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

响应字段

200 成功响应

取消成功，或重复取消同一笔已经退款的订单。status 为 refunded。按订单释放预扣一次；重复响应不再释放。

application/json

固定返回值
`accepted`	`true`
`broadcast`	`false`
`status`	`refunded`已作退款结算取消响应固定值按订单释放预扣一次，不表示链上自动转币退款。重复调用不再释放。
`route`	`manual`人工提现取消响应固定值按 status=refunded 释放原预扣一次。

`verificationStage`7 个取值
含义与取值
`awaiting_proof`
`verifying`
`confirming`
`proof_failed`
`succeeded`
`payments_managed`
`payments_succeeded`

withdrawOrderIdstring必返

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

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

acceptedboolean必返

固定为 true，表示该订单曾经受理。是否释放预扣以 status 为准。

取值：true

broadcastboolean必返

固定为 false。成功响应不携带 txHash。

取值：false

statusstring必返

固定为 refunded。按该订单释放预扣一次；重复调用仍返回此值，不再释放第二次。

取值：refunded

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

amountstring必返

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

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

acceptedAtinteger必返

首次受理时间，Unix 秒整数。取消不会改写该时间。

最小值：0

routestring必返

固定为 manual。本接口只取消尚未广播的外部人工提现。

取值：manual

voucherTxHashstring按条件返回

已保存的凭证交易哈希，非空时返回。可带小写 0x，后接 64 个小写十六进制字符；账务仍按 refunded 处理。

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

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

failureCodestring按条件返回

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

最少字符数：1

payerAddressstring按条件返回

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

最少字符数：1

confirmationsinteger按条件返回

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

最小值：0

requiredConfirmationsinteger按条件返回

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

最小值：1

不接受未定义字段。

HTTP 状态码

状态码	含义与处理
`200`	取消成功，或重复取消同一笔已经退款的订单。status 为 refunded。按订单释放预扣一次；重复响应不再释放。
`401`	请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。
`404`	查询此刻没有该接入方与订单号的接入记录。在途 POST 仍可能随后受理，不能单凭 404 释放预扣。检查环境、订单号与提交记录，再使用原订单查询。
`409`	当前不能取消。订单已进入处理、已有交易行、凭证已接管，或公开状态已经是其他终态。正文固定为 {"error":"conflict"}。尚未终态时保持预扣和原状态；已经是 failed 或 succeeded 时保持该终态，不新增通知。钱包不可读时返回 503，不是本响应。
`422`	订单号不是 30 位数字，或请求带了 query、非空 body。去掉 query 和 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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。