注册商户

GET · /api/v1/wallet/withdraw/get-by-business-id

查询单笔提现

按商户业务单号（appOrderNo）查询提现记录的当前状态。收到 WITHDRAW 回调后，建议用此接口反查最新状态做对账。

对账最佳实践

收到 WITHDRAW 系列回调时，不要直接信任 payload 里的 status。 建议用 payload 中的 appOrderNo 调本接口拿当前状态—— payload 是事件快照，网络重试或乱序可能让你拿到旧值。
GET/api/v1/wallet/withdraw/get-by-business-id HMAC

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_2026050501

请求示例

# 签名算法（stringToSign / 4 个 header）见 /docs/api/auth
API_KEY=pk_test_xxx
SECRET=sk_test_xxx
METHOD=GET
APP_ORDER_NO=ORDER_2026050501
REQ_PATH="/api/v1/wallet/withdraw/get-by-business-id?appOrderNo=$APP_ORDER_NO"
TS=$(( $(date +%s) * 1000 ))
NONCE=$(uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')
# GET 请求 body 为空，body hash = SHA256("")
BODY_SHA=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
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 -G "https://api.pqpa.com/api/v1/wallet/withdraw/get-by-business-id" \
  --data-urlencode "appOrderNo=$APP_ORDER_NO" \
  -H "X-Api-Key:    $API_KEY" \
  -H "X-Timestamp:  $TS" \
  -H "X-Nonce:      $NONCE" \
  -H "X-Signature:  $SIG"

响应

Response
200OK
{
  "code": 0,
  "data": {
    "appOrderNo":    "ORDER_2026050501",
    "chainCode":     "ETH",
    "token":         "USDT",
    "amount":        "10.5",
    "fee":           "0.0021",
    "fromAddress":   "0xHotWallet000000000000000000000000000001",
    "toAddress":     "0xab12cd34ef56789000000000000000000000001",
    "memo":          null,
    "txHash":        "0x9ab8c4f7e2d1000000000000000000000000000000000000000000000000abcd",
    "blockHeight":   21430500,
    "confirmations": 12,
    "status":        "SUCCESS",
    "failReason":    null,
    "riskLevel":     null,
    "riskReason":    null,
    "callbackTaskId": 5001,
    "createTime":    "2026-05-05T12:34:56",
    "updateTime":    "2026-05-05T12:36:10"
  },
  "msg": ""
}

data 字段说明

appOrderNo
string required
商户业务单号（回填请求参数）。
chainCode
string required
公链 code。
token
string required
代币 symbol，如 USDT。
amount
string required
提现金额（字符串）。
fee
string? optional
实际链上手续费；广播前为 null。
fromAddress
string? optional
出款热钱包地址；广播前为 null。
toAddress
string required
链上收款地址。
memo
string? optional
Memo 链下的 memo；非 Memo 链为 null。
txHash
string? optional
链上交易 hash；广播前为 null。
blockHeight
integer? optional
所在区块高度；确认前为 null。
confirmations
integer required
当前确认数。
status
string required
提现状态枚举。
取值：PROCESSINGBROADCASTEDCONFIRMINGSUCCESSFAILEDCANCELLED
failReason
string? optional
FAILED 时的失败原因；其它状态为 null。
riskLevel
string? optional
风控评级（如 HIGH）；未触发风控时为 null。
riskReason
string? optional
风控原因说明；未触发风控时为 null。
callbackTaskId
integer? optional
关联的回调任务 id；尚未生成时为 null。
createTime
string required
提现单创建时间，格式 yyyy-MM-ddTHH:mm:ss。
updateTime
string required
最后更新时间。

状态机

同一笔提现的 status 演化路径：

发起提现
      │
      ▼
 PROCESSING ──► BROADCASTED ──► CONFIRMING ──► SUCCESS  ✅ → 推送 WITHDRAW_SUCCESS 回调
      │               │
      │               └─ 链上 revert / 重组 ──────────► FAILED    ❌ → 推送 WITHDRAW_FAILED 回调
      │
      └─ 风控拦截 / 余额不足 / 人工拒绝 ─────────────► CANCELLED  ⛔ → 推送 WITHDRAW_CANCELLED 回调

下一步