Appearance
统一退款接口 ¶
提示
当交易发生之后一段时间内,可以通过统一退款接口将支付款退还给买家,支持多次退款,超过约定时间的订单无法进行退款。除了使用接口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 | 对响应内容进行签名 |
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));
}
}