数字货币订单查询

概述

订单查询 API 用于主动获取数字货币代收 / 代付订单的最新状态、手续费与链上信息。代收与代付为两个独立接口，请求体结构相同、响应体不同。

使用建议

业务应以 回调通知 为主要状态来源，查询接口用于回调丢失时的补偿对账。请勿高频轮询（建议间隔不低于 5 秒）。

公共请求头（含必填 Nonce）、公共请求体字段与统一响应结构见 数字货币接入总览。

---

请求路径

域名：推荐使用统一域名 openapi.toppayment.com（路径不变）；原数字货币域名（global-digit-openapi.toppayment.com）仍可用。

场景	环境	地址
代收查询	沙箱	https://openapi.toppayment.com/crypto/sandbox/pay/query
代收查询	生产	https://openapi.toppayment.com/crypto/pay/query
代付查询	沙箱	https://openapi.toppayment.com/crypto/sandbox/disbursement/query
代付查询	生产	https://openapi.toppayment.com/crypto/disbursement/query

请求头参数

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
Nonce	M	String(16-64)	防重放随机串，10 分钟内不可重复，不参与签名

请求体参数

代收与代付查询共用同一套请求参数。

字段	必填	类型	描述
mchNo	M	String(32)	商户编号 沙箱需使用 SD 前缀的沙箱商户号
timestamp	M	String(13)	请求时间戳（13 位毫秒级），偏差须在 ±5 分钟内
sign	M	String	签名，见 签名规则
orderNum	C	String(64)	商户订单号
platOrderNum	C	String(64)	平台订单号
tenantCode	O	String(32)	子租户编码，不传使用默认租户
countryCode	O	String(16)	国家码，数字货币场景无需传

订单号二选一

orderNum 与 platOrderNum 至少传一个，都不传返回 0001（orderNum or platOrderNum required）。两者同时传入时以 platOrderNum 为准。订单不存在返回 0006。

请求示例

Content-Type: application/json
Nonce: 5d8b3f1c74a920e6b8c3

{
    "mchNo": "{{mchNo}}",
    "orderNum": "CR1788506800926",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

{
    "mchNo": "{{mchNo}}",
    "platOrderNum": "CR20260904152640640",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

---

代收订单查询响应

响应体参数

字段	必填	类型	描述
success	M	Boolean	是否成功
code	M	String	响应状态码 9999：成功；其他见 异常码
msg	O	String	响应消息，成功时为 null
timeStamp	M	Number	服务器响应时间（毫秒级）
data	M	Object	响应数据对象
orderNum	M	String	商户订单号
platOrderNum	M	String	平台订单号
payMoney	M	Number	收款数量
fee	O	Number	手续费 未产生手续费（如订单未支付）时为 null
currency	O	String	币种 收银台模式下付款人未选择币种前为 null
netWork	O	String	链网络，同上
inAddress	O	String	收款地址 尚未分配时为 null
status	M	String	订单状态，取值见下表

代收状态取值

status	说明	是否终态
WAITING	待付款（含订单处理中、已下单未支付）	否
SUCCESS	收款成功，资金已入账	是
FAILED	下单失败	是
EXPIRED	订单已过期（超过 expiryPeriod 仍未付款）	是

与回调 status 的差异

查询接口返回的是统一展示状态（WAITING / SUCCESS / FAILED / EXPIRED）；代收回调返回的是订单明细状态（INIT_ORDER / NO_PAY / SUCCESS / PAY_ERROR 等）。两者取值集合不同，请分别处理，详见 回调通知。

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CR1788506800926",
        "platOrderNum": "CR20260904152640640",
        "payMoney": 10.500000,
        "fee": 1.100000,
        "currency": "USDT",
        "netWork": "TRC20",
        "inAddress": "TP5wzCqNsJFNT83m1VXdF2Aj1ageFWgqW2",
        "status": "SUCCESS"
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CR1788506800927",
        "platOrderNum": "CR20260904152640641",
        "payMoney": 10.500000,
        "fee": null,
        "currency": null,
        "netWork": null,
        "inAddress": null,
        "status": "WAITING"
    }
}

{
    "success": false,
    "code": "0006",
    "msg": "[0006]the order does not exist!",
    "timeStamp": 1767873172906,
    "data": null
}

---

代付订单查询响应

响应体参数

字段	必填	类型	描述
success	M	Boolean	是否成功
code	M	String	响应状态码 9999：成功；其他见 异常码
msg	O	String	响应消息，成功时为 null
timeStamp	M	Number	服务器响应时间（毫秒级）
data	M	Object	响应数据对象
orderNum	M	String	商户订单号
platOrderNum	M	String	平台订单号
amount	M	Number	代付数量
fee	M	Number	手续费
feeType	M	Number	手续费承担方式 0：代付数量内扣除；1：手续费另计
status	M	Number	订单状态码，取值见 代付状态码
statusMsg	M	String	统一展示状态 PENDING / PROCESSING / SUCCESS / FAILED / CANCELLED
currency	M	String	币种
netWork	M	String	链网络

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CW1788506801001",
        "platOrderNum": "CW20260825143024553",
        "amount": 10.500000,
        "fee": 0.700000,
        "feeType": 0,
        "status": 2,
        "statusMsg": "SUCCESS",
        "currency": "USDT",
        "netWork": "TRC20"
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CW1788506801002",
        "platOrderNum": "CW20260825143024554",
        "amount": 10.500000,
        "fee": 0.700000,
        "feeType": 0,
        "status": 1,
        "statusMsg": "PENDING",
        "currency": "USDT",
        "netWork": "TRC20"
    }
}

---

对账建议

• 以 platOrderNum 作为对账主键，orderNum 仅在商户维度唯一。
• 仅在订单状态为终态时结束轮询：代收 SUCCESS / FAILED / EXPIRED，代付 status 为 2 / 3 / 4。
• 回调超过预期时间未收到时再启动查询补偿，避免与回调重复处理（请在商户侧做幂等）。

---

参考

• 数字货币代收
• 数字货币代付
• 数字货币回调通知
• 异常码