API 参考 / 提现
查询玩家提现记录
分页读取当前认证接入方下，指定玩家、指定链的平台已受理提现记录，用于补充 OG 自有账本及手机提现历史。
/v1/players/{playerId}/withdrawals接入方服务端 → 支付服务
调用说明
调用时机
玩家查看提现历史、提交受理后刷新记录，或 OG 后端恢复服务后补查已受理原单时调用；未知提交仍由 OG 本地原单和单笔查询跟踪。
调用步骤
- OG 后端从自己的登录态确定玩家，使用原 playerId 与允许读取的登记 chainId。
- 发送空 body 的签名 GET；query 只允许 chainId、page、pageSize，各至多一次。分页 query 的实际字节原样参与 HMAC。
- 核对每条记录的原订单、完整链/资产、金额和收款地址，按 withdrawOrderId 合并自己的持久记录，再返回授权玩家的历史列表。
分页与排序
page 默认 1，只接受无前导零的正十进制字符串，最大 10001；pageSize 默认 20，只接受 20 或 50。还须满足 (page - 1) * pageSize <= 200000。响应为裸对象 {items,total,page,pageSize}；items 的每一项与单笔提现查询使用相同字段。
按 acceptedAt 的 Unix 秒倒序，相同秒按公开 30 位 withdrawOrderId 的字节倒序。这里的时间是平台首次受理时间，不是提现完成时间。这是 offset 分页，不是 cursor 或快照分页；翻页期间新受理订单可能使边界移动，客户端须按订单号合并去重并刷新首页，不能承诺一次遍历期间没有重复或遗漏。
结果处理
仅返回该 HMAC 接入方、原玩家和当前允许读取完整链事实的已受理原单；不返回其他玩家、其他接入方、未知提交或未受理记录。列表项与单笔查询相同，不另带 playerId、管理侧标识或 scope。status 仍可能是 held。OG 必须自行保存原提交、未知结果与预扣；空列表、超出末页或某单未出现，都不能释放预扣。重要结果仍可按原订单号单笔复核。
失败与重试
401 检查签名与原 query；422 检查玩家路径、登记链、分页写法/边界、多余或重复 query、非空 body。503 表示依赖或原记录暂不可用、损坏，保留本地账本后重查并请平台核查。无匹配记录返回 200，不返回 404；不支持时间或收款地址筛选。
请求头
| 请求头 | 说明 |
|---|---|
X-Access-Key必填 | 平台发放的 API Access Key，用于识别你的业务后端。每个请求发送一次；只在服务端保存。 |
X-Timestamp必填 | 本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。 |
X-Signature必填 | 本次 API 请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用 API 密钥签 METHOD|PATH|TIMESTAMP|QUERY|BODY，保留实际路径、query 和 body 字节；每个请求发送一次。 |
路径参数
提交提现时的原玩家标识，最多 128 个 Unicode 字符，不含空白、控制字符或 /，作为单个转义路径段；由 OG 后端授权，不能接受浏览器任意指定其他玩家。
^[^/]+$；最少字符数：1；最多字符数：128查询参数
当前环境允许读取的登记链 ID；按完整登记链事实筛选已受理原单。
^0*[1-9][0-9]*$；最少字符数：1；最多字符数：20页码，默认 1，无前导零，最大 10001；同时要求 (page - 1) * pageSize <= 200000。
^([1-9][0-9]{0,3}|10000|10001)$；默认值：1每页数量，仅支持 20 或 50，默认 20。
20、50；默认值：20GET 请求的 body 必须为空；只发送本页列出的路径和 query 参数。
响应字段
200 成功响应
返回该玩家该链本次查询可见的已受理订单及总数。无匹配或页码超过末页时 items 为空，不据此释放本地预扣。
items[].accepted | true |
|---|---|
items[].paymentDetails.remainingAmountBase | 0 |
items[].paymentDetails.excessAmountBase | 0 |
| 含义与取值 |
|---|
unpaid |
partial |
verifying |
succeeded |
overpaid |
manual_review |
| 含义与取值 |
|---|
verifying |
confirming |
confirmed |
invalid |
| 含义与取值 | 适用范围与处理 |
|---|---|
人工流程处理中manual_pending | 普通流程 继续保留预扣；可能处于审批、提现监测或链上确认，不代表未广播。 |
等待人工核查held | 普通流程 继续保留预扣，等待处理结果。 |
提现成功succeeded | 普通流程 / 终态 按 withdrawOrderId 确认扣款一次。 |
提现失败failed | 普通流程 / 终态 按 withdrawOrderId 释放原预扣一次；不同于提交 HTTP 422。 |
自动提现处理中auto_sending | 兼容自动流程 继续保留预扣，等待终态。 |
提现凭证核验中voucher_checking | 已配置凭证流程 继续保留预扣，有哈希也不确认扣款。 |
提现凭证未通过voucher_failed | 已配置凭证流程 仍是处理中，继续保留预扣，不按终态处理。 |
已作退款结算refunded | 取消未广播提现 / 终态 按订单释放预扣一次，不表示链上自动转币退款。 |
| 含义与取值 | 适用范围与处理 |
|---|---|
人工提现manual | 普通流程 保存流程信息，按 status 判断账务动作。 |
自动提现auto | 兼容自动流程 保存流程信息，按 status 判断账务动作。 |
| 含义与取值 |
|---|
awaiting_proof |
verifying |
confirming |
proof_failed |
succeeded |
payments_managed |
payments_succeeded |
| 含义与取值 |
|---|
true |
false |
| 含义与取值 |
|---|
20 |
50 |
按 acceptedAt 秒倒序，同秒按 withdrawOrderId 字节倒序。每项与单笔查询相同，不另带 playerId、管理侧标识或 scope。status 仍可能是 held。
50查看每项字段
查询与多笔付款成功通知的完整付款摘要，不含内部命令、账户、游标或钱包标识。成功须 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
本次查询范围内匹配的已受理订单总数，不包括 OG 本地未知提交；后续查询可变化。
0本次页码，同时受 offset <= 200000 约束。
1；最大值：10001本次每页数量。
20、50不接受未定义字段。
HTTP 状态码
| 状态码 | 含义与处理 |
|---|---|
200 | 返回该玩家该链本次查询可见的已受理订单及总数。无匹配或页码超过末页时 items 为空，不据此释放本地预扣。 |
401 | 请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。 |
422 | 查询格式不正确。检查路径参数，仅保留接口允许的 query，并保证 GET body 为空；修正后可重新查询。 |
503 | 依赖不可用或原单事实损坏，当前页不能作为可靠查询结果。保持 OG 本地订单/预扣，重试相同查询；持续失败请平台核对原单与运行依赖。 |
失败时先核对 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 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。