GET · /api/v1/payment/orders/by-app-order-no
按单号查询支付订单
按商户业务单号查询支付订单完整状态,含汇率快照、到账金额、异常与回调任务信息。适合在回调丢失时做主动补偿。
/api/v1/payment/orders/by-app-order-no HMAC 查询时若订单已到过期时间,会先按规则把状态刷新为 EXPIRED(并触发过期回调)再返回,所以查询结果总是最新状态。
Header 参数
X-Api-Keystring required | 应用 apiKey。沙箱前缀 pk_test_,正式 pk_live_。 例: pk_test_4f9d8ab1c0e74... |
X-Timestampinteger (UNIX 毫秒) required | 请求发起时刻的 UNIX 毫秒时间戳(13 位整数)。与服务端时差不能超过 ±300000ms(5 分钟)。 例: 1746450000000 |
X-Noncestring required | 本次请求的随机串,建议 UUID v4 或 16 字节 hex。同一 (apiKey, nonce) 在 10 分钟窗口内不可重复。 例: 8e3a1c2f7b6d4a90 |
X-Signaturestring required | HMAC-SHA256 签名(小写 hex,64 字符)。算法: HMAC(secret, METHOD + "\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + SHA256(body))。详见 鉴权章节。 例: 6e4a8c1f...(64 字符) |
Query 参数
appOrderNostring required | 下单时传入的商户业务单号。 例: ORDER_20261023_0001 |
请求示例
# 签名算法(stringToSign / 4 个 header)见 /docs/api/auth
API_KEY=pk_test_xxx
SECRET=sk_test_xxx
METHOD=GET
REQ_PATH='/api/v1/payment/orders/by-app-order-no?appOrderNo=ORDER_20261023_0001'
BODY='' # GET 无 body,SHA-256 取空串
TS=$(( $(date +%s) * 1000 ))
NONCE=$(uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')
BODY_SHA=$(printf "%s" "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIG=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$REQ_PATH" "$TS" "$NONCE" "$BODY_SHA" \
| openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X GET "https://api.pqpa.com$REQ_PATH" \
-H "X-Api-Key: $API_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIG"响应
200OK
{
"code": 0,
"data": {
"id": 5001,
"appOrderNo": "ORDER_20261023_0001",
"checkoutUrl": "https://pay.example.com/checkout/3f9c...e1",
"fiatCurrency": "USD",
"fiatAmount": 100.00,
"payCurrency": "USDT",
"chainId": 3,
"chainCode": "TRON",
"chainTokenId": 50,
"tokenSymbol": "USDT",
"payAmount": 100.010001,
"rateSnapshotId": 7001,
"rate": 0.99990000,
"rateSource": "THIRD_PARTY",
"rateLockTime": 1792732500000,
"rateExpireTime": 1792732800000,
"rateExpireTimeMillis": 1792732800000,
"ratePrecision": 8,
"payPrecision": 6,
"slippageBps": 0,
"paidAmount": 100.010001,
"overpaidAmount": 0,
"supplementExpireTime": null,
"exceptionReason": null,
"handlingStatus": "NONE",
"payAddress": "TXyz...abc",
"memo": null,
"status": "PAID",
"txHash": "a1b2c3...",
"callbackTaskId": 88001,
"partialCallbackTaskId": null,
"expireTime": 1792732800000,
"expireTimeMillis": 1792732800000,
"extras": "{\"userId\":\"u_1024\"}",
"createTime": 1792732500000,
"updateTime": 1792732620000
},
"msg": ""
}data 字段说明
idinteger required | 支付订单 id(回调 payload 的 id 同值)。 |
appOrderNostring required | 商户业务单号。 |
checkoutUrlstring required | 托管付款页地址。 |
fiatCurrency / fiatAmountstring? / number? optional | 法币币种 / 金额;直接按币数下单时为 null。 |
payCurrencystring? optional | 收款币种;未选币(AWAITING_CURRENCY)时为 null。 |
chainId / chainCodeinteger? / string? optional | 公链内部 id / code。 |
chainTokenId / tokenSymbolinteger? / string? optional | 代币 id / 符号。 |
payAmountnumber? optional | 应付币种金额。 |
rateSnapshotIdinteger? optional | 汇率快照 id;直接传 payAmount 时为 null,下列汇率字段同理。 |
rate / rateSourcenumber? / string? optional | 汇率(1 payCurrency = rate fiatCurrency)/ 报价来源 THIRD_PARTY · LOCAL_TABLE · MOCK。 |
rateLockTimeinteger? optional | 锁价时间(毫秒)。 |
rateExpireTime / rateExpireTimeMillisinteger? optional | 锁价过期时间(毫秒,两字段同值)。 |
ratePrecision / payPrecision / slippageBpsinteger? optional | 报价精度 / 支付币种精度 / 滑点(bps)。 |
paidAmountnumber required | 累计已到账金额。 |
overpaidAmountnumber required | 多付金额(paidAmount − payAmount,不小于 0)。 |
supplementExpireTimeinteger? optional | 补款截止时间(毫秒);首次部分到账时设置。 |
exceptionReasonstring? optional | 异常原因,取值见异常单。 |
handlingStatusstring required | 异常处理状态:NONE / PENDING / PROCESSING / RESOLVED / IGNORED。 |
payAddress / memostring? optional | 收款地址 / Memo(Tag)。 |
statusstring required | 订单状态,见状态说明。 |
txHashstring? optional | 最近一次匹配的交易哈希。 |
callbackTaskIdinteger? optional | |
partialCallbackTaskIdinteger? optional | 部分支付回调任务 id。 |
expireTime / expireTimeMillisinteger required | 订单过期时间(毫秒,两字段同值)。 |
extrasstring? optional | 下单时传入的扩展字段。 |
createTime / updateTimeinteger required | 创建 / 更新时间(毫秒)。 |
错误码
| code | 名称 | 说明 |
|---|---|---|
1007004020 | PAYMENT_ORDER_NOT_FOUND | 支付订单不存在或不属于当前应用。按单号查询、收银台 checkoutToken 无效时都返回此码。 |