业务示例代码-世界杯冠军次数-98年世界杯冠军_守望先锋世界杯直播

业务示例代码

2025-09-06 02:46:57

1. 目标通过本教程的学习，你应该可以：

可以通过发起退款

可以通过查询退款结果

如果退款异常时，可以通过发起异常退款

可以接收微信支付退款结果并解析退款结果

退款时可以处理好错误码

2. 业务处理流程2.1 申请退款当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账户上。

申请退款需要2类信息：

原支付订单信息

微信支付订单号或者商户订单号

原订单金额

退款信息

商户退款单号：标识该平台商户下的退款单，同一个平台商户下不同商户退款单号表示不同的退款单

退款原因

退款金额

退款出资信息

退款回调URL

退款商品信息

1package com.java.refund;

3import com.java.demo.Create; // 使用商户平台申请退款接口：https://pay.weixin.qq.com/doc/v3/merchant/4013071036

4import static com.java.demo.Create.*;

5import com.java.utils.WXPayUtility; // 引用微信支付工具库，参考：https://pay.weixin.qq.com/doc/v3/merchant/4014931831

6import java.util.ArrayList;

8public class CreateRefundDemo {

9 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/v3/merchant/4013070756

10 // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考

11 // https://pay.weixin.qq.com/doc/v3/merchant/4013070756

12 private static String mchid = "19xxxxxxxx";

13 // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053

14 private static String certificateSerialNo = "1DDE55AD98Exxxxxxxxxx";

15 // 商户API证书私钥文件路径，本地文件路径

16 private static String privateKeyFilePath = "/path/to/apiclient_key.pem";

17 // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816

18 private static String wechatPayPublicKeyId = "PUB_KEY_ID_xxxxxxxxxxxxx";

19 // 微信支付公钥文件路径，本地文件路径

20 private static String wechatPayPublicKeyFilePath = "/path/to/wxp_pub.pem";

23 public static void main(String[] args) {

24 Create ceateRefund = new Create(

25 mchid,

26 certificateSerialNo,

27 privateKeyFilePath,

28 wechatPayPublicKeyId,

29 wechatPayPublicKeyFilePath

30 );

32 CreateRequest createRefundRequest = new CreateRequest();

34 // 原支付订单信息

35 createRefundRequest.transactionId = "4200000020202506035017900000";

36 createRefundRequest.amount = new AmountReq();

37 createRefundRequest.amount.total = 800L;

39 // 退款信息

40 // 商户退款单号生成方式商户视实际情况生成，需要保证平台商户下全局唯一

41 createRefundRequest.outRefundNo = "4200000020202506035017900000_1";

42 createRefundRequest.reason = "成团退差价";

43 createRefundRequest.amount.refund = 200L;

45 // 退款成功，退款关闭，退款异常时需要微信支付通知商户商户，可以加上回调URL，退款到这几个状态时会调用这个URL通知商户

46 createRefundRequest.notifyUrl = "https://weixin.qq.com";

48 // 退款资金来源

49 // 1. 对于出行预付押金退款

50 // - 不填写表示已结退款，从出行商户基本户出资退款

51 // - 填写UNSETTLED，表示未结退款，从押金账户出资退款

52 // 2.

53 // 对于老资金流商户（老资金流也叫旧资金流，旧资金流如何区分见：https://kf.qq.com/faq/161223N7fi2E161223EvY3Ir.html）

54 // - 不填写表示未结退款，从未结账户出资退款

55 // - 填写AVAILABLE，表示从可用余额出资退款

56 // createRefundRequest.fundsAccount = ReqFundsAccount.AVAILABLE;

58 // 退款商品信息

59 createRefundRequest.goodsDetail = new ArrayList<>();

60 {

61 GoodsDetail goodDetail = new GoodsDetail();

62 goodDetail.merchantGoodsId = "1217752501201407033233368018";

63 goodDetail.wechatpayGoodsId = "1001";

64 goodDetail.goodsName = "iPhone6s 16G";

65 goodDetail.unitPrice = 528800L;

66 goodDetail.refundAmount = 528800L;

67 goodDetail.refundQuantity = 1L;

68 createRefundRequest.goodsDetail.add(goodDetail);

69 }

71 Refund refund;

72 try {

73 refund = ceateRefund.run(createRefundRequest);

74 } catch (WXPayUtility.ApiException e) {

75 // 申请退款处理异常处理逻辑

76 if (e.getErrorCode().equals("SYSTEM_ERROR")) {

77 // 错误：系统错误

78 // 解决方式：稍后原单重试

79 // 描述：微信支付系统失败，一定要原单重试，系统失败直接立即重试大概率还会是系统失败，建议等1分钟后再重试

80 } else if (e.getErrorCode().equals("FREQUENCY_LIMITED")) {

81 // 错误：限频报错

82 // 解决方式：稍后原单重试

83 // 描述：退款接口频率限制，一定要原单重试，直接立即重试大概率还会是系统失败，建议等1分钟后再重试

84 } else if (e.getErrorCode().equals("USER_ACCOUNT_ABNORMAL")) {

85 // 错误：用户账户异常

86 // 解决方式：退款受理失败，商户可以自行处理退款，也可以登录商户平台进入交易中心发起异常退款

87 // 描述：用户注销或者被管控了，这笔订单已经不能发起退款，这个错误就不需要重试了

88 } else if (e.getErrorCode().equals("NOT_ENOUGH")) {

89 // 错误：账户余额不足

90 // 解决方式：商户充值之后原单重试

91 // 描述：商户账户余额不足，导致退款失败，商户充值之后一定要原单重试

92 } else if (e.getErrorCode().equals("NO_AUTH")) {

93 // 错误：无退款权限

94 // 解决方式：检查商户是否是被处罚：登录商户平台进入账户中心-违约记录查询是否违约记录，如果有按照上面的指引解决违约记录之后原单重试

95 // 描述：商户被处罚

96 } else if (e.getErrorCode().equals("SIGN_ERROR")) {

97 // 错误：签名错误

98 // 解决方式：检查平台商户证书序列号，证书私钥文件，公钥ID，公钥文件，同时确认下签名过程是不是按照微信支付的签名方式

99 // 描述：签名报错，需要确认签名材料和签名流程是否正确

100 } else if (e.getErrorCode().equals("PARAM_ERROR")) {

101 // 错误：参数错误

102 // 解决方式：按照报错返回的message，重新输入请求参数

103 // 描述：参数的类型，长度，或者必填选项没有填写等

104 } else if (e.getErrorCode().equals("INVALID_REQUEST")) {

105 // 错误：请求非法，请求参数正确，但是不符合退款业务规则

106 // 解决方式：根据具体message查看具体哪里不符合业务规则，如果可以修改参数达到符合业务规则的修改请求符合业务规则之后再原单重试

107 // 描述：不符合业务规则的场景如：

108 // - 交易时间超过365天，不允许发起退款

109 // - 一笔订单退款次数已经超过50次了，这笔订单不允许发起新的退款

110 // - 申请退款的金额超过了这笔订单剩余可退金额，不允许申请退款

111 } else {

112 // 其他类型错误：稍等一会后原单重试

113 }

114

115 }

116 }

117}2.2 查询退款上面申请退款成功之后，说明微信支付成功受理了这笔退款，并不是已经退款到账，商户可以通过查询退款接口查询退款结果

退款单的状态机：

1package com.java.refund;

3import com.java.demo.Create; // 使用商户平台申请退款接口：https://pay.weixin.qq.com/doc/v3/merchant/4013071036

4import static com.java.demo.Create.*;

5import com.java.demo.QueryByOutRefundNo; // 使用商户平台查询单笔退款（按商户退款单号）接口，见：https://pay.weixin.qq.com/doc/v3/merchant/4013071041

6import static com.java.demo.QueryByOutRefundNo.*;

7import com.java.demo.CreateAbnormalRefund; // 使用商户平台发起异常退款接口，见：https://pay.weixin.qq.com/doc/v3/merchant/4013071193

8import static com.java.demo.CreateAbnormalRefund.*;

9import com.java.utils.WXPayUtility; // 引用微信支付工具库，参考：https://pay.weixin.qq.com/doc/v3/merchant/4014931831

10import java.util.ArrayList;

12public class QueryRefundDemo {

13 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/v3/merchant/4013070756

14 // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考

15 // https://pay.weixin.qq.com/doc/v3/merchant/4013070756

16 private static String mchid = "19xxxxxxxx";

17 // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053

18 private static String certificateSerialNo = "1DDE55AD98Exxxxxxxxxx";

19 // 商户API证书私钥文件路径，本地文件路径

20 private static String privateKeyFilePath = "/path/to/apiclient_key.pem";

21 // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816

22 private static String wechatPayPublicKeyId = "PUB_KEY_ID_xxxxxxxxxxxxx";

23 // 微信支付公钥文件路径，本地文件路径

24 private static String wechatPayPublicKeyFilePath = "/path/to/wxp_pub.pem";

26 public static void main(String[] args) {

27 QueryByOutRefundNo client = new QueryByOutRefundNo(

28 mchid,

29 certificateSerialNo,

30 privateKeyFilePath,

31 wechatPayPublicKeyId,

32 wechatPayPublicKeyFilePath

33 );

35 QueryByOutRefundNoRequest request = new QueryByOutRefundNoRequest();

36 request.outRefundNo = "4200000020202506035017900000_1";

38 QueryByOutRefundNo.Refund refund;

39 try {

40 refund = client.run(request);

41 switch (refund.status) {

42 case SUCCESS:

43 // 终态：退款成功（退款到账）

44 // 更新商户自己的业务单据状态为成功

45 // UpdateRefund2Succ();

46 break;

47 case CLOSED:

48 // 终态：退款关闭

49 // 更新商户自己的业务单据状态为关闭

50 // UpdateRefund2Closed();

51 // 如果还需要退款，需要换单（换outRefundNo）重新申请退款

52 Create createRefund = new Create(

53 mchid,

54 certificateSerialNo,

55 privateKeyFilePath,

56 wechatPayPublicKeyId,

57 wechatPayPublicKeyFilePath

58 );

60 CreateRequest createRefundRequest = new CreateRequest();

61 // 其他参数和之前申请退款参数一样，只改商户退款单号

62 createRefundRequest.outRefundNo = "4200000020202506035017900000_2";

63 createRefund.run(createRefundRequest);

65 break;

66 case PROCESSING:

67 // 非终态：退款处理中 - 还未到账，需要隔一段时间再来查询

68 break;

69 case ABNORMAL:

70 // 非终态：退款异常 - 用户异常、用户被管控等原因不能原路退

71 // 可以用两种处理方式：

72 // 1. 商户登录商户平台进入交易中心发起异常退款，把钱退到用户指定的银行卡或者商户的银行

73 // 2. 请求异常退款API

74 CreateAbnormalRefund createAbnormalRefund = new CreateAbnormalRefund(

75 mchid,

76 certificateSerialNo,

77 privateKeyFilePath,

78 wechatPayPublicKeyId,

79 wechatPayPublicKeyFilePath

80 );

81 CreateAbnormalRefundRequest abnormalRefundRequest = new CreateAbnormalRefundRequest();

82 abnormalRefundRequest.refundId = refund.refundId;

83 abnormalRefundRequest.outRefundNo = "4200000020202506035017900000_1";

84 abnormalRefundRequest.type = AbnormalReceiveType.USER_BANK_CARD;

85 abnormalRefundRequest.bankType = "ICBC_DEBIT";

86 abnormalRefundRequest.bankAccount = createAbnormalRefund.encrypt("请填用户的银行卡号");

87 abnormalRefundRequest.realName = createAbnormalRefund.encrypt("请填收款用户姓名");

88 CreateAbnormalRefund.Refund abnormalRefund = createAbnormalRefund.run(abnormalRefundRequest);

89 // 发起异常退款成功之后，退款单会进入退款中，还是需要通过查单接口查询退款单的状态

90 break;

91 default:

92 // 非法状态

93 throw new IllegalArgumentException("微信支付退款单状态非法");

94 }

95 } catch (WXPayUtility.ApiException e) {

96 // 查询退款处理异常处理逻辑

97 if (e.getErrorCode().equals("RESOURCE_NOT_EXISTS")) {

98 // 错误：退款单不存在

99 // 解决方式：原参数申请退款

100 // 描述：退款受理没成功，原参数发起退款申请即可

101 } else if (e.getErrorCode().equals("SYSTEM_ERROR")) {

102 // 错我：系统错误

103 // 解决方式：稍后原单重试

104 // 描述：微信支付系统失败，直接立即重试大概率还会是系统失败，建议等1分钟后再重试

105 } else if (e.getErrorCode().equals("FREQUENCY_LIMITED")) {

106 // 错误：限频报错

107 // 处理逻辑：稍后原单重试

108 // 描述：退款接口频率限制，直接立即重试大概率还会是系统失败，建议等1分钟后再重试

109 } else if (e.getErrorCode().equals("NO_AUTH")) {

110 // 错误：无退款权限

111 // 处理逻辑：检查商户是否是被处罚：登录商户平台进入账户中心-违约记录查询是否违约记录，如果有按照上面的指引解决违约记录之后原单重试

112 } else if (e.getErrorCode().equals("SIGN_ERROR")) {

113 // 错误：签名错误

114 // 处理逻辑：检查平台商户证书序列号，证书私钥文件，公钥ID，公钥文件，同时确认下签名过程是不是按照微信支付的签名方式

115 // 描述：签名报错，需要确认签名材料和签名流程是否正确

116 } else if (e.getErrorCode().equals("PARAM_ERROR")) {

117 // 错误：参数错误

118 // 处理逻辑：按照报错返回的message，重新输入请求参数

119 // 描述：参数的类型，长度，或者必填选项没有填写等

120 } else {

121 // 其他类型错误：稍等一会后原单重试

122 }

123 }

124 }

125}2.3 退款结果通知如果商户申请退款时设置了notifyUrl，或者在商户平台-交易中心-交易管理-退款管理-退款配置中设置了通知URL，那么退款状态变更为SUCCESS、CLOSED或者ABNORMAL后会通过HTTP POST方法回调到这个URL上

如果退款申请是设置了notifyUrl，同时退款配置中也设置了通知URL，已退款申请的URL为准

1package com.java.refund;

3import com.java.utils.WXPayUtility; // 引用微信支付工具库，参考：https://pay.weixin.qq.com/doc/v3/merchant/4014931831

4import com.java.utils.WXPayUtility.Notification;

5import java.security.PublicKey;

6import okhttp3.Headers;

7import okhttp3.Response;

8import com.google.gson.annotations.SerializedName;

10public class RefundNotifyDemo {

11 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/v3/merchant/4013070756

12 // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考

13 // https://pay.weixin.qq.com/doc/v3/merchant/4013070756

14 private static String mchid = "19xxxxxxxx";

15 // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053

16 private static String certificateSerialNo = "1DDE55AD98Exxxxxxxxxx";

17 // 商户API证书私钥文件路径，本地文件路径

18 private static String privateKeyFilePath = "/path/to/apiclient_key.pem";

19 // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816

20 private static String wechatPayPublicKeyId = "PUB_KEY_ID_xxxxxxxxxxxxx";

21 // 微信支付公钥文件路径，本地文件路径

22 private static String wechatPayPublicKeyFilePath = "/path/to/wxp_pub.pem";

23 // 商户APIv3密钥，如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053267

24 private static String apiv3Key = "your apiv3 key";

26 public static class RefundAmount {

27 @SerializedName("total")

28 public Long total;

30 @SerializedName("refund")

31 public Long refund;

33 @SerializedName("payer_total")

34 public Long payerTotal;

36 @SerializedName("payer_refund")

37 public Long payerRefund;

38 }

40 public static class Refund {

41 @SerializedName("mchid")

42 public String mchid;

44 @SerializedName("out_trade_no")

45 public String outTradeNo;

47 @SerializedName("transaction_id")

48 public String transactionId;

50 @SerializedName("out_refund_no")

51 public String outRefundNo;

53 @SerializedName("refund_id")

54 public String refundId;

56 @SerializedName("refund_status")

57 public String refundStatus;

59 @SerializedName("success_time")

60 public String successTime;

62 @SerializedName("user_received_account")

63 public String userReceivedAccount;

65 @SerializedName("amount")

66 public RefundAmount amount;

67 }

69 public void refundNotify(Response httpResponse) {

70 String refundNotifyStr = WXPayUtility.extractBody(httpResponse); // 微信支付退款通知的原始字符串

71 Headers headers = httpResponse.headers(); // 微信支付退款通知的Headers

72 PublicKey wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);

74 Notification notification = WXPayUtility.parseNotification(

75 apiv3Key,

76 wechatPayPublicKeyId, wechatPayPublicKey, headers,

77 refundNotifyStr);

79 // 检查这个ID是否已经处理过了，ID是微信支付系统生成的唯一ID，每个ID只需要处理一次

80 // CheckIfIdProcessed(notification.getId());

82 // 解析退款单

83 Refund refund = WXPayUtility.fromJson(notification.getResource().getCiphertext(), Refund.class);

85 // 处理退款事件

86 switch (notification.getEventType()) {

87 case "REFUND.SUCCESS":

88 // 退款成功，理论上退款单的状态是成功态，这里多做一次校验

89 if (refund.refundStatus.equals("SUCCESS")) {

90 // 退款成功，处理退款成功逻辑

91 // UpdateRefund2Succ();

92 } else {

93 // 退款单状态非法，报错返回

94 throw new IllegalArgumentException("退款单状态非法");

95 }

96 break;

97 case "REFUND.ABNORMAL":

98 // 退款异常，理论上退款单的状态应该是异常态，这里多做一次校验

99 if (refund.refundStatus.equals("ABNORMAL")) {

100 // 退款异常，处理退款异常逻辑

101 // 可以和查单发现退款单异常处理逻辑一样，可以用两种处理方式：

102 // 1. 商户登录商户平台进入交易中心发起异常退款，把钱退到用户指定的银行卡或者商户的银行

103 // 2. 请求异常退款API

104 // UpdateRefund2Abnormal();

105 } else {

106 // 退款单状态非法，报错返回

107 throw new IllegalArgumentException("退款单状态非法");

108 }

109 break;

110 case "REFUND.CLOSED":

111 // 退款关闭，理论上退款单的状态应该是关闭态，这里多做一次校验

112 if (refund.refundStatus.equals("CLOSED")) {

113 // 退款关闭，处理退款关闭逻辑

114 // 可以和查单发现退款单关闭处理逻辑一样（如果还需要退款，需要换单之后重新发起退款）

115 // UpdateRefund2Closed();

116 } else {

117 // 退款单状态非法，报错返回

118 throw new IllegalArgumentException("退款单状态非法");

119 }

120 break;

121 default:

122 // 非法事件类型，报错返回

123 throw new IllegalArgumentException("退款事件非法");

124 }

125

126 }

127

128}

129

业务示例代码

最新发布