简介这份资源面向使用Java开发微信小程序支付的开发者聚焦微信支付V3版本的退款功能实现适合已具备一定后端基础、需要快速落地退款流程的中高级开发者参考。压缩包共4个文件以3个txt与1个properties配置为主分别承载V3支付Bean、Controller示例代码、商户参数配置及pom依赖说明整体约6KB轻量便于直接嵌入现有工程。内容围绕V3接口的签名、退款请求封装、回调通知验签与错误重试等关键环节展开可帮助读者理清从获取Access Token到处理退款结果的完整链路并对照示例快速搭建可调试的退款模块。目前已有4693人学习下载适合作为小程序退款功能开发时的速查与排错参考。1. 小程序退款总翻车先看清 V3 这套签名与证书的门道做过小程序支付的兄弟大概率都有同感收款接口跑通只是热身退款才是真正让人掉头发的地方。wxpayV3.rar这个包给的不是一份泛泛的文档而是一套能直接塞进 Spring Boot 工程的 Java 落地件——WechatPayV3Bean.txt管配置装配WechatPayV3Controller.txt管退款与回调入口wechat_pay_v3.properties管商户参数pom依赖.txt把该引的坐标列清楚。它瞄准的场景很具体小程序下单收款之后用户申请退款后端要按微信支付 V3 的规矩把请求签出去、把回调验回来、把状态落库。很多人第一次接 V3 会本能地去找access_token这是从 V2 带过来的肌肉记忆。V3 的鉴权模型换了请求头里带Authorization: WECHATPAY2-SHA256-RSA2048用商户私钥对「方法URL时间戳随机串请求体」拼出的串做 SHA256withRSA 签名平台证书则用来验微信回给你的内容。这套机制决定了你本地必须备好三样东西商户 API 私钥、商户证书序列号、平台证书或平台公钥。少一样签名就过不去报出来的还是那种让人一脸懵的 401。这份资源适合两类人一类是刚接手小程序退款、被 V3 签名卡住的 Java 后端另一类是手里有老 V2 代码、想平滑迁到 V3 的维护者。它不教你小程序前端怎么画退款按钮也不替你做对账它解决的是「后端怎么把一笔退款正确地发出去、收回来、记下来」。下面按配置、签名、退款、回调、排坑、进阶的顺序拆开讲参数和坑都落到能抄的程度。2. 把 wxpayV3 拆开配置装配与依赖坐标怎么落2.1 四个文件各自的职责边界拿到压缩包先别急着往项目里拖先认清每个文件是干嘛的不然改起来会互相打架。pom依赖.txt是坐标清单V3 官方推荐用wechatpay-java这个 SDK它把签名、验签、证书下载都封好了比手搓 HttpClient 稳得多。wechat_pay_v3.properties是纯参数文件商户号、AppID、证书序列号、私钥路径、APIv3 密钥、回调地址都在这。WechatPayV3Bean.txt是把这些参数读进来、装配成 SDK 需要的配置对象和RSAAutoCertificateConfig。WechatPayV3Controller.txt是业务入口退款申请和退款回调两个接口都在里面。常见做法是properties 只放环境相关的值Bean 里做一次性的初始化Controller 只关心业务参数和状态流转。这样换环境测试/生产只动 properties不动代码。要注意的是 APIv3 密钥和商户私钥是两码事——APIv3 密钥用来解密回调里的敏感字段比如退款通知里的加密串商户私钥用来签名请求别把两者搞混这是新手最容易犯的错。2.2 依赖坐标与配置项落地先把依赖引进来。pom依赖.txt里核心就是官方 SDK版本按你项目实际锁定的来别盲目追最新。!-- 微信支付 V3 官方 Java SDK -- dependency groupIdcom.github.wechatpay-apiv3/groupId artifactIdwechatpay-java/artifactId version0.2.12/version /dependency !-- 如果不用 SDK 自带的 HTTP 客户端可保留 okhttp -- dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency坐标说明wechatpay-java负责签名、验签、平台证书自动更新是 V3 的核心okhttp是它底层用的 HTTP 客户端一般随 SDK 传递进来显式声明是为了锁版本避免和项目里其他组件冲突。如果你的工程已经有 HttpClient 封装也别硬塞两套统一走 SDK 的HttpClientBuilder更省心。配置项落到 properties字段名按你项目习惯来关键是值别填错# 商户号10 位数字 wxpay.mch-id1900000001 # 小程序 AppID wxpay.app-idwx1234567890abcdef # 商户证书序列号在商户平台 API 安全里能看到 wxpay.mch-serial-no4A3B2C1D... # 商户 API 私钥文件路径apiclient_key.pem wxpay.private-key-path/opt/cert/apiclient_key.pem # APIv3 密钥32 位用于解密回调 wxpay.api-v3-keyyour32lengthapiv3keyhere000000 # 退款结果回调地址必须公网可达且是 https wxpay.refund-notify-urlhttps://your.domain/wxpay/refund/notify参数说明mch-serial-no是证书序列号不是商户号两个都是数字但含义完全不同填反了签名直接失败private-key-path指向的是apiclient_key.pem不是apiclient_cert.pem后者是证书本身api-v3-key必须正好 32 位短一位解密回调就抛异常refund-notify-url微信要求 https本地调试得靠内网穿透工具映射出去否则回调永远收不到。2.3 Bean 装配一次初始化全局复用WechatPayV3Bean.txt的思路是把配置读进来构建一个单例的RefundService或JsapiService。SDK 的RSAAutoCertificateConfig会自动下载并轮换平台证书省去手动维护的麻烦。Configuration public class WechatPayV3Bean { Value(${wxpay.mch-id}) private String mchId; Value(${wxpay.mch-serial-no}) private String mchSerialNo; Value(${wxpay.private-key-path}) private String privateKeyPath; Value(${wxpay.api-v3-key}) private String apiV3Key; // 全局单例避免每次请求都重新加载私钥 Bean public RSAAutoCertificateConfig rsaAutoCertificateConfig() throws IOException { return new RSAAutoCertificateConfig.Builder() .merchantId(mchId) .privateKey(Files.readString(Paths.get(privateKeyPath))) .merchantSerialNumber(mchSerialNo) .apiV3Key(apiV3Key) .build(); } Bean public RefundService refundService(RSAAutoCertificateConfig config) { return new RefundService.Builder().config(config).build(); } }逻辑说明RSAAutoCertificateConfig在启动时用商户私钥完成一次身份校验之后自动拉取平台证书并定时更新验签时就不用你手动指定平台证书了。RefundService是 SDK 提供的退款专用服务类封装了申请退款接口。参数上privateKey传的是私钥内容字符串不是路径所以这里用Files.readString读出来apiV3Key用于解密回调务必和商户平台设置的一致。把这两个 Bean 做成单例很关键私钥解析有开销每次请求都 new 一个配置对象在高并发下会拖慢响应。3. 退款请求怎么发签名、参数与状态判断3.1 V3 签名到底签了什么V3 的签名串是五行拼出来的HTTP 方法、URL带 query 的路径部分、时间戳、随机串、请求体。用商户私钥对这串做 SHA256withRSA再 Base64塞进Authorization头。SDK 已经把这步封好了你调refundService.create()时它自动签。但理解这串的意义在于排错如果报 401 签名错误八成是 URL 带了域名、或者请求体被框架改过比如序列化多加了空格导致签名串和实际发出去的不一致。常见坑是请求体被 Jackson 二次序列化。SDK 内部用 Gson 序列化如果你在 Controller 里先把对象转成 String 再传进去字段顺序或空格一变签名就对不上。正确做法是把业务对象直接交给 SDK让它自己序列化。3.2 发起退款的完整调用WechatPayV3Controller.txt里的退款入口核心是组装CreateRequest。下面这段是可直接抄的骨架RestController RequestMapping(/wxpay) public class WechatPayV3Controller { Autowired private RefundService refundService; PostMapping(/refund) public ResponseEntityString refund(RequestBody RefundDTO dto) throws Exception { // 商户退款单号必须唯一重复请求微信会幂等返回 String outRefundNo RF System.currentTimeMillis(); CreateRequest req new CreateRequest.Builder() // 原支付订单号二选一transaction_id 或 out_trade_no .outTradeNo(dto.getOutTradeNo()) // 退款单号自己生成用于对账 .outRefundNo(outRefundNo) // 退款金额单位分不能大于原订单金额 .amount(new AmountReq(dto.getRefundFen(), dto.getTotalFen(), CNY)) // 退款原因会展示给用户 .reason(dto.getReason()) // 回调地址不传则用配置里的默认值 .notifyUrl(https://your.domain/wxpay/refund/notify) .build(); Refund refund refundService.create(req); // refund.getStatus() 常见值SUCCESS / PROCESSING / ABNORMAL / CLOSED return ResponseEntity.ok(refund.getStatus()); } }逻辑说明outTradeNo和transaction_id二选一前者是你下单时的商户订单号后者是微信侧订单号用哪个取决于你库里存了哪个。outRefundNo必须全局唯一重复提交同一个退款单号微信会幂等处理不会重复退钱这也是重试机制的基础。AmountReq三个参数分别是退款金额、原订单总额、币种单位都是分退款金额不能超过原订单总额否则报参数错误。notifyUrl建议显式传别依赖默认配置多环境时容易串。3.3 退款状态怎么读refund.getStatus()返回的是字符串别用result_code那套 V2 的字段去判断。V3 退款状态主要有几个值含义差别很大状态值含义处理建议SUCCESS退款成功更新本地订单为已退款PROCESSING退款处理中等待回调不要重复发起ABNORMAL退款异常需人工介入查退款单详情CLOSED退款关闭通常因原订单问题核对订单状态注意PROCESSING不是失败很多新手看到不是 SUCCESS 就重试结果触发风控。正确姿势是收到PROCESSING就等回调回调里再确认最终状态。退款到账时间取决于用户支付方式零钱通常较快银行卡可能 T1 甚至更久别拿「没立刻到账」当 bug 查。4. 回调验签与状态落库别让通知变成黑匣子4.1 回调报文的结构与解密微信退款完成后会 POST 一个 JSON 到你配置的notifyUrl报文分两部分外层是id、create_time、event_type、resourceresource里又有algorithm、ciphertext、nonce、associated_data。真正的退款结果在ciphertext里用 APIv3 密钥做 AES-256-GCM 解密才能看到。SDK 提供了NotificationParser帮你一步到位。PostMapping(/refund/notify) public MapString, String refundNotify(RequestBody String body, RequestHeader(Wechatpay-Signature) String signature, RequestHeader(Wechatpay-Timestamp) String timestamp, RequestHeader(Wechatpay-Nonce) String nonce, RequestHeader(Wechatpay-Serial) String serial) { MapString, String resp new HashMap(); try { // 构造验签参数SDK 会用平台证书验签并解密 RequestParam param new RequestParam.Builder() .serialNumber(serial) .nonce(nonce) .signature(signature) .timestamp(timestamp) .body(body) .build(); // RefundNotification 是解密后的退款结果对象 RefundNotification notification notificationParser.parse(param, RefundNotification.class); // 幂等先查本地是否已处理过该退款单 if (!refundRecordService.isProcessed(notification.getOutRefundNo())) { refundRecordService.updateStatus( notification.getOutRefundNo(), notification.getRefundStatus()); } resp.put(code, SUCCESS); resp.put(message, 成功); } catch (Exception e) { // 验签失败或解密失败返回失败让微信重试 resp.put(code, FAIL); resp.put(message, e.getMessage()); } return resp; }逻辑说明四个请求头缺一不可Wechatpay-Serial告诉 SDK 用哪张平台证书验签Wechatpay-Signature是签名值。notificationParser.parse内部先验签再解密任何一步失败都会抛异常此时必须返回FAIL微信会按策略重试。返回SUCCESS表示你已成功接收微信不再重试。参数上body必须是原始报文别在框架里做任何预处理否则验签必挂。4.2 幂等与落库回调可能重复推送微信不保证只发一次。所以处理逻辑必须先查outRefundNo是否已处理已处理直接返回成功。落库时把退款单号、原订单号、退款金额、状态、回调时间都记下来方便对账。常见做法是给out_refund_no加唯一索引靠数据库兜底防重。提示回调接口不要做耗时操作比如发短信、调外部系统。微信对响应时间有要求超时会判失败并重试重试风暴能把你的库打崩。耗时逻辑丢到消息队列异步处理。5. 退款排查五条血泪踩坑记录5.1 签名报 401但参数看着都对现象请求发出去返回 401提示签名错误可商户号、序列号、私钥路径都核对过没问题。原因多半是请求体被二次序列化或者 URL 里带了域名。V3 签名串里的 URL 只取路径部分/v3/refund/domestic/refunds不含https://api.mch.weixin.qq.com。解决用 SDK 直接传对象别自己转 String确认签名用的 URL 是纯路径。如果还不行把签名串打日志逐行比对通常能一眼看出多出来的空格。5.2 回调收不到日志一片空白现象退款明明成功了本地回调接口没任何日志。原因notifyUrl不是 https或者公网不可达或者被网关拦了。解决确认地址是 https 且外网能访问本地调试用内网穿透映射检查 Nginx 或安全组有没有放行 POST微信回调只认 200 且响应体符合格式返回其他状态码会被判失败。5.3 解密回调抛 AEADBadTagException现象验签过了解密ciphertext时报 AEAD 标签错误。原因APIv3 密钥填错或者密钥长度不是 32 位。解决去商户平台重新核对 APIv3 密钥注意它和 API 密钥V2 用的那个不是一回事确认配置文件里没有多余空格长度严格 32 位。5.4 重复退款用户收到两笔钱现象用户反馈收到两次退款。原因没做幂等网络超时后代码重试生成了新的outRefundNo。解决outRefundNo用业务唯一键比如原订单号退款序号生成别用时间戳重试时复用同一个退款单号微信会幂等返回数据库对out_refund_no加唯一约束。5.5 金额对不上退多了或退少了现象退款金额和预期差 100 倍。原因单位搞错V3 金额单位是分不是元。解决所有金额字段统一用分存储和传输前端传元的话在入口处乘 100 并转 int别用 double 做金额运算浮点误差会让你对账对到怀疑人生。6. 进阶把退款做成可重试、可对账的闭环退款跑通只是及格线生产环境还得解决两件事重试和对账。重试不能无脑循环得区分错误类型。签名错误、参数错误这类是「重试也没用」的直接告警网络超时、SYSTEM_ERROR这类才值得重试且必须复用同一个outRefundNo。我一般会建一张退款任务表记录每次请求的状态和重试次数用定时任务扫描PROCESSING超过一定时间的单子去查退款详情接口兜底。// 查询退款单详情用于回调丢失时兜底 GetMapping(/refund/query/{outRefundNo}) public Refund queryRefund(PathVariable String outRefundNo) throws Exception { QueryByOutRefundNoRequest req new QueryByOutRefundNoRequest.Builder() .outRefundNo(outRefundNo) .build(); // 返回对象里的 status 才是权威状态 return refundService.queryByOutRefundNo(req); }对账则是每天拉一次微信的账单和本地退款记录逐笔比对。V3 有专门的账单下载接口返回的是加密的 CSV用 APIv3 密钥解密后解析。差异单子要能定位到具体是哪笔、差多少、什么状态。这套闭环建起来之后退款出问题基本都能在当天发现而不是等用户投诉。还有个容易被忽略的点平台证书会轮换。SDK 的RSAAutoCertificateConfig会自动更新但如果你用的是手动指定平台证书的方式证书过期后验签会突然全挂。所以能用自动更新就别手动。另外商户私钥文件权限要收紧别提交到代码仓库用配置中心或挂载卷注入。从那以后我每次接微信支付 V3都强制先把签名串打日志、把回调幂等做掉、把金额单位统一成分为单位这三步走完再写业务。希望帮到你。本文还有配套的精品资源点击获取