查询退款

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

Query 请求参数

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

GET /v1/refund-orders?third_refund_no=REFUND202610220001

成功响应

{
  "request_id": "7d5f6832c7494cb28e413f97f8460981",
  "code": 0,
  "message": "成功",
  "data": {
    "refund_id": "202610220000000043",
    "order_id": "202610220000000042",
    "app_id": "1234567890",
    "third_order_no": "ORDER202610220001",
    "third_refund_no": "REFUND202610220001",
    "currency": "USDT",
    "refund_amount": "3.33",
    "fee_refund_amount": "0.20",
    "merchant_debit_amount": "3.13",
    "status": "SUCCESS",
    "callback_url": "https://merchant.example.com/notify/refund",
    "failure_reason": "",
    "create_time": "2026-10-22T00:00:00Z",
    "success_time": "2026-10-22T00:00:01Z",
    "update_time": "2026-10-22T00:00:01Z"
  }
}

字段	类型	说明
data.callback_url	string	本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知
data.refund_id	string	平台退款ID，YYYYMMDD + 10位随机数字，表内唯一
data.order_id	string	平台订单ID，YYYYMMDD + 10位随机数字，表内唯一
data.app_id	string	商户 APPID，由鉴权请求头确定
data.third_order_no	string	原收款订单的三方订单号
data.third_refund_no	string	三方退款单号，1–32 个字符，同一 APPID 下唯一
data.currency	string	币种，固定为 USDT
data.refund_amount	string	退款金额，USDT，正数金额字符串，最多 24 位整数、2 位小数
data.fee_refund_amount	string	本次实际退还手续费；仅成功时结算，处理及失败时为 0.00
data.merchant_debit_amount	string	本次商户实际扣款 = 退款金额 − 退还手续费；仅成功时结算，处理及失败时为 0.00
data.status	string	退款状态：PROCESSING 处理中，SUCCESS 成功，FAILED 失败
data.failure_reason	string	退款失败原因；非失败状态为空字符串
data.create_time	string	创建时间，RFC 3339 格式，UTC 时区
data.success_time	string	退款成功时间，RFC 3339 / UTC；未成功时为空字符串
data.update_time	string	更新时间，RFC 3339 格式，UTC 时区

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

业务错误

code	message	处理方式
1025	退款订单不存在	检查当前 APPID 下的 third_refund_no。

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