查询订单
查询支付订单的当前状态及补款记录。
认证方式
查询类接口不使用请求头 HMAC 签名，而是靠请求体里的 accessSign 认证：
accessSign = HMACSHA256(secretKey, 把 payOrderId 和 merchantOrderId 按不区分大小写升序排序后直接拼接)结果是大写十六进制字符串（64 字符）。
IMPORTANT
你不需要自己算 accessSign——创建订单的响应里就带了 data.accessSign， 把它连同 payOrderId 一起落库，后续查询和确认支付直接回传即可。官方 SDK 也是这么用的。
查询订单状态
接口
POST /v4.0.0/api/orders/query请求
json
{
"payOrderId" : "01K...H8",
"merchantOrderId" : "aaf...-8",
"accessSign" : "AA377...F5"
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
payOrderId | string | 是 | HashNut 生成的订单 ID（26 位 ULID） |
merchantOrderId | string | 是 | 您的订单标识符 |
accessSign | string | 是 | 创建订单时返回的 accessSign，原样回传 |
WARNING
三个字段都是必填，缺任何一个都会报错（服务端直接读这三个键）。
响应
json
{
"code" : 0,
"msg" : "success",
"ui" : null,
"version" : null,
"count" : 0,
"data" : {
"merchantAddress" : "0x17a7...042",
"merchantChannel" : "default",
"blockChain" : "ETH",
"tokenSymbol" : "usdt",
"createChannel" : 1,
"accessChannel" : 0,
"merchantOrderId" : "aaff...-8",
"payOrderId" : "01KZ...H8",
"tokenAddress" : "0xdac17f958d2ee523a2206206994597c13d831ec7",
"receiptAddress" : "0x58b1...2c4",
"amount" : 0.05,
"state" : 1,
"accessSign" : "AA3777...6F5",
"payTxId" : "0x4a96...2a0",
"rate" : 80,
"obtainAmount" : 0.0496,
"platformFee" : 4.0E-4,
"expireDuration" : "60000",
"underPaid" : true,
"paidAmount" : 0.03,
"supplementCount" : 1,
"errorCode" : "failed",
"errorMsg" : "amount not enough",
"createTime" : 1785753243948,
"supplements" : [ {
"supplementId" : "01KZ...3",
"payOrderId" : "01K..H8",
"supplementAmount" : 0.02,
"paidAmount" : 0.0,
"underPaid" : false,
"receiptAddress" : "0x58...c4",
"state" : 0,
"reason" : "amount not enough",
"createTime" : 1785753770316
}, {
"supplementId" : "01KZ..BWT",
"payOrderId" : "01K..8",
"supplementAmount" : 0.04,
"paidAmount" : 0.02,
"underPaid" : true,
"payTxId" : "0x269...f7",
"receiptAddress" : "0x58b..c4",
"state" : 1,
"reason" : "amount not enough",
"errorCode" : "failed",
"errorMsg" : "amount not enough",
"createTime" : 1785753722283
} ]
}
}字段与创建订单基本一致，查询接口额外返回这几项：
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 0 表示成功，非零表示错误 |
msg | string | 可读的消息文本 |
data.merchantAddress | string | 部署分账合约的商户地址 |
data.merchantChannel | string | 商户下单渠道，如果入参为空，则返回默认的default |
data.blockChain | string | 区块链名称（如 ETH、TRON、BSC、POLYGON） |
data.tokenSymbol | string | 代币符号（如 usdt、usdc） |
data.createChannel | integer | 下单渠道，0 = 通过商户系统下单,1 = 通过 api key 下单 |
data.accessChannel | integer | 默认为0 |
data.merchantOrderId | string | 商户下单时填入的商户订单号 |
data.payOrderId | string | HashNut 生成的唯一订单ID（26 位 ULID） |
data.tokenAddress | string | 支付订单的 token 合约地址，比方说: USDT的合约地址 |
data.receiptAddress | string | 订单收款地址，客户支付订单时需要发送 token 到该地址 |
data.amount | number | 订单应付金额 |
data.state | integer | 订单状态（0 = INIT）。参见订单状态 |
data.accessSign | string | 后续查询 / 确认订单必须回传的凭证，请落库保存 |
data.payTxId | string | 首次支付该订单的交易Id，请落库保存 |
data.rate | integer | 手续费率，除以 rateBase 得到实际比率 |
data.obtainAmount | number | 扣除平台手续费后商户实收金额 |
data.platformFee | number | 平台手续费，商户提现时才会收取 |
data.expireDuration | string | 过期时长（秒） |
data.underPaid | bool | 订单是否被短款支付，如果用户未支付该状态为false，如果用户支付金额不足，则该字段为true，用户补款足额支付后该字段为true |
data.paidAmount | number | 用户已经支付的金额 |
data.supplementCount | integer | 未支付的补款单数量 |
data.errorCode | string | 错误码 |
data.errorMsg | string | 错误消息 |
data.createTime | date | 订单创建时间 |
data.supplements | objectArray | 补款单，如果用户未支付订单或者足额支付订单，则数组为空 |
上述示例为了展示补款单状态未能足额支付，如果用户未支付或者足额支付，则 supplements 数组为空
补款单
| 字段 | 类型 | 说明 |
|---|---|---|
supplementId | string | 补款单Id |
payOrderId | string | 需要补款的订单Id |
supplementAmount | number | 需要补款的金额 |
paidAmount | number | 已经补款的金额 |
underPaid | bool | 是否足额补款 |
payTxId | string | 支付补款单的交易Id |
receiptAddress | string | 补款单收款地址 |
state | integer | 补款单状态（0 = INIT）。参见订单状态 |
reason | string | 需要补款的原因 |
errorCode | string | 错误码 |
errorMsg | string | 错误消息 |
createTime | date | 补款单创建时间 |
NOTE
confirmCount、expireDuration、chainId、eip712ChainId 返回的是 JSON 字符串而不是数字—— 服务端把 Java 的 long / Long 统一序列化成字符串。Go SDK 用 json.Number 接，两种写法都兼容。
查询补款记录
短款订单允许客户补差额，每次补款是一条独立记录。
接口
POST /v4.0.0/api/orders/supplements # 全部记录，返回数组
POST /v4.0.0/api/orders/supplements/latest # 仅最近一条，返回单个对象（无记录时为 null）请求
两个接口的请求体相同，只需要 payOrderId：
json
{
"payOrderId" : "01KZ...H8"
}WARNING
这两个接口不校验 accessSign，也不校验请求头签名——只要 payOrderId 合法就返回数据。 请不要把 payOrderId 暴露在你自己的公开页面或前端可见的地方。
响应
json
{
"code" : 0,
"msg" : "success",
"data" : [ {
"supplementId" : "01KZ...3",
"payOrderId" : "01K..H8",
"supplementAmount" : 0.02,
"paidAmount" : 0.0,
"underPaid" : false,
"receiptAddress" : "0x58...c4",
"state" : 0,
"reason" : "amount not enough",
"createTime" : 1785753770316
} ]
}| 字段 | 类型 | 说明 |
|---|---|---|
supplementId | string | 补款单Id |
payOrderId | string | 需要补款的订单Id |
supplementAmount | number | 需要补款的金额 |
paidAmount | number | 已经补款的金额 |
underPaid | bool | 是否足额补款 |
payTxId | string | 支付补款单的交易Id |
receiptAddress | string | 补款单收款地址 |
state | integer | 补款单状态（0 = INIT）。参见订单状态 |
reason | string | 需要补款的原因 |
errorCode | string | 错误码 |
errorMsg | string | 错误消息 |
createTime | date | 补款单创建时间 |
TIP
大多数场景只需要轮询「查询订单状态」，supplementCount 大于 0 时再去拉补款明细。 更省事的做法是接支付通知，别轮询。