跳至主要內容

数字货币订单查询

TOPPAY Team大约 5 分钟

概述

订单查询 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-TypeMString固定值:application/json
NonceMString(16-64)防重放随机串,10 分钟内不可重复,不参与签名

请求体参数

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

字段必填类型描述
mchNoMString(32)商户编号
沙箱需使用 SD 前缀的沙箱商户号
timestampMString(13)请求时间戳(13 位毫秒级),偏差须在 ±5 分钟内
signMString签名,见 签名规则
orderNumCString(64)商户订单号
platOrderNumCString(64)平台订单号
tenantCodeOString(32)子租户编码,不传使用默认租户
countryCodeOString(16)国家码,数字货币场景无需传

订单号二选一

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

请求示例

Content-Type: application/json
Nonce: 5d8b3f1c74a920e6b8c3

代收订单查询响应

响应体参数

字段必填类型描述
successMBoolean是否成功
codeMString响应状态码
9999:成功;其他见 异常码
msgOString响应消息,成功时为 null
timeStampMNumber服务器响应时间(毫秒级)
dataMObject响应数据对象
orderNumMString商户订单号
platOrderNumMString平台订单号
payMoneyMNumber收款数量
feeONumber手续费
未产生手续费(如订单未支付)时为 null
currencyMString币种
netWorkMString链网络
inAddressOString收款地址
尚未分配时为 null
statusMString订单状态,取值见下表

代收状态取值

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"
    }
}

代付订单查询响应

响应体参数

字段必填类型描述
successMBoolean是否成功
codeMString响应状态码
9999:成功;其他见 异常码
msgOString响应消息,成功时为 null
timeStampMNumber服务器响应时间(毫秒级)
dataMObject响应数据对象
orderNumMString商户订单号
platOrderNumMString平台订单号
amountMNumber代付数量
feeMNumber手续费
feeTypeMNumber手续费承担方式
0:代付数量内扣除;1:手续费另计
statusMNumber订单状态码,取值见 代付状态码
statusMsgMString统一展示状态
PENDING / PROCESSING / SUCCESS / FAILED / CANCELLED
currencyMString币种
netWorkMString链网络

响应示例

{
    "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"
    }
}

对账建议

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

参考