查询收款订单

按三方订单号查询当前 APPID 下的收款订单。请求使用签名鉴权。

Query 请求参数

参数	类型	必填	说明
third_order_no	string	是	三方订单号，1–32 个字符

GET /v1/payment-orders?third_order_no=ORDER202610220001

成功响应

{
  "request_id": "7d5f6832c7494cb28e413f97f8460981",
  "code": 0,
  "message": "成功",
  "data": {
    "pay_url": "https://t.me/example_bot?start=pay_202610220000000042",
    "expires_at": "2026-10-22T00:20:00Z",
    "order_id": "202610220000000042",
    "app_id": "1234567890",
    "third_order_no": "ORDER202610220001",
    "currency": "USDT",
    "payment_amount": "10.00",
    "fee_amount": "0.63",
    "fee_rate": "636",
    "actual_amount": "9.37",
    "status": "PENDING",
    "refund_status": "NONE",
    "custom_params": "customer=example",
    "callback_url": "https://merchant.example.com/notify/payment",
    "create_time": "2026-10-22T00:00:00Z",
    "close_time": "",
    "pay_time": "",
    "update_time": "2026-10-22T00:00:00Z"
  }
}

字段	类型	说明
data.pay_url	string	Telegram 付款链接，打开后由付款人确认支付
data.expires_at	string	订单到期时间，RFC 3339 / UTC
data.callback_url	string	本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知
data.order_id	string	平台订单ID，YYYYMMDD + 10位随机数字，表内唯一
data.app_id	string	商户 APPID，由鉴权请求头确定
data.third_order_no	string	三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019
data.currency	string	币种，固定为 USDT
data.payment_amount	string	收款金额，USDT，正数；最多 24 位整数、2 位小数
data.fee_amount	string	手续费 = 收款金额 × 费率基点 ÷ 10000；截断至 2 位小数，不四舍五入
data.fee_rate	string	订单费率，基点整数 0–10000；636 表示 6.36%
data.actual_amount	string	收款金额 − 手续费；待支付时为预计到账金额
data.status	string	订单状态：PENDING 待支付，TIMEOUT 已超时，PAID 已支付，CLOSED 已关闭
data.refund_status	string	退款状态：NONE 无退款，PARTIAL 部分退款，FULL 全额退款
data.custom_params	string	自定义参数，最多 500 字符；原样返回，默认空字符串
data.create_time	string	创建时间，RFC 3339 格式，UTC 时区
data.close_time	string	关闭时间，RFC 3339 / UTC；未关闭时为空字符串
data.pay_time	string	付款时间，RFC 3339 / UTC；未支付时为空字符串
data.update_time	string	更新时间，RFC 3339 格式，UTC 时区

公共响应字段见通用约定。

业务错误

code	message	处理方式
1020	收款订单不存在	检查当前 APPID 下的 third_order_no；不能查询其他 APPID 的订单。

完整错误码见错误码，调用示例见开发资源。