申请退款
对已支付的收款订单申请退款。受理后返回处理中状态，通过结果通知或查询接口确认最终结果。请求使用签名鉴权。
JSON 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
third_order_no | string | 是 | 原收款订单的三方订单号 |
third_refund_no | string | 是 | 三方退款单号，1–32 个字符，同一 APPID 下唯一 |
refund_amount | string | 是 | 退款金额，USDT，正数金额字符串，最多 24 位整数、2 位小数 |
callback_url | string | 否 | 本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知 |
json
{
"third_order_no": "ORDER202610220001",
"third_refund_no": "REFUND202610220001",
"refund_amount": "3.33",
"callback_url": "https://merchant.example.com/notify/refund"
}退款规则
- 一笔收款可多次退款，成功与处理中的退款合计不得超过原收款金额。
- 相同退款单号、原订单号、金额及回调地址重复请求返回原退款单；参数不同返回
1023。失败后重新申请须使用新退款单号。 - 仅成功时扣除商户账户余额并退回原付款账户；余额不足时退款失败。
- 累计应退手续费 = 原手续费 × 累计成功退款金额 ÷ 原收款金额，直接截断至两位小数。本次退还金额减去此前已退手续费，全额退完时退清剩余手续费。
- 商户实际扣款 = 本次退款金额 − 本次退还手续费。
成功响应
json
{
"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.00",
"merchant_debit_amount": "0.00",
"status": "PROCESSING",
"callback_url": "https://merchant.example.com/notify/refund",
"failure_reason": "",
"create_time": "2026-10-22T00:00:00Z",
"success_time": "",
"update_time": "2026-10-22T00:00:00Z"
}
}| 字段 | 类型 | 说明 |
|---|---|---|
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 | 处理方式 |
|---|---|---|
| 1020 | 收款订单不存在 | 检查当前 APPID 下的 third_order_no；不能查询其他 APPID 的订单。 |
| 1021 | 退款金额格式不正确 | refund_amount 必须为正数金额字符串，最多 24 位整数、2 位小数。 |
| 1022 | 收款订单尚未支付 | 仅已支付订单支持退款。 |
| 1023 | 退款单号已存在且参数不一致 | 同一 APPID 下退款单号唯一；重试须使用原订单号、退款金额及回调地址。 |
| 1024 | 退款金额超过可退金额 | 原收款金额减去成功及处理中的退款金额，为当前可退金额。 |
| 1026 | 收款订单付款人信息不完整 | 联系服务方核实原收款订单。 |
| 1027 | 回调地址格式不正确 | callback_url 可不传或为空字符串；填写时须为有效 HTTPS 地址，最多 2048 字节，不允许账号密码、片段或空白字符。 |
填写 callback_url 后，订单结果按结果通知发送；未填写则不通知。