GET · /api/v1/payment/orders/by-app-order-no

按单号查询支付订单

按商户业务单号查询支付订单完整状态,含汇率快照、到账金额、异常与回调任务信息。适合在回调丢失时做主动补偿。

GET/api/v1/payment/orders/by-app-order-no HMAC

查询时若订单已到过期时间,会先按规则把状态刷新为 EXPIRED(并触发过期回调)再返回,所以查询结果总是最新状态。

Header 参数

X-Api-Key
string required
应用 apiKey。沙箱前缀 pk_test_,正式 pk_live_。
例: pk_test_4f9d8ab1c0e74...
X-Timestamp
integer (UNIX 毫秒) required
请求发起时刻的 UNIX 毫秒时间戳(13 位整数)。与服务端时差不能超过 ±300000ms(5 分钟)。
例: 1746450000000
X-Nonce
string required
本次请求的随机串,建议 UUID v4 或 16 字节 hex。同一 (apiKey, nonce) 在 10 分钟窗口内不可重复。
例: 8e3a1c2f7b6d4a90
X-Signature
string required
HMAC-SHA256 签名(小写 hex,64 字符)。算法:HMAC(secret, METHOD + "\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + SHA256(body))。详见 鉴权章节。
例: 6e4a8c1f...(64 字符)

Query 参数

appOrderNo
string required
下单时传入的商户业务单号。
例: ORDER_20261023_0001

query 参与签名

签名的 PATH 要写成 /api/v1/payment/orders/by-app-order-no?appOrderNo=...,与实际请求 URL 逐字一致,见 鉴权。

请求示例

# 签名算法(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"

响应

Response
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 字段说明

id
integer required
支付订单 id(回调 payload 的 id 同值)。
appOrderNo
string required
商户业务单号。
checkoutUrl
string required
托管付款页地址。
fiatCurrency / fiatAmount
string? / number? optional
法币币种 / 金额;直接按币数下单时为 null。
payCurrency
string? optional
收款币种;未选币(AWAITING_CURRENCY)时为 null。
chainId / chainCode
integer? / string? optional
公链内部 id / code。
chainTokenId / tokenSymbol
integer? / string? optional
代币 id / 符号。
payAmount
number? optional
应付币种金额。
rateSnapshotId
integer? optional
汇率快照 id;直接传 payAmount 时为 null,下列汇率字段同理。
rate / rateSource
number? / string? optional
汇率(1 payCurrency = rate fiatCurrency)/ 报价来源 THIRD_PARTY · LOCAL_TABLE · MOCK。
rateLockTime
integer? optional
锁价时间(毫秒)。
rateExpireTime / rateExpireTimeMillis
integer? optional
锁价过期时间(毫秒,两字段同值)。
ratePrecision / payPrecision / slippageBps
integer? optional
报价精度 / 支付币种精度 / 滑点(bps)。
paidAmount
number required
累计已到账金额。
overpaidAmount
number required
多付金额(paidAmount − payAmount,不小于 0)。
supplementExpireTime
integer? optional
补款截止时间(毫秒);首次部分到账时设置。
exceptionReason
string? optional
异常原因,取值见异常单。
handlingStatus
string required
异常处理状态:NONE / PENDING / PROCESSING / RESOLVED / IGNORED。
payAddress / memo
string? optional
收款地址 / Memo(Tag)。
status
string required
订单状态,见状态说明。
txHash
string? optional
最近一次匹配的交易哈希。
callbackTaskId
integer? optional
已支付回调任务 id,可用于查回调尝试、重发。
partialCallbackTaskId
integer? optional
部分支付回调任务 id。
expireTime / expireTimeMillis
integer required
订单过期时间(毫秒,两字段同值)。
extras
string? optional
下单时传入的扩展字段。
createTime / updateTime
integer required
创建 / 更新时间(毫秒)。

错误码

code名称说明
1007004020PAYMENT_ORDER_NOT_FOUND支付订单不存在或不属于当前应用。按单号查询、收银台 checkoutToken 无效时都返回此码。