简介这份资源面向需要在Java后端接入微信H5支付的开发者尤其适合电商网站、移动应用等场景下希望打通网页支付流程的中初级工程师。内容围绕统一下单、预支付会话标识生成、支付链接与二维码转换、异步回调验签、订单查询、异常重试及安全合规等关键环节展开帮助读者理解从下单到支付结果确认的完整链路。压缩包共11个文件约16KB以5个Java源码和3个XML配置为主辅以properties配置、说明文档和HTML页面结构紧凑便于对照代码理解接口调用与参数配置。目前已有1320人学习下载可作为接入H5微信支付时的参考实现帮助读者梳理签名生成、回调处理与测试环境调试等易错点并借助部署说明快速搭建可运行的示例工程。1. 从一次支付回调丢单说起Java 后端接 H5 微信支付到底在做什么去年帮一个做知识付费的朋友排查线上问题用户付了钱、微信侧显示成功但订单状态一直停在「待支付」客服电话被打爆。翻日志发现回调接口收到了通知但验签失败被直接 return 掉了原因是证书序列号配错了一位。这类问题在 Java 接 H5 微信支付的场景里太常见了——不是接口调不通而是调通了之后的状态流转、签名校验、回调幂等这些「后半程」没做扎实。H5 微信支付本质上是商户后端调用统一下单接口拿到mweb_url前端跳转拉起微信中间页完成付款再靠异步回调把结果写回业务库。它适合移动端浏览器、公众号外链这类没有原生 SDK 的场景对 Java 后端来说核心工作量集中在签名、下单、回调三块而不是前端。下面按我实际拆过的顺序把能直接抄的代码和参数讲清楚。2. 签名与统一下单把 mweb_url 稳定拿到手2.1 先搞清楚 V3 的签名链路别在密钥上翻车微信支付 V3 和老的 V2 最大的区别是签名算法换成了 SHA256-RSA请求头里要带Authorization格式是WECHATPAY2-SHA256-RSA2048开头的一串。很多新手卡在第一步私钥格式不对。商户平台下载的apiclient_key.pem是 PKCS#8 的Java 里用KeyFactory.getInstance(RSA)配合PKCS8EncodedKeySpec就能加载但如果你拿到的是 PKCS#1开头是-----BEGIN RSA PRIVATE KEY-----直接喂进去会抛InvalidKeySpecException。常见做法是用 openssl 转一下# PKCS#1 转 PKCS#8转换后开头变成 BEGIN PRIVATE KEY openssl pkcs8 -topk8 -inform PEM -in apiclient_key.pem -outform PEM -nocrypt -out apiclient_key_pkcs8.pem签名串的拼装是有严格顺序的HTTP方法\nURL路径\n时间戳\n随机串\n请求体\n每一行以\n结尾最后一行请求体后面也要有\nGET 请求请求体为空但那个\n不能省。这个细节错了签名永远对不上而且微信返回的报错是笼统的SIGN_ERROR不会告诉你哪一行错了属于典型的黑匣子。我一般会先把待签名串打印出来和官方文档的示例逐字符比对确认换行符是\n而不是\r\n。public String buildSignMessage(String method, String urlPath, long timestamp, String nonce, String body) { // 注意body 为空时也要保留末尾换行否则签名不匹配 return method \n urlPath \n timestamp \n nonce \n (body null ? : body) \n; } public String sign(String message, PrivateKey privateKey) throws Exception { Signature signer Signature.getInstance(SHA256withRSA); signer.initSign(privateKey); signer.update(message.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(signer.sign()); }buildSignMessage里的urlPath只取域名后面的部分带 query 参数比如/v3/pay/transactions/h5?appidxxx不要带https://api.mch.weixin.qq.com。sign方法用SHA256withRSA输出 Base64。这两段是整个 V3 接口的地基后面所有请求都复用。2.2 H5 统一下单的请求体参数怎么填H5 下单接口是POST /v3/pay/transactions/h5请求体里几个字段必须和商户平台配置严格对应错一个就是PARAM_ERROR。下面是我常用的最小可用请求体{ appid: wx1234567890abcdef, mchid: 1900000001, description: 年度会员-12个月, out_trade_no: ORDER202405200001, time_expire: 2024-05-20T23:59:5908:00, notify_url: https://your-domain.com/pay/notify, amount: { total: 9900, currency: CNY }, scene_info: { payer_client_ip: 203.0.113.10, h5_info: { type: Wap } } }几个参数的血泪经验amount.total单位是分9900 就是 99 元别传成元out_trade_no只能包含字母数字和_-|*长度 6 到 32重复下单会返回ORDERPAID或OUT_TRADE_NO_USEDscene_info.h5_info.type固定填Wappayer_client_ip要传真实用户 IP微信会做风控校验传内网 IP 或127.0.0.1可能被拒。time_expire用 RFC3339 格式带时区不传默认 2 小时。请求头除了Authorization还要带Accept: application/json、Content-Type: application/json、User-Agent随便填个有意义的字符串即可。返回体里h5_url就是前端要跳转的地址注意它有时效性一般几分钟内有效别缓存起来反复用。// 组装 Authorization 头 String nonce UUID.randomUUID().toString().replace(-, ); long ts System.currentTimeMillis() / 1000; String message buildSignMessage(POST, /v3/pay/transactions/h5, ts, nonce, body); String signature sign(message, privateKey); String auth WECHATPAY2-SHA256-RSA2048 mchid\ mchid \, nonce_str\ nonce \, signature\ signature \, timestamp\ ts \, serial_no\ merchantCertSerial \;serial_no是商户 API 证书的序列号在商户平台「API 安全」里能看到不是平台证书序列号这两个搞混是高频翻车点。mchid是商户号字符串形式。2.3 前端跳转与降级处理拿到h5_url后前端直接window.location.href h5_url即可。但有个坑微信中间页会校验Referer如果你的页面在 iframe 里或者 Referer 被浏览器策略裁掉会提示「商家参数格式有误」。常见做法是确保跳转发生在顶层窗口且页面域名和商户平台配置的「H5 支付授权域名」一致。另外 iOS 上微信中间页拉起 App 后用户返回浏览器时页面状态可能丢失建议跳转前把订单号存到sessionStorage回来时轮询订单状态兜底。3. 回调验签与幂等钱到账了状态不能乱3.1 回调通知的验签要验三样东西微信回调是POST到你的notify_url请求头里有Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial请求体是加密的 JSON。验签分两步先用平台证书公钥验请求头签名再用 APIv3 密钥解密resource字段。验签串的拼装规则和请求签名一样时间戳\n随机串\n请求体\n。public boolean verifyNotify(String timestamp, String nonce, String body, String signature, PublicKey platformPublicKey) throws Exception { // 时间戳超过 5 分钟视为重放直接拒绝 long now System.currentTimeMillis() / 1000; if (Math.abs(now - Long.parseLong(timestamp)) 300) { return false; } String message timestamp \n nonce \n body \n; Signature verifier Signature.getInstance(SHA256withRSA); verifier.initVerify(platformPublicKey); verifier.update(message.getBytes(StandardCharsets.UTF_8)); return verifier.verify(Base64.getDecoder().decode(signature)); }platformPublicKey来自平台证书Wechatpay-Serial头告诉你用的是哪张证书多证书轮换期间要按序列号取对应公钥。时间戳校验是防重放的关键别省。3.2 解密 resource 并做幂等落库验签通过后resource里是ciphertext、nonce、associated_data用 APIv3 密钥做 AES-256-GCM 解密public String decryptResource(String ciphertext, String nonce, String associatedData, String apiV3Key) throws Exception { byte[] key apiV3Key.getBytes(StandardCharsets.UTF_8); byte[] nonceBytes nonce.getBytes(StandardCharsets.UTF_8); byte[] data Base64.getDecoder().decode(ciphertext); // GCM 密文末尾 16 字节是认证 tag byte[] cipherData Arrays.copyOfRange(data, 0, data.length - 16); byte[] tag Arrays.copyOfRange(data, data.length - 16, data.length); Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(key, AES), new GCMParameterSpec(128, nonceBytes)); if (associatedData ! null !associatedData.isEmpty()) { cipher.updateAAD(associatedData.getBytes(StandardCharsets.UTF_8)); } return new String(cipher.doFinal(cipherData, 0, cipherData.length, tag), StandardCharsets.UTF_8); }解密出来是{out_trade_no:...,transaction_id:...,trade_state:SUCCESS,...}。落库前必须做幂等以out_trade_no为唯一键先查订单状态如果已经是「已支付」就直接返回成功不要再改金额或重复发货。微信会重试回调最多 8 次间隔递增不做幂等就是重复发货的血案。另外回调接口必须返回 HTTP 200 且响应体{code:SUCCESS}返回其他状态码微信会一直重试。3.3 主动查单兜底别只信回调回调可能因为网络、部署、证书轮换各种原因丢生产环境一定要有主动查单。定时任务扫「待支付」且创建超过 5 分钟的订单调GET /v3/pay/transactions/out-trade-no/{out_trade_no}?mchidxxx查真实状态。查单接口同样要签名返回的trade_state是SUCCESS就补写状态。这个兜底逻辑我一般做成独立任务和回调走同一套状态机避免两处逻辑不一致。4. 避坑排查那些让回调静默失败的细节4.1 现象回调一直收不到日志里没有任何记录原因通常是notify_url不可达。微信要求公网 HTTPS端口只能是 443 或 80且不能带 query 参数。内网穿透工具临时调试可以但正式环境必须用备案域名。解决先用curl -X POST手动打一下你的回调地址确认能通再检查商户平台「开发配置」里的回调地址是否和代码里传的一致。4.2 现象验签返回 false但签名串看着没问题原因多半是请求体被框架改过。Spring 的RequestBody反序列化后再toString()拼签名串字段顺序、空格、转义都可能变导致验签失败。解决用HttpServletRequest的getInputStream()读原始字节或者加一个ContentCachingRequestWrapper缓存原始 body验签用原始字符串业务解析另起一次。4.3 现象解密抛AEADBadTagException原因是 APIv3 密钥不对或者associated_data传了空字符串而实际有值。APIv3 密钥是 32 位在商户平台「API 安全」里设置设置后不可查看只能重置重置会影响所有接口。解决核对密钥长度和内容associated_data严格按回调里的值传没有就传空字符串而不是null。4.4 现象订单状态偶发重复更新库存扣了两次原因是回调和查单任务并发执行没有加锁。解决更新状态用UPDATE orders SET statusPAID WHERE out_trade_no? AND statusPENDING靠数据库行锁和影响行数判断影响行数为 0 说明已被处理过直接返回成功。别用「先查后改」的两步操作。4.5 现象平台证书轮换后验签突然全挂原因是代码里硬编码了证书序列号或公钥。微信平台证书会定期轮换旧证书有过渡期。解决启动时拉取证书列表缓存按Wechatpay-Serial动态匹配或者用微信提供的证书下载接口定时刷新别把公钥写死在配置文件里。5. 进阶把支付模块做成可复用的组件做到上面这些单笔支付能跑通了但真实项目里往往有多个业务线要接支付重复写签名和回调解析很浪费。我的习惯是抽一个WxPayClient把签名、请求、验签、解密封装成四个方法业务侧只关心「下单」和「处理业务结果」。下面是一个精简的封装骨架public class WxPayClient { private final PrivateKey merchantKey; private final String mchid; private final String serialNo; private final String apiV3Key; private final MapString, PublicKey platformCerts; // serial - publicKey public String post(String path, String body) throws Exception { long ts System.currentTimeMillis() / 1000; String nonce UUID.randomUUID().toString().replace(-, ); String msg buildSignMessage(POST, path, ts, nonce, body); String sig sign(msg, merchantKey); // 组装 header 并发起 HTTPS 请求省略 HTTP 客户端细节 return doHttpPost(path, body, buildAuth(ts, nonce, sig)); } public NotifyResult parseNotify(HttpServletRequest request) throws Exception { String body readRawBody(request); String serial request.getHeader(Wechatpay-Serial); PublicKey pub platformCerts.get(serial); if (pub null) throw new IllegalStateException(未知平台证书: serial); boolean ok verifyNotify(request.getHeader(Wechatpay-Timestamp), request.getHeader(Wechatpay-Nonce), body, request.getHeader(Wechatpay-Signature), pub); if (!ok) throw new SecurityException(验签失败); return JSON.parseObject(decryptResource(/* 从 body 取字段 */), NotifyResult.class); } }这个骨架的关键设计点platformCerts用 Map 按序列号索引支持多证书并存parseNotify把验签和解密串起来业务侧拿到的是明文对象post方法统一处理签名和请求头业务方法只传 path 和 body。验证这套封装是否可靠我一般做三件事用官方提供的示例数据跑一遍签名比对构造一个过期时间戳的回调确认被拒模拟同一笔订单回调两次确认幂等生效。这三步走完基本能覆盖 90% 的线上异常。从那以后我每次接新的支付渠道都强制先把「签名串打印 回调原始 body 缓存 幂等 SQL」这三件事做掉再写业务逻辑宁可前期多花半天也不想半夜被丢单告警叫醒。希望帮到你。本文还有配套的精品资源点击获取
