业务示例代码
更新时间：2025.08.081. 目标
通过本教程的学习，你应该可以：
2. 业务处理流程
2.1. 申请退款
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账户上。
申请退款需要3类信息：
商户信息
子商户号
原支付订单信息
微信支付订单号或者商户订单号
原订单金额
退款信息
商户退款单号：标识该服务商商户下的退款单，同一个服务商商户下不同商户退款单号表示不同的退款单
退款原因
退款金额
退款出资信息
退款回调URL
退款商品信息
1package com.java.partner.refund; 2 3import com.java.demo.Create; // 使用合作伙伴申请退款接口https://pay.weixin.qq.com/doc/v3/partner/4013080625 4import static com.java.demo.Create.*; // 使用合作伙伴申请退款接口https://pay.weixin.qq.com/doc/v3/partner/4013080625 5import com.java.utils.WXPayUtility; // 引用微信支付工具库，参考：https://pay.weixin.qq.com/doc/v3/partner/4014985777 6import java.util.ArrayList; 7 8public class CreateRefundDemo { 9 10 public static void main(String[] args) { 11 Create ceateRefund = new Create( 12 "19xxxxxxxx", // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 13 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 14 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径，本地文件路径 15 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 16 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径，本地文件路径 17 ); 18 19 CreateRequest createRefundRequest = new CreateRequest(); 20 // 商户信息 21 createRefundRequest.subMchid = "1900000109"; 22 23 // 原支付订单信息 24 createRefundRequest.transactionId = "4200000020202506035017900000"; 25 createRefundRequest.amount = new AmountReq(); 26 createRefundRequest.amount.total = 800L; 27 28 // 退款信息 29 // 商户退款单号生成方式商户视实际情况生成，需要保证服务商商户下全局唯一 30 createRefundRequest.outRefundNo = "4200000020202506035017900000_1"; 31 createRefundRequest.reason = "成团退差价"; 32 createRefundRequest.amount.refund = 200L; 33 34 // 退款成功，退款关闭，退款异常时需要微信支付通知商户商户，可以加上回调URL，退款到这几个状态时会调用这个URL通知商户 35 createRefundRequest.notifyUrl = "https://weixin.qq.com"; 36 37 // 退款资金来源 38 // 1. 对于出行预付押金退款 39 // - 不填写表示已结退款，从出行商户基本户出资退款 40 // - 填写UNSETTLED，表示未结退款，从押金账户出资退款 41 // 2. 42 // 对于子商户为老资金流的商户（老资金流也叫旧资金流，旧资金流如何区分见：https://kf.qq.com/faq/161223N7fi2E161223EvY3Ir.html） 43 // - 不填写表示未结退款，从未结账户出资退款 44 // - 填写AVAILABLE，表示从可用余额出资退款 45 // createRefundRequest.fundsAccount = ReqFundsAccount.AVAILABLE; 46 47 // 退款商品信息 48 createRefundRequest.goodsDetail = new ArrayList<>(); 49 { 50 GoodsDetail goodDetail = new GoodsDetail(); 51 goodDetail.merchantGoodsId = "1217752501201407033233368018"; 52 goodDetail.wechatpayGoodsId = "1001"; 53 goodDetail.goodsName = "iPhone6s 16G"; 54 goodDetail.unitPrice = 528800L; 55 goodDetail.refundAmount = 528800L; 56 goodDetail.refundQuantity = 1L; 57 createRefundRequest.goodsDetail.add(goodDetail); 58 } 59 ; 60 61 Refund refund; 62 try { 63 refund = ceateRefund.run(createRefundRequest); 64 } catch (WXPayUtility.ApiException e) { 65 // 申请退款处理异常处理逻辑 66 if (e.getErrorCode() == "SYSTEM_ERROR") { 67 // 错误：系统错误 68 // 解决方式：稍后原单重试 69 // 描述：微信支付系统失败，一定要原单重试，系统失败直接立即重试大概率还会是系统失败，建议等1分钟后再重试 70 } else if (e.getErrorCode() == "FREQUENCY_LIMITED") { 71 // 错误：限频报错 72 // 解决方式：稍后原单重试 73 // 描述： 退款接口频率限制，一定要原单重试，直接立即重试大概率还会是系统失败，建议等1分钟后再重试 74 } else if (e.getErrorCode() == "MCH_NOT_EXISTS") { 75 // 错误：子商户不存在 76 // 解决方式：检查输入的子商户号是否填写正确，修改正确之后原单重试 77 // 描述：输入子商户账户不存在，需要填写存在的账户之后重试 78 } else if (e.getErrorCode() == "USER_ACCOUNT_ABNORMAL") { 79 // 错误：用户账户异常 80 // 解决方式：退款受理失败，商户可以自行处理退款，也可以登录商户平台进入交易中心发起异常退款 81 // 描述：用户注销或者被管控了，这笔订单已经不能发起退款，这个错误就不需要重试了 82 } else if (e.getErrorCode() == "NOT_ENOUGH") { 83 // 错误：账户余额不足 84 // 解决方式：商户充值之后原单重试 85 // 描述：商户账户余额不足，导致退款失败，商户充值之后一定要原单重试 86 } else if (e.getErrorCode() == "NO_AUTH") { 87 // 错误：无退款权限 88 // 解决方式： 89 // 1. 检查商户是否是被处罚：登录商户平台进入账户中心-违约记录查询是否违约记录，如果有按照上面的指引解决违约记录之后原单重试 90 // 2. 91 // 检查子商户是否已授权服务商商户API退款权限：登录商户平台进入产品中心-特约商户授权产品，在特约商户列表中看看该子商户是否存在并且授权状态为“已授权”， 92 // 如果不存在或者授权状态不是“已授权”就需要发起授权邀请，等子商户审批之后重新查询一遍，授权状态为“已授权”之后再原单重试 93 // 描述：服务商商户被处罚或者服务商商户和子商户没有父子受理关系 94 } else if (e.getErrorCode() == "SIGN_ERROR") { 95 // 错误：签名错误 96 // 解决方式：检查服务商商户证书序列号，证书私钥文件，公钥ID，公钥文件，同时确认下签名过程是不是按照微信支付的签名方式 97 // 描述：签名报错，需要确认签名材料和签名流程是否正确 98 } else if (e.getErrorCode() == "PARAM_ERROR") { 99 // 错误：参数错误 100 // 解决方式：按照报错返回的message，重新输入请求参数 101 // 描述：参数的类型，长度，或者必填选项没有填写等 102 } else if (e.getErrorCode() == "INVALID_REQUEST") { 103 // 错误：请求非法，请求参数正确，但是不符合退款业务规则 104 // 解决方式：根据具体message查看具体哪里不符合业务规则，如果可以修改参数达到符合业务规则的修改请求符合业务规则之后再原单重试 105 // 描述：不符合业务规则的场景如： 106 // - 交易时间超过365天，不允许发起退款 107 // - 一笔订单退款次数已经超过50次了，这笔订单不允许发起新的退款 108 // - 申请退款的金额超过了这笔订单剩余可退金额，不允许申请退款 109 } else { 110 // 其他类型错误：稍等一会后原单重试 111 } 112 113 } 114 } 115}
2.2. 查询退款
上面申请退款成功之后，说明微信支付成功受理了这笔退款，并不是已经退款到账，商户可以通过查询退款接口查询退款结果
退款单的状态机：
1package com.java.partner.refund; 2 3import com.java.demo.Create; // 使用合作伙伴申请退款接口https://pay.weixin.qq.com/doc/v3/partner/4013080625 4import static com.java.demo.Create.*; // 使用合作伙伴申请退款接口https://pay.weixin.qq.com/doc/v3/partner/4013080625 5import com.java.demo.QueryByOutRefundNo; // 使用合作伙伴查询单笔退款（按商户退款单号）接口，见：https://pay.weixin.qq.com/doc/v3/partner/4013080626 6import static com.java.demo.QueryByOutRefundNo.*; // 使用合作伙伴查询单笔退款（按商户退款单号）接口，见：https://pay.weixin.qq.com/doc/v3/partner/4013080626 7import com.java.demo.CreateAbnormalRefund; // 使用合作伙伴发起异常退款接口，见：https://pay.weixin.qq.com/doc/v3/partner/4013080627 8import static com.java.demo.CreateAbnormalRefund.*; // 使用合作伙伴发起异常退款接口，见：https://pay.weixin.qq.com/doc/v3/partner/4013080627 9import com.java.utils.WXPayUtility; // 引用微信支付工具库，参考：https://pay.weixin.qq.com/doc/v3/partner/4014985777 10import java.util.ArrayList; 11 12public class QueryRefundDemo { 13 14 public static void main(String[] args) { 15 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/v3/partner/4013080340 16 QueryByOutRefundNo client = new QueryByOutRefundNo( 17 "19xxxxxxxx", // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 18 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 19 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径，本地文件路径 20 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 21 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径，本地文件路径 22 ); 23 24 QueryByOutRefundNoRequest request = new QueryByOutRefundNoRequest(); 25 request.outRefundNo = "4200000020202506035017900000_1"; 26 request.subMchid = "1900000109"; 27 try { 28 QueryByOutRefundNo.Refund refund = client.run(request); 29 switch (refund.status) { 30 case SUCCESS: 31 // 终态：退款成功（退款到账） 32 // 更新商户自己的业务单据状态为成功 33 // UpdateRefund2Succ(); 34 break; 35 case CLOSED: 36 // 终态：退款关闭 37 // 更新商户自己的业务单据状态为关闭 38 // UpdateRefund2Closed(); 39 // 如果还需要退款，需要换单（换outRefundNo）重新申请退款 40 Create createRefund = new Create( 41 "19xxxxxxxx", // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 42 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 43 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径，本地文件路径 44 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 45 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径，本地文件路径 46 ); 47 48 CreateRequest createRefundRequest = new CreateRequest(); 49 // 其他参数和之前申请退款参数一样，只改商户退款单号 50 createRefundRequest.outRefundNo = "4200000020202506035017900000_2"; 51 createRefund.run(createRefundRequest); 52 53 break; 54 case PROCESSING: 55 // 非终态：退款处理中 - 还未到账，需要隔一段时间再来查询 56 break; 57 case ABNORMAL: 58 // 非终态：退款异常 - 用户异常、用户被管控等原因不能原路退 59 // 可以用两种处理方式： 60 // 1. 商户登录商户平台进入交易中心发起异常退款，把钱退到用户指定的银行卡或者商户的银行 61 // 2. 请求异常退款API 62 // TODO: 请准备商户开发必要参数，参考：https://pay.weixin.qq.com/doc/v3/partner/4013080340 63 CreateAbnormalRefund createAbnormalRefund = new CreateAbnormalRefund( 64 "19xxxxxxxx", // 商户号，是由微信支付系统生成并分配给每个商户的唯一标识符，商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 65 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 66 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径，本地文件路径 67 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID，如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 68 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径，本地文件路径 69 ); 70 CreateAbnormalRefundRequest abnormalRefundRequest = new CreateAbnormalRefundRequest(); 71 abnormalRefundRequest.refundId = refund.refundId; 72 abnormalRefundRequest.subMchid = "1900000109"; 73 abnormalRefundRequest.outRefundNo = "4200000020202506035017900000_1"; 74 abnormalRefundRequest.type = AbnormalReceiveType.USER_BANK_CARD; 75 abnormalRefundRequest.bankType = "ICBC_DEBIT"; 76 abnormalRefundRequest.bankAccount = createAbnormalRefund.encrypt("请填 用户的银行卡号"); 77 abnormalRefundRequest.realName = createAbnormalRefund.encrypt("请填 收款用户姓名"); 78 CreateAbnormalRefund.Refund abnormalRefund = createAbnormalRefund.run(abnormalRefundRequest); 79 // 发起异常退款成功之后，退款单会进入退款中，还是需要通过查单接口查询退款单的状态 80 break; 81 default: 82 // 非法状态 83 throw new IllegalArgumentException("微信支付退款单状态非法"); 84 } 85 } catch (WXPayUtility.ApiException e) { 86 // 查询退款处理异常处理逻辑 87 if (e.getErrorCode() == "RESOURCE_NOT_EXISTS") { 88 // 错误：退款单不存在 89 // 解决方式：原参数申请退款 90 // 描述：退款受理没成功，原参数发起退款申请即可 91 } else if (e.getErrorCode() == "SYSTEM_ERROR") { 92 // 错我：系统错误 93 // 解决方式：稍后原单重试 94 // 描述：微信支付系统失败，直接立即重试大概率还会是系统失败，建议等1分钟后再重试 95 } else if (e.getErrorCode() == "FREQUENCY_LIMITED") { 96 // 错误：限频报错 97 // 处理逻辑：稍后原单重试 98 // 描述： 退款接口频率限制，直接立即重试大概率还会是系统失败，建议等1分钟后再重试 99 } else if (e.getErrorCode() == "MCH_NOT_EXISTS") { 100 // 错误：子商户不存在 101 // 处理逻辑：检查输入的子商户号是否填写正确，修改正确之后原单重试 102 // 描述：输入子商户账户不存在，需要填写存在的账户之后重试 103 } else if (e.getErrorCode() == "NO_AUTH") { 104 // 错误：无退款权限 105 // 处理逻辑：检查服务商商户是否退款权限，服务商商户和子商户是否有父子受理关系，需要开通服务商商户的退款权限和添加子商户的父子受理权限才能发起退款 106 // 描述：服务商商户无退款权限或者服务商商户和子商户没有父子受理关系 107 } else if (e.getErrorCode() == "SIGN_ERROR") { 108 // 错误：签名错误 109 // 处理逻辑：检查服务商商户证书序列号，证书私钥文件，公钥ID，公钥文件，同时确认下签名过程是不是按照微信支付的签名方式 110 // 描述：签名报错，需要确认签名材料和签名流程是否正确 111 } else if (e.getErrorCode() == "PARAM_ERROR") { 112 // 错误：参数错误 113 // 处理逻辑：按照报错返回的message，重新输入请求参数 114 // 描述：参数的类型，长度，或者必填选项没有填写等 115 } else { 116 // 其他类型错误：稍等一会后原单重试 117 } 118 } 119 } 120}
2.3. 退款结果通知
如果商户申请退款时设置了notifyUrl，或者在商户平台-交易中心-交易管理-退款管理-退款配置 中设置了通知URL，那么退款状态变更为SUCCESS、CLOSED或者ABNORMAL后会通过HTTP POST方法回调到这个URL上
如果退款申请是设置了notifyUrl，同时退款配置中也设置了通知URL，已退款申请的URL为准
1RefundNotifyResult refundNotifyResult; 2try { 3 // 1. 解析微信支付回调包体，refundNotifyRawResult为商户接收到微信回调的原始信息 4 refundNotifyResult = refund.parseRefundNotify(refundNotifyRawResult); 5 // 2. 解析完回调包体之后，可以先返回给微信支付200或者204，表示回调成功 6 // 商户再异步处理包体逻辑，这样子能保证微信回调不会超时，微信支付超时多次之后不会再回调 7 // 处理方式如先吧refundNotifyResult抛到消息队列，然后返回微信支付成功，最后消息队列消费者可以异步处理退款回调信息 8 // 9 send2MQ(refundNotifyResult); 10} catch (Exception e) { 11 // 处理回调异常 12} 13 14 15// 消费者处理逻辑 16public static bool handleRefundNotify(RefundNotifyResult refundNotifyResult) { 17 switch (refundNotifyResult.status) { 18 // 这里处理状态逻辑和上面的查询退款单的逻辑保持一致即可 19 } 20}
文档是否有帮助
