申请退款
接口说明
对已支付成功的订单发起退款。
注意：
- 支持部分退款和全额退款
- 退款金额不能超过订单可退款余额（查询订单返回的
refundableBalance） - 同一笔订单的多次退款请求，
bizRefundNo必须唯一（不传则由系统生成）
接口列表
退款接口属于管理 API（/mch/*），通过 Sa-Token 会话认证，响应使用 Result 包装（字段名为 message，非 msg）。
与支付 API 的区别
支付 API（/unipay/*）使用 RSA 签名认证、DaxResult 响应；退款接口使用 Accesstoken 请求头认证、Result 响应。
请求地址
POST /mch/order/refund/refund
- 认证：Sa-Token（请求头
Accesstoken） - 响应：
Result<RefundOrderResult>
请求头
| 参数名 | 必填 | 描述 |
|---|---|---|
| Accesstoken | 是 | Sa-Token 会话令牌 |
| Content-Type | 是 | application/json |
请求参数
RefundParam：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| tradeNo | string | 否* | 原支付资金交易号（平台 tradeNo） |
| bizOrderNo | string | 否* | 商户业务订单号 |
| amount | long | 是 | 退款金额，单位分（@Positive，必须大于 0） |
| bizRefundNo | string | 否 | 商户退款号（不传由系统生成） |
| reason | string | 否 | 退款原因 |
*
tradeNo、bizOrderNo至少传一个，优先使用tradeNo。tradeNo解析时若按资金号查不到，会再尝试网关容器orderNo反查。
请求示例
json
{
"bizOrderNo": "ORDER20241201001",
"amount": 100,
"bizRefundNo": "REFUND20241201001",
"reason": "用户申请退款"
}响应参数
Result<RefundOrderResult>，data 字段结构（主要字段，完整 27 字段见源码 RefundOrderResult）：
| 参数 | 类型 | 描述 |
|---|---|---|
| id | long | 退款单 ID |
| mchNo | string | 商户号 |
| mchName | string | 商户名称（翻译） |
| appId | string | 应用号 |
| refundNo | string | 系统退款号 |
| bizRefundNo | string | 商户退款号 |
| relationOrderNo | string | 实际上送通道的关联号 |
| title | string | 标题 |
| tradeNo | string | 原支付资金交易号 |
| tradeType | string | 原支付交易形态 |
| bizOrderNo | string | 原商户订单号 |
| outOrderNo | string | 通道支付订单号 |
| outRefundNo | string | 通道退款流水号 |
| amount | long | 退款金额（分） |
| orderAmount | long | 原订单总金额（分） |
| currency | string | 币种 |
| reason | string | 退款原因 |
| status | string | 退款状态（RefundOrderStatusEnum） |
| finishTime | string | 退款完成时间（UTC） |
| channel | string | 支付通道 |
| product | string | 支付产品 |
| channelMchNo | string | 通道商户号 |
| channelAppId | string | 通道应用 AppId |
| notifyUrl | string | 异步通知地址 |
| attach | string | 商户附加参数 |
| clientIp | string | 客户端 IP |
| storeNo | string | 门店号 |
| errorMsg | string | 错误信息（失败时） |
退款状态（RefundOrderStatusEnum）
| status | 说明 |
|---|---|
| progress | 退款中（已创建并调用通道，等待结果） |
| success | 退款成功 |
| fail | 退款失败 |
| close | 退款关闭（超时未确认等） |
响应示例
json
{
"code": 0,
"message": "success",
"data": {
"id": "1853123456789012345",
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"bizOrderNo": "ORDER20241201001",
"tradeNo": "T2024120112345700001",
"amount": 100,
"orderAmount": 100,
"status": "progress",
"reason": "用户申请退款"
}
}退款回调
退款成功后，平台会向原支付订单的 notifyUrl 发送 event=refund.success 的异步通知，报文结构见 异步回调。