微信支付V3退款签名与回调验签实践详解

简介：Java微信支付V3（小程序）退款实现资源包，面向需要在小程序端接入微信支付退款能力的后端开发者，帮助其解决退款流程不清晰、参数易出错等实际问题。内容聚焦微信支付V3版本退款API的完整调用流程，覆盖获取Access Token、发起退款请求、处理退款结果、回调通知验签、错误处理与重试机制、小程序端交互以及日志记录等关键环节，并结合样例代码展示具体实现方式，为开发者梳理清前后端分工与异常场景。资源包共4个文件，以txt源码示例和properties配置文件为主，整体仅6KB，便于快速查阅和导入工程；其中包含退款Bean与Controller示例、properties配置项以及pom依赖说明，可辅助理解请求参数的封装、API调用和项目配置，同时帮助开发者在测试环境完成调试，减少联调时因签名或回调问题产生的返工，有效缩短上手周期。已有4691人学习下载，适合熟悉Java但初次接触微信支付V3退款业务的开发者作为参考。

1. 小程序退款为什么绕不开微信支付 V3 的签名

微信支付 V3 的小程序退款，表面看只是 POST 一个退款接口，实际上 90% 的报错都出在签名和证书上。很多 Java 后端习惯用 V2 的思路去找 Access Token，但 V3 没有 access_token，取而代之的是商户私钥对请求体做 RSA 签名的 Authorization 头。解压 wxpayV3.rar 后，wxpayV3 目录下的 WechatPayV3Bean.txt、WechatPayV3Controller.txt、wechat_pay_v3.properties 和 pom依赖.txt 正好对应参数模型、控制层、配置和依赖四块。这篇博客用这套工程结构，把退款请求、回调验签、幂等落库和排查技巧串起来，适合被 401 和 SIGN_ERROR 卡住、想搞懂 V3 签名机制的 Java 开发者。

2. 退款前先搭好 V3 证书配置与签名 HTTP 客户端

V3 的每个接口调用都要求商户系统用商户私钥签名，微信服务端再用商户证书公钥验签。所以第一步不是写退款业务，而是把私钥、证书序列号、APIv3 密钥和发送请求的 HTTP 客户端准备对。这个基础不打好，后续所有退款请求都会在授权上失败。

2.1 wechat_pay_v3.properties 里的配置项

wxpayV3 工程中的 wechat_pay_v3.properties 是唯一不需要改 Java 代码就能切换环境的文件。下面是一份贴近实际使用的配置：

wechat.pay.mchid=1600000000 wechat.pay.appid=wx1234567890abcdef wechat.pay.mch-serial-no=1234567890ABCDEF wechat.pay.private-key-path=classpath:cert/apiclient_key.pem wechat.pay.apiv3-key=0123456789abcdef0123456789abcdef wechat.pay.refund-notify-url=https://api.example.com/wxpay/refund/notify wechat.pay.api-base=https://api.mch.weixin.qq.com

mchid 是商户号，appid 对应小程序的 AppID。mch-serial-no 是商户证书的序列号，不是证书文件的文件名，也不等于证书内容的签名摘要。可以在本机执行openssl x509 -in apiclient_cert.pem -noout -serial查看，输出里的serial=...后面那段值就是序列号。

private-key-path 指向的是 apiclient_key.pem，也就是申请支付证书时下载到的私钥文件，通常放在 src/main/resources/cert/ 下。apiv3-key 是你在商户平台设置的 32 位 APIv3 密钥，它不是证书私钥，而是用于回调内容解密的对称密钥。注意不要把这两者搞混。

我之前帮同事排查过一个案例：他把 apiclient_cert.pem 的内容当成私钥加载，结果一调用就报SIGN_ERROR。因为证书文件是公钥载体，签名必须用单独的私钥文件。所以配置文件里 private-key-path 永远指向 key 文件，不是 cert 文件。下面这张表整理了最容易配错的三个点：

2.2 用 OkHttp 组装带签名的 HTTP 客户端

pom依赖.txt 里会列出 okhttp 和 jackson-databind。这里不贴具体版本，使用你项目里已有的 3.14 以上版本就可以。为什么用 OkHttp？因为它的 Interceptor 能直观地看到请求头和 body，对排查签名问题很有用；Apache HttpClient 也能做，但调试体验不如 OkHttp。

发送退款请求的核心是生成 Authorization 头。V3 的规范是WECHATPAY2-SHA256-RSA2048，后面跟着 mchid、nonce_str、timestamp、serial_no、signature 五个字段。这里给出一个最小实现：

public String buildAuthHeader(String method, String path, String body) throws Exception { String nonceStr = UUID.randomUUID().toString().replace("-", ""); String timestamp = String.valueOf(System.currentTimeMillis() / 1000); // 拼接微信支付 V3 的签名原串，每一段都以换行符结尾 String message = method + "\n" + path + "\n" + timestamp + "\n" + nonceStr + "\n" + (body == null ? "" : body) + "\n"; Signature signer = Signature.getInstance("SHA256withRSA"); signer.initSign(loadPrivateKey()); signer.update(message.getBytes(StandardCharsets.UTF_8)); String signature = Base64.getEncoder().encodeToString(signer.sign()); return "WECHATPAY2-SHA256-RSA2048 " + "mchid=\"" + mchid + "\"," + "nonce_str=\"" + nonceStr + "\"," + "timestamp=\"" + timestamp + "\"," + "serial_no=\"" + mchSerialNo + "\"," + "signature=\"" + signature + "\""; }

签名串的拼接规则是固定的五段：HTTP 方法、URL 路径、时间戳、随机字符串、请求体，每一段以换行符结尾。特别要注意 path 只包含路径部分，比如/v3/refund/domestic/refunds，不包含域名和 query；使用 GET 查询时没有请求体，body 位置传空字符串。我看到很多代码在 body 上直接塞入 null，结果导致拼接出来的是"null"，签名永远对不上。

签名算法固定是SHA256withRSA，私钥加载方式如下：

private PrivateKey loadPrivateKey() throws Exception { byte[] keyBytes = Files.readAllBytes(Paths.get(privateKeyPath)); String pem = new String(keyBytes, StandardCharsets.UTF_8) .replace("-----BEGIN PRIVATE KEY-----", "") .replace("-----END PRIVATE KEY-----", "") .replaceAll("\\s", ""); byte[] decoded = Base64.getDecoder().decode(pem); PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(decoded); return KeyFactory.getInstance("RSA").generatePrivate(spec); }

这里用的是 PKCS#8 格式，微信下载的 apiclient_key.pem 通常是 PKCS#1，大多数情况下 Java 的 PKCS8EncodedKeySpec 也能解析；如果报 InvalidKeySpec，可以先确认文件头部是不是BEGIN RSA PRIVATE KEY，如果是就用 Bouncy Castle 的 PEMParser 转换一次。常见做法是直接把私钥文件转成 PKCS#8，避免不同环境下的解析差异。

2.3 预置回调解密工具

退款回调的 resource 字段是 AES-256-GCM 加密的，这一步和签名分开处理。在写退款业务前先把解密函数准备好，后面回调验签时才不用临时找代码。可以参考下面的方法：

public static String decryptResource(String associatedData, String nonce, String ciphertext) { SecretKeySpec key = new SecretKeySpec(apiV3Key.getBytes(StandardCharsets.UTF_8), "AES"); try { Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding"); GCMParameterSpec spec = new GCMParameterSpec(128, nonce.getBytes(StandardCharsets.UTF_8)); cipher.init(Cipher.DECRYPT_MODE, key, spec); cipher.updateAAD(associatedData.getBytes(StandardCharsets.UTF_8)); return new String(cipher.doFinal(Base64.getDecoder().decode(ciphertext)), StandardCharsets.UTF_8); } catch (Exception e) { throw new RuntimeException("退款回调解密失败", e); } }

GCM 参数里的 128 是 tag 长度，微信服务端加密时使用 128 位认证标签。nonce 和 associated_data 都来自回调 JSON 的 resource 字段，ciphertext 是该字段里的密文。解密时不要额外再做 URL 解码，直接用 Base64 解码即可。这个函数在后面的回调处理中会直接复用。

3. 退款 Bean 与 Controller 层：参数校验、JSON 组装与幂等落库

wxpayV3 工程里 WechatPayV3Bean.txt 不是复杂的东西，它就是退款请求的 Java 模型。真正容易出错的地方在于：你用什么顺序把字段序列化成 JSON，签名就会用哪个字符串。如果 Bean 里的字段顺序和微信文档不一致，签名照样能算出，但微信服务端按自己顺序拼接后验签失败。所以理解这个 Bean 的字段角色，比一次性写下所有 getter/setter 更重要。

3.1 WechatPayV3Bean 的字段与文档对应关系

退款申请接口的请求体只需要几个字段。常见字段整理成下面的表格：

注意金额字段的类型是 Integer，不是 BigDecimal。微信支付 V3 的所有金额单位都是“分”，0.01 元要用 1 表示。用元做单位直接调接口会得到 PARAM_ERROR，而且这种错误在日志里非常难察觉，因为返回信息只会提示金额格式不对。

另一个细节是 out_refund_no 的命名规则：建议直接关联原始订单号加随机后缀，例如REFUND_ORDER202501010001_001，这样排查问题时能一眼看出该退款属于哪个订单，同时也能保证多次调用之间的唯一性。如果使用第三方生成的 UUID，日志关联会麻烦很多。

3.2 Controller 层只做参数翻译，不写支付逻辑

WechatPayV3Controller.txt 中一般会提供一个 POST 接口给小程序后端调用。思路是小程序端拿到用户操作后只传出来几个关键参数，服务端去补齐商户号、回调地址等敏感信息。下面是一个符合工程实践的接口骨架：

@RestController @RequestMapping("/wxpay/refund") public class WechatPayV3Controller { private final RefundService refundService; public WechatPayV3Controller(RefundService refundService) { this.refundService = refundService; } @PostMapping public ApiResult refund(@RequestBody RefundApplyParam param) { // 金额校验：必须是正整数，单位是分 if (param.getRefundFee() == null || param.getRefundFee() <= 0) { return ApiResult.fail("refundFee must be positive integer in fen"); } RefundOrderDO refundOrder = refundService.applyRefund(param); return ApiResult.ok(refundOrder); } }

Controller 里不出现私钥、证书、Authorization 相关内容，只负责接收参数和调用 service。这样做的原因是签名相关代码要在多个接口间复用，散落在 Controller 里会导致后续维护时改一处漏一处。RefundApplyParam 一般是 outTradeNo、refundFee、reason 三个字段，outRefundNo 和 notifyUrl 由 Service 层生成或从配置读取。

3.3 组装退款 JSON 并发送

Service 层组装退款对象并生成签名请求。这里的关键是序列化顺序要固定，推荐直接使用 ObjectMapper 的默认字段顺序，不要在实体类上使用@JsonProperty重排，也不要手写 JSON 字符串。

String path = "/v3/refund/domestic/refunds"; RefundRequest request = new RefundRequest(); request.setOutTradeNo(param.getOutTradeNo()); request.setOutRefundNo(generateRefundNo(param.getOutTradeNo())); request.setRefundFee(param.getRefundFee()); request.setTotalFee(order.getActualPayFee()); request.setNotifyUrl(refundNotifyUrl); ObjectMapper mapper = new ObjectMapper(); String body = mapper.writeValueAsString(request); Request httpRequest = new Request.Builder() .url(apiBase + path) .post(RequestBody.create(body, MediaType.parse("application/json"))) .header("Authorization", buildAuthHeader("POST", path, body)) .header("Accept", "application/json") .build();

这里body变量被使用两次：一次构造 RequestBody，一次传入签名方法。必须确保两个地方使用的是同一个字符串，不要在签名后再对 body 做格式化或转义。如果用了日志输出去美化 JSON，那只是复制到控制台给人看的，不影响签名；但如果你把美化后的字符串回填进签名逻辑，就会报 SIGN_ERROR。

还有一点，total_fee必须是原订单实际支付金额，不能拿商品原价或应付金额去凑。微信侧会校验退款金额是否超过可退余额，一旦超过就返回REFUND_FEE_MISMATCH。

3.4 幂等落库：用 out_refund_no 做唯一键

退款场景天然会重试。网络超时后接口不确定是否已经受理，重发一次可能产生两条退款记录。所以本地数据库必须以 out_refund_no 为唯一索引，落库的 DDL 简单但关键：

CREATE TABLE t_refund_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, out_refund_no VARCHAR(64) NOT NULL, out_trade_no VARCHAR(64) NOT NULL, refund_fee INT NOT NULL, status VARCHAR(20) NOT NULL DEFAULT 'CREATED', refund_id VARCHAR(64) DEFAULT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_out_refund_no (out_refund_no) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

插入时不要用“先 select 再 insert”，高并发重试下一定会穿透。最稳妥的是直接执行 insert，捕获 DuplicateKeyException 后走查询分支，拿到已存在的退款单并返回。这样无论请求多少次，数据库里同一个 out_refund_no 只有一条记录。

状态字段 status 可以先给一个本地初始值，等微信回调后再更新为 PROCESSING、SUCCESS 这些最终状态。注意不要在发起退款请求前就置为 SUCCESS，因为微信侧还没有受理。

4. 回调验签、状态机与重试：V3 退款最容易翻车的三处

退款申请接口返回的 status 并不代表退款已经结束，真正决定结果的是异步回调。回调处理如果验签不严，可能被伪造通知；如果状态判断错误，会把 PROCESSING 当成 SUCCESS 更新数据库。这一章把回调验签、状态字符和重试策略放在一起说。

4.1 回调报文先验平台证书签名

微信退款回调的请求头带有 Wechatpay-Signature、Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Serial 四个字段。其中 Wechatpay-Serial 是微信支付平台证书的序列号，不是文件里的商户证书序列号。需要用微信侧下发的平台证书来验签，不能拿 apiclient_cert.pem 去验。

验签原始字符串的拼接规则与请求签名一致：

// 回调验签：时间戳、nonce、原始 body 组成待签名串 String message = timestamp + "\n" + nonce + "\n" + body + "\n"; Signature verifier = Signature.getInstance("SHA256withRSA"); verifier.initVerify(platformPublicKey); verifier.update(message.getBytes(StandardCharsets.UTF_8)); boolean valid = verifier.verify(Base64.getDecoder().decode(signature));

报文里的 body 是整个回调 JSON 字符串，不能经过任何格式化。验签成功后，使用 2.3 节里的 decryptResource 方法解密 resource 字段，得到退款结果对象。如果本机没有平台证书，可以从微信支付平台证书下载接口定期拉取并缓存，也可以手动下载放到 cert 目录。测试环境里最常见的问题是平台证书过期或用错证书，导致验签一直返回 false。

注意区分平台证书和商户证书：回调验签使用平台证书，请求签名使用商户私钥，二者不是同一个文件。遇到过不少把两个序列号搞反的，排查方向直接跑偏。确认序列号时，看请求头里的 Wechatpay-Serial 对应哪个证书文件，再去加载对应的公钥即可。

4.2 不要把 result_code 带到 V3 的状态判断里

有些博客会写“响应中 result_code 为 SUCCESS 就代表退款成功”，这是 V2 的接口语义。V3 的退款申请接口正常响应返回的是 HTTP 200，body 里根本没有 result_code，而是：

{ "out_refund_no": "REFUND202501010001_001", "refund_id": "5030020001", "status": "PROCESSING", "create_time": "2025-01-01T10:00:00+08:00" }

后续状态通过回调里的 refund_status 变化。常见状态如下表：

如果项目是从 V2 迁移到 V3，尤其要把字段名从 result_code 改成 status/refund_status。V3 退款申请接口返回的是 status，回调里返回的是 refund_status，两个字段在时间维度上不一样：status 是申请接口当时的受理状态，refund_status 是后续的流转结果。不要在同一个变量里混用，否则会出现“退款还没处理完就被标记成功”的脏数据。

4.3 重试与退避：超时后先查单再重发

退款接口超时后，最怕的是请求已经到达微信侧但响应丢失。此时如果盲目重发，可能把同一笔退款提交两次，导致生成两个 out_refund_no。所以重试策略应该是：先查询退款单状态，再决定是否重新发起申请。

for (int i = 0; i < 3; i++) { try { RefundQueryResp queryResp = refundApi.query(outRefundNo); if (queryResp != null) { return handleExisting(queryResp); } return refundApi.apply(request); } catch (SocketTimeoutException e) { RefundQueryResp queryResp = refundApi.query(outRefundNo); if (queryResp == null && i < 2) { Thread.sleep(1000L << i); // 退避 1s、2s continue; } throw e; } }

这里的查询接口是GET /v3/refund/domestic/refunds/{out_refund_no}。先把查询结果拿出来看，如果已经存在就直接返回，不再重复申请。Thread.sleep 只是简化示意，生产环境建议替换成 ScheduledExecutorService 或消息队列里的延迟消费。

回调处理本身要轻量，不要在收到回调后同步去调用其他外部接口或做重计算，否则微信在 5 秒内收不到响应会重复推送。接住回调后先验签解密，更新数据库状态，再把结果推给小程序前端即可。

5. 一个排查 V3 签名问题的实操技巧：把请求原样扣下来

排查 V3 签名问题时，最忌讳的是拿着“错误请求”的日志去猜。你需要的是把实际发送的 Authorization 头、请求体和签名串完整记录下来，然后手工复现计算签名。OkHttp 的 Application Interceptor 能做到这一点，并且不会污染业务代码。

5.1 用拦截器复制 body 并打印签名素材

public class SignatureLogInterceptor implements Interceptor { @Override public Response intercept(Chain chain) throws IOException { Request original = chain.request(); String bodyStr = ""; if (original.body() != null) { Buffer buffer = new Buffer(); original.body().writeTo(buffer); bodyStr = buffer.readUtf8(); } System.out.println("wxpay-v3-request: " + original.method() + " " + original.url().encodedPath() + " " + original.header("Authorization")); System.out.println("wxpay-v3-body: " + bodyStr); return chain.proceed(original); } }

这个拦截器会把发送到微信服务器的请求路径、Authorization 和 body 一次性拍下来。注意original.body()在执行chain.proceed(original)时还会再读取一次，因为 OkHttp 的 RequestBody 被 writeTo 写入 Buffer 后，原始 body 依然可以再次写入网络流，不会因为拦截器里的读取而失效。拿到日志后，把 Authorization 里的 timestamp、nonce_str、signature 字段值，以及 body 粘贴到临时文件，再写一个独立的方法用同样的算法重新计算签名。如果结果不一致，就是签名串、私钥加载或 body 内容出了问题。

5.2 常见 V3 退款错误码速查

遇到 SIGN_ERROR 时优先查服务器时间是否偏差过大。V3 请求签名里的 timestamp 是 Unix 秒，如果和微信服务器时间差超过 5 分钟会直接拒绝，很多调试到一半突然开始 SIGN_ERROR 的情况都源于服务器 NTP 失效。

5.3 把 timestamp 和 nonce_str 固定住，签名就能复现

在本地写一个不被框架调用的 test 方法，把 timestamp、nonce_str、serial_no 全部固定，传入固定的 body，输出计算出的 signature。这样每次跑出来的值都一样，适合做回归验证。唯一要注意的是固定值不能频繁使用，否则 nonce 被微信服务端记录后，重复请求会被拦截。这个固定签名的测试方法保留在工程里，之后接 V3 商家转账、分账、投诉回调时都能复用同一套验签逻辑。

本文还有配套的精品资源，点击获取