退款接口

退款模块用于支付完成后的售后处理，支持发起退款、查询退款和接收退款通知。

接口清单

接口	方法	说明
/api/refund/refundOrder	POST	发起退款
/api/refund/query	POST	查询退款订单
notifyUrl	POST	退款通知

发起退款核心字段

字段	必填	说明
payOrderId / mchOrderNo	是	平台支付订单号与商户订单号二选一
mchRefundNo	是	商户退款单号，需唯一
refundAmount	是	退款金额，单位分
currency	是	货币代码，建议 CNY
refundReason	是	退款原因
clientIp	否	客户端 IP
notifyUrl	否	退款通知地址
channelExtra	否	渠道扩展参数
extParam	否	业务扩展参数，通知时原样返回

发起退款示例

{
  "mchNo": "M202604230001",
  "appId": "APP202604230001",
  "payOrderId": "P202604230001",
  "mchRefundNo": "RF202604230001",
  "refundAmount": 300,
  "currency": "CNY",
  "refundReason": "用户退货",
  "clientIp": "127.0.0.1",
  "notifyUrl": "https://merchant.example.com/notify/refund",
  "version": "1.0",
  "reqTime": 1713849600000,
  "signType": "MD5",
  "sign": "YOUR_SIGN"
}

退款状态建议

状态值	含义
0	订单生成
1	退款中
2	退款成功
3	退款失败
4	退款关闭

查询退款订单

查询时通常传以下任一字段：

字段	说明
refundOrderId	平台退款单号
mchRefundNo	商户退款单号

返回数据建议重点关注：

• refundAmount
• payAmount
• state
• channelOrderNo
• errCode
• errMsg
• successTime

退款通知

退款成功或失败后，平台会向 notifyUrl 推送通知。建议回调处理重点校验：

• refundOrderId
• mchRefundNo
• payOrderId
• refundAmount
• state
• sign

通知侧也应采用幂等更新，避免同一笔退款重复落账或重复更新售后状态。