统一退款接口 ¶

提示

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

退款请求可以重复提交，多次请求会保持退款的幂等性，不会触发重复退款。但重复提交时只有 商户扩展参数、异步通知地址 、用户IP 、签名值 、请求时间字段可以传输不同的值，其他参数需要与首次下单的数值一致，传输不同的值也不会生效。

接口说明 ¶

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

请求参数 ¶

字段名	变量名	必填	类型	长度	描述	示例值
商户退款号	bizRefundNo	是	String	100	同样的商户退款号多次请求，同一退款单号多次请求只退一笔	R10893
支付订单号	orderNo	否	String	32	与商户订单号至少要传输一个，同时传输以订单号为准	1753370980523384832
商户支付订单号	businessNo	否	String	100	与订单号至少要传输一个，同时传输以订单号为准	P0001
退款金额	amount	是	Integer		要进行退款的金额，单位为分，不可以超过可退款的余额	10
退款原因	reason	否	String	150	进行退款的原因，非必填	测试退款
预留的退款扩展参数	extraParam	否	ChannelParam	2048	暂时未使用
商户扩展参数	attach	否	String	500	商户扩展参数，回调时会原样返回	id=123332
异步通知地址	notifyUrl	否	String	200	异步通知地址，为空则读取管理端的配置，此配置不会生效	http://abc.cn/noticeCallback
用户IP	clientIp	否	String	64	支持V4和V6，部分支付方式要求必填，如调用微信支付方式时	127.0.0.1
随机数	nonceStr	否	String	32	d112892e382a7093
签名值	sign	否	String	64	072695d112892e382a7093b81e6a52af
请求时间	reqTime	是	Long		使用时间戳(秒级)	123123121

响应结果 ¶

提示

业务数据包裹在公共响应参数中的data字段，在code为0时才会有返回数据。

字段名	变量名	必传	类型	示例值	描述
商户退款号	bizRefundNo	是	String	R00123	商户退款时传入的退款单号
退款号	refundNo	是	String	DEVR24051019590563000001	系统生成的退款单号
退款状态	status	是	String	success	见退款状态说明
状态码	code	是	Integer	0
错误信息	msg	否	String	关闭失败	状态非0时会有返回值
响应时间	resTime	是	Long	123123121
响应数据签名值	sign	是	String	072695d112892e382a7093b81e6a52af	对响应内容进行签名

错误码 ¶

状态码	名称	备注
0	成功	退款发起成功

HTTP请求示例 ¶

请求参数 ¶

json

{
    "bizRefundNo": "R77292",
    "bizOrderNo": "SDK_1715341621498",
    "amount": 19,
    "attach": "{回调参数}",
    "notifyUrl": "https://abc.com/callback",
    "clientIp": "127.0.0.1",
    "sign": "69c0845c4c1b0c1b4820cd9430b1938386bb43ea1e7d521484b0cb2297eac7b4",
    "reqTime": 1715342344
}

响应参数(正常) ¶

json

{
    "msg": "success",
    "code": 0,
    "data": {
        "refundNo": "DEVR24051020531763000004",
        "bizRefundNo": "R10893",
        "sign": "fc35c71844a49f5ca0cd3aebea65395b13e672d607f7d7788ec4c49e6c062849",
        "code": "0",
        "resTime": 1715345598
    },
    "traceId": "sNiSFTXDufTR"
}

响应参数(正常) ¶

json

{
  "msg": "success",
  "code": 0,
  "data": {
    "sign": "2bcc5ac7902379d65dc9901186cd81a2833835a30d5a59b3b1860df82f012557",
    "code": "1",
    "msg": "当前订单状态[退款中]不允许发起退款操作",
    "resTime": 1715345296
  },
  "traceId": "7UEqCd1v3fcZ"
}

SDK请求示例 ¶

提示

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

java

package cn.daxpay.single.sdk.payment;

import cn.daxpay.single.sdk.code.SignTypeEnum;
import cn.daxpay.single.sdk.model.refund.RefundModel;
import cn.daxpay.single.sdk.net.DaxPayConfig;
import cn.daxpay.single.sdk.net.DaxPayKit;
import cn.daxpay.single.sdk.param.refund.RefundParam;
import cn.daxpay.single.sdk.response.DaxPayResult;
import cn.daxpay.single.sdk.util.PaySignUtil;
import cn.hutool.core.util.RandomUtil;
import org.junit.Before;
import org.junit.Test;

/**
 * 退款接口测试
 * 支持部分退款和全部退款, 部分退款的次数不要超过10次, 否则可能会出现不可知的错误
 *
 * @author xxm
 * @since 2024/2/5
 */
public class RefundOrderTest {

    @Before
    public void init() {
        // 初始化支付配置
        DaxPayConfig config = DaxPayConfig.builder()
                .serviceUrl("http://127.0.0.1:9000")
                .signSecret("123456")
                .signType(SignTypeEnum.HMAC_SHA256)
                .build();
        DaxPayKit.initConfig(config);
    }

    /**
     * 退款
     */
    @Test
    public void refund(){
        RefundParam param = new RefundParam();
        param.setBizRefundNo("R" + RandomUtil.randomNumbers(5));
        param.setBizOrderNo("SDK_1715341621498");
        param.setAmount(1);
        param.setAttach("{回调参数}");
        param.setNotifyUrl("https://abc.com/callback");
        param.setClientIp("127.0.0.1");

        DaxPayResult<RefundModel> execute = DaxPayKit.execute(param);
        System.out.println(JSONUtil.toJsonStr(execute));
    }

}