统一退款接口 ¶

提示

当交易发生之后一段时间内，可以通过统一退款接口将支付款退还给买家，支持多次退款，超过约定时间的订单无法进行退款。除了使用接口API方式对订单退款，也可以在管理后台使用界面进行手工操作。

退款请求可以重复提交，多次请求会保持退款的幂等性，不会触发重复退款。但重复提交时参数需要与首次下单的数值一致，传输不同的值也不会生效。

接口说明 ¶

参数	说明
请求URL	`/unipay/refund`
请求方式	`POST`
请求类型	`application/json`

请求参数 ¶

业务参数 ¶

提示

设置参数时，不要忘了设置公共请求参数调用说明，未做特殊说明所有接口都需要传输

字段名	变量名	必填	类型	长度	描述	示例值
商户退款号	bizRefundNo	是	String	100	同样的商户退款号多次请求，同一退款单号多次请求只退一笔	R10893
支付订单号	orderNo	否	String	100	不可同时为空，支付订单号 > 商户订单号 > 通道订单号	1753370980523384832
商户支付订单号	bizOrderNo	否	String	100	不可同时为空，支付订单号 > 商户订单号 > 通道订单号	P0001
通道支付订单号	outOrderNo	否	String	100	不可同时为空，支付订单号 > 商户订单号 > 通道订单号	2025110024006610001
退款金额	amount	是	BigDecimal	8,2	10.12	要进行退款的金额，,单位为元，保留两位小数
退款原因	reason	否	String	150	进行退款的原因，非必填	测试退款
预留的退款扩展参数	extraParam	否	ChannelParam	2048	暂时未使用
商户扩展参数	attach	否	String	500	商户扩展参数，回调时会原样返回	id=123332
异步通知地址	notifyUrl	否	String	200	异步通知地址	http://abc.cn/noticeCallback

响应结果 ¶

业务响应参数 ¶

提示

业务数据在公共响应参数中的data字段，在code为0时才会有返回数据，见调用说明。

字段名	变量名	必传	类型	示例值	描述
退款号	refundNo	是	String	DEVR24051019590563000001	系统生成的退款单号
商户退款号	bizRefundNo	是	String	R00123	商户退款时传入的退款单号
退款状态	status	是	String	success	见退款状态说明
错误提示	errorMsg	否	String	success	如果退款状态为失败时, 会返回此字段

HTTP请求示例 ¶

请求参数 ¶

json

{
  "bizRefundNo" : "R91379",
  "orderNo" : "DEV_P2025041010494470000001",
  "amount" : 0.01,
  "attach" : "{回调参数}",
  "mchNo" : "M1723635576766",
  "appId" : "M8207639754663343",
  "clientIp" : "127.0.0.1",
  "sign" : "d770e54d5e26923e6e2f53580fcf5271",
  "reqTime" : "2025-04-10 11:16:07"
}

响应参数(成功) ¶

json

{
  "code" : 0,
  "msg" : "success",
  "data" : {
    "refundNo" : "DEV_R2025041011160870000002",
    "bizRefundNo" : "R91379",
    "status" : "success"
  },
  "sign" : "eb086247f42a6c8c7f12e24a2e06fa7d",
  "resTime" : "2025-04-10 11:16:10",
  "traceId" : "t6h0RaYLoa8E"
}

响应参数(失败) ¶

json

{
  "code" : 20044,
  "msg" : "只有失败状态的才可以重新发起退款",
  "sign" : "71f9bca7bb4c35f116d2965e2961c7c6",
  "resTime" : "2025-04-10 11:17:01",
  "traceId" : "m6sGgqQ2iUdd"
}

SDK请求示例 ¶

提示

使用SDK可以简化接入支付的速度

java

public void refund(){
    RefundParam param = new RefundParam();
    param.setBizRefundNo("R" + RandomUtil.randomNumbers(5));
    param.setOrderNo("DEV_P2025041010494470000001");
    param.setAmount(BigDecimal.valueOf(0.01));
    param.setAttach("{回调参数}");
    param.setClientIp("127.0.0.1");

    DaxPayResult<RefundResult> execute = DaxPayKit.execute(param);
    System.out.println(JsonUtil.toJsonStr(execute));
    System.out.println(DaxPayKit.verifySign(execute));
}

回调消息通知 ¶

如果设置了异步通知地址，则订单将会在发生变动后给该地址发送通知消息，数据格式见回调和订阅消息接收，业务数据格式与查询退款订单中的数据格式一致

通知示例 ¶

json

{
    "mchNo": "M1723635576766",
    "appId": "M8207639754663343",
    "code": 0,
    "msg": "success",
    "data": {
        "orderId": "1911366655705894912",
        "orderNo": "DEV_P2025041318313670000003",
        "outOrderNo": "2025041322001404211436125851",
        "bizOrderNo": "PAY_65080159831744540293248",
        "title": "测试支付",
        "refundNo": "DEV_R2025041318421670000005",
        "bizRefundNo": "REFUND_69613599721744540898044",
        "channel": "ali_pay",
        "orderAmount": 0,
        "amount": 0.01,
        "reason": "测试退款",
        "finishTime": "2025-04-13 18:42:19",
        "status": "success",
        "clientIp": "127.0.0.1"
    },
    "sign": "054be962401f68682be41e781a55643a",
    "resTime": "2025-04-13 18:43:33",
    "traceId": "Jla3Ihi8FS9Z"
}