Spring Boot 微信支付 APIv3 H5 接入与回调幂等实战

简介一套围绕Java后端与微信H5支付接口的实战示例面向需要为电商网站、移动应用网页端接入微信支付的初中级Java开发者重点解决统一下单、预支付会话生成、前端调起支付、异步回调验签与订单状态确认等环节的落地问题。压缩包共11个文件、约16KB以5个java源码和3个xml配置为主体辅以properties参数文件、doc部署说明与html支付页面便于对照理解接口调用、配置项和页面交互。已有1322人学习内容覆盖统一下单获取prepay_id、生成支付链接或二维码、支付回调处理、订单查询、异常重试及安全合规等关键点并区分测试与正式环境的调试思路。读者可据此快速搭建可运行的H5支付原型也可作为排查签名、回调与配置问题的参考部署文档还能帮助团队完成环境配置与后期维护。1. 从一次「点了没反应」的 H5 支付说起有个做商城 H5 的团队把支付接完了测试同学在电脑浏览器上点支付唤起二维码一切正常发到手机上用户在聊天窗口里点开链接再点「立即支付」页面毫无反应。查了半天日志服务端下单接口返回 200h5_url也拿到了问题出在这套 Java 微信支付代码写的是 H5 支付通道而 H5 支付只在系统浏览器里能拉起收银台在聊天窗口内置的浏览器里会被拦下那个场景得换 JSAPI。这类「代码没错、场景错了」的翻车在 H5 微信支付接入里占了一大半。这套工程要解决的就是后半段脏活把 APIv3 的签名、H5 下单、回调验签解密、幂等落库、主动查单兜底收进一个 Spring Boot 里能直接跑的分层结构。它适合两类人一类是手上有个手机站或落地页要在系统浏览器里拉起支付的后端另一类是已经接上了但回调重复入库、订单状态乱跳、退款对不上账的团队。下面按目录、下单链路、回调、踩坑、二次开发五段拆。2. 技术栈与工程骨架Spring Boot APIv3 的分层怎么切整套代码围绕微信支付 APIv3 搭建不再是早期那套 XML MD5 的 v2 接口。选型上很朴素Spring Boot 2.7 或 3.x 都行JDK 8 起步HTTP 客户端用 OkHttp长连接、超时可控比HttpURLConnection少踩坑JSON 序列化用 Jackson持久层 MyBatis-PlusRedis 做短期的订单锁和回调去重缓存MySQL 存订单和流水。密钥体系是这一版最关键的变化商户 API 私钥apiclient_key.pem 商户证书序列号 APIv3 密钥三样东西各管一件事很多人第一周就栽在把它们混成一样。2.1 依赖与配置项把商户参数从代码里赶出去先把会变的东西全部塞进配置文件。我见过太多项目把商户号写死在Service里换一个商户主体要全局搜索替换血泪经验。!-- pom.xml 关键依赖版本统一走 dependencyManagement -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置类用ConfigurationProperties绑定路径指向私钥文件而不是把私钥内容贴进 yml这样换机器只改路径wxpay: app-id: wx0000000000000000 mch-id: 1900000000 # 商户号字符串别用数字类型丢了前导零 mch-serial-no: 5157F09EFDC0... # 商户 API 证书序列号 private-key-path: /data/cert/apiclient_key.pem api-v3-key: 32位长度的APIv3密钥回调解密用 notify-url: https://your-domain.com/api/pay/notify h5-domain: https://your-domain.com # 必须与商户平台配置的 H5 支付域名一致提示mch-id一定要声明成 String。用Long接前导零会丢签名串里商户号对不上报错信息还只给你一个笼统的SIGN_ERROR。2.2 目录结构controller / service / channel 三层各管什么工程骨架按「协议层 - 业务层 - 通道层」切避免下单逻辑和订单状态机糅在一起src/main/java/com/example/pay ├── controller │ ├── PayController.java # 统一下单、查单、退款入口 │ └── PayNotifyController.java # 回调入口只做验签解密 转发 ├── service │ ├── OrderService.java # 订单创建、状态迁移、幂等控制 │ └── PayService.java # 编排下单 - 落库 - 返回链接 ├── channel │ ├── WxPaySigner.java # 签名与验签纯工具无业务依赖 │ ├── WxPayHttpClient.java # 统一封装 v3 请求自动带 Authorization │ └── WxH5PayChannel.java # H5 下单参数组装与响应解析 ├── notify │ └── WxNotifyDecoder.java # 通知报文验签 AES-GCM 解密 ├── entity / mapper # 订单、支付流水 └── task └── PayQueryTask.java # 定时主动查单补回调丢失分层原则很直接channel包里任何类都不允许 importOrderService它只负责「把请求发出去、把响应解出来」不知道订单概念。这样后面要加别的支付方式channel直接复用业务层不用动。PayNotifyController也刻意做薄——验签解密后把明文丢给OrderService控制层绝不写业务判断回调出问题时你只需要看一个地方。2.3 签名与验签一个字符串拼接错误能查一整天APIv3 的签名串是五行拼接格式固定少一个换行都不行Component public class WxPaySigner { Resource private WxPayProperties props; private PrivateKey privateKey; // 启动时加载一次别每次请求都读文件 PostConstruct public void init() throws Exception { String pem new String(Files.readAllBytes(Paths.get(props.getPrivateKeyPath()))); // 去掉 PEM 头尾和换行再 Base64 解码成 PKCS8 String base64 pem.replace(-----BEGIN PRIVATE KEY-----, ) .replace(-----END PRIVATE KEY-----, ) .replaceAll(\\s, ); PKCS8EncodedKeySpec spec new PKCS8EncodedKeySpec(Base64.getDecoder().decode(base64)); this.privateKey KeyFactory.getInstance(RSA).generatePrivate(spec); } /** * param method HTTP 方法大写 * param urlPath 带 query 的路径例如 /v3/pay/transactions/h5?mchid1900000000 * param body 请求体原文GET 或空体时传空字符串 */ public String buildAuthorization(String method, String urlPath, String body) throws Exception { long timestamp Instant.now().getEpochSecond(); // 秒级不是毫秒 String nonce RandomStringUtils.randomAlphanumeric(32); // 注意最后一行 body 后面还有一个换行 String message method \n urlPath \n timestamp \n nonce \n body \n; Signature signer Signature.getInstance(SHA256withRSA); signer.initSign(privateKey); signer.update(message.getBytes(StandardCharsets.UTF_8)); String signature Base64.getEncoder().encodeToString(signer.sign()); return WECHATPAY2-SHA256-RSA2048 mchid\ props.getMchId() \,nonce_str\ nonce \,timestamp\ timestamp \,serial_no\ props.getMchSerialNo() \,signature\ signature \; } }这段是整个工程的基石几个参数的含义必须咬死method必须大写GET写成get直接验签失败urlPath必须带 query string如果你传的是https://api.mch.weixin.qq.com开头的完整 URL把域名部分也带进去了同样失败body必须是最终发出去的原始字符串中间被 Jackson 重新序列化一遍、字段顺序变了、多了空格签名就对不上。我一般的做法是请求体先序列化成 String 存一个局部变量签名用它发送也用它绝不二次序列化。3. 下单链路拆解从组装报文到前端拿到跳转链接H5 下单接口是POST /v3/pay/transactions/h5一次完整调用分四步生成商户订单号并落库、组装请求体、带签名发请求、解析h5_url返回给前端。任何一步做错前端拿到的都是「商家参数格式有误」这种看不出所以然的提示。3.1 请求体组装与商户订单号生成规则请求体里有几个字段是必填且不能想当然的scene_info.payer_client_ip传用户真实出口 IP传内网 IP 或者127.0.0.1会被拒scene_info.h5_info.type固定Wapamount.total单位是分整数不接受小数。public MapString, Object buildH5OrderBody(String orderNo, int totalFen, String ip, String desc) { MapString, Object body new LinkedHashMap(); body.put(appid, props.getAppId()); body.put(mchid, props.getMchId()); body.put(description, desc); // 商品描述用户账单上看得到 body.put(out_trade_no, orderNo); // 商户订单号6-32 位全局唯一 body.put(notify_url, props.getNotifyUrl()); // 必须是 https 公网地址 body.put(amount, Map.of(total, totalFen, currency, CNY)); body.put(scene_info, Map.of( payer_client_ip, ip, h5_info, Map.of(type, Wap) // 固定值别改 )); return body; }用LinkedHashMap而不是HashMap不是签名需要签名用最终字符串而是排查日志时字段顺序稳定肉眼对报文舒服。订单号我一般用「业务前缀 yyyyMMddHHmmss 6 位随机」比如H5_20240512103015_834271长度控制在 32 位以内前缀方便后面按渠道筛单。生成之后先入库状态UNPAID再去调下单——反过来先调接口再落库一旦落库失败用户已经能付款了你却查不到这笔单这就是典型的后悔药没处买。3.2 带签名发送请求一个统一 HTTP 客户端省掉重复代码所有 v3 接口的调用姿势一样算签名、塞Authorization头、带Accept: application/json、超时控制。抽一个客户端出来Component public class WxPayHttpClient { private static final String BASE https://api.mch.weixin.qq.com; private final OkHttpClient client new OkHttpClient.Builder() .connectTimeout(3, TimeUnit.SECONDS) .readTimeout(10, TimeUnit.SECONDS) // 下单接口偶发慢别设 2 秒 .build(); Resource private WxPaySigner signer; public String post(String urlPath, String jsonBody) throws Exception { String auth signer.buildAuthorization(POST, urlPath, jsonBody); Request request new Request.Builder() .url(BASE urlPath) .addHeader(Authorization, auth) .addHeader(Accept, application/json) .addHeader(Content-Type, application/json) .post(RequestBody.create(jsonBody, MediaType.parse(application/json))) .build(); try (Response resp client.newCall(request).execute()) { String respBody resp.body() null ? : resp.body().string(); if (!resp.isSuccessful()) { // 微信的错误体里 code message 才是排查依据别只打状态码 throw new WxPayException(微信支付调用失败 resp.code() respBody); } return respBody; } } }这里的urlPath是相对路径域名在客户端内部拼保证签名时用的路径和实际请求的路径完全一致。错误处理特意把响应体打出来因为微信的错误体形如{code:PARAM_ERROR,message:...}message里会明确指出哪个字段不对只看 400 等于放弃线索。超时上读超时给到 10 秒是因为个别时段下单接口抖动2 秒超时会让用户看到失败但订单已经创建了。3.3 解析 h5_url前端跳转与回跳域名配置下单成功后返回体里关键就一个h5_url前端拿到直接window.location.href h5_url即可拉起收银台。想支付完回到自己页面下单时加redirect_url且这个地址的域名必须在商户平台登记过。public String createH5Pay(String orderNo, int totalFen, String ip, String desc) throws Exception { // 1. 先落库防止「用户付了但系统没单」 orderService.createUnpaidOrder(orderNo, totalFen); // 2. 组装并序列化一次签名和发送复用同一个字符串 String body objectMapper.writeValueAsString( buildH5OrderBody(orderNo, totalFen, ip, desc)); // 3. 调接口 String resp wxPayHttpClient.post(/v3/pay/transactions/h5, body); JsonNode node objectMapper.readTree(resp); String h5Url node.path(h5_url).asText(); if (h5Url.isEmpty()) { throw new WxPayException(未返回 h5_url响应 resp); } return h5Url; }参数说明orderNo一旦生成不允许改退款、查单、对账全靠它totalFen全程用分数据库字段也存分只有展示层才除以 100混用是最常见的金额错乱来源ip从X-Forwarded-For取第一个非内网地址经过 Nginx 时别直接取getRemoteAddr()。注意h5_url有有效期一般是 5 分钟量级前端拿到后立刻跳转别缓存到下一个页面再用。4. 回调通知处理支付结果怎么可靠地落进数据库下单只是把用户送到收银台真正决定订单状态的是异步通知。这一环出问题表现往往是「用户说付了后台还是待支付」客服只能手工补单。4.1 三道关验签、解密、字段校验通知报文是加密的resource里是ciphertext、nonce、associated_data三段用 APIv3 密钥做 AES-256-GCM 解密。解密之前必须先验签验签用的是微信支付平台证书或平台公钥别跳过这步否则任何人构造一个 POST 就能把你的订单改成已支付。public String decryptResource(String associatedData, String nonce, String ciphertext) throws Exception { Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec key new SecretKeySpec( props.getApiV3Key().getBytes(StandardCharsets.UTF_8), AES); // GCM tag 长度固定 128 bit 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); }参数对应的就是报文里的三个字段一个都不能错位associated_data传成nonce解密会直接抛AEADBadTagExceptionapiV3Key长度不是 32 位同样解不开。解出来的明文里有out_trade_no、transaction_id、trade_state、amount.total、payer_openid落库前我固定做三项校验trade_state必须是SUCCESSamount.total必须和本地订单金额相等mchid和appid必须和配置一致。金额不等就直接告警不落库这种情况基本意味着有人拿别的单号来撞。4.2 幂等设计同一笔通知被推八次也别慌微信的通知是「至少一次」语义没收到成功应答会按策略重试多次网络抖动、你的服务重启、处理超时都会触发重推。所以处理逻辑必须天然幂等靠的是数据库的条件更新不是内存里的Set。-- 只有从 UNPAID 迁移到 PAID 才算真正处理重复执行影响 0 行 UPDATE t_order SET status PAID, transaction_id #{transactionId}, pay_time NOW() WHERE order_no #{orderNo} AND status UNPAID AND amount #{amount}Transactional(rollbackFor Exception.class) public boolean handlePaid(String orderNo, String transactionId, int amount) { int updated orderMapper.markPaid(orderNo, transactionId, amount); if (updated 0) { // 已经处理过或金额/状态不匹配直接返回 true 让微信停止重推 log.info(通知重复或状态不符跳过 orderNo{}, orderNo); return true; } // 只有真正迁移成功的那一次才发消息、加积分、扣库存 notifyBusiness(orderNo); return true; }这段的关键在于「状态机 CAS」把幂等判断交给一条带WHERE status UNPAID的更新语句影响行数是 0 就说明别人已经处理过了。这样即使两个回调线程同时进来也只有一个能更新成功不需要分布式锁。副作用发货、发券一定放在更新成功之后放前面就会出现「重复发了三次货、订单还是一条」。4.3 主动查单兜底回调丢了不至于干等再稳的回调也可能丢服务器换 IP、网关限流、证书轮换期间验签失败。所以一定要有兜底——定时扫一段窗口内的未支付订单主动去查。// GET /v3/pay/transactions/out-trade-no/{out_trade_no}?mchidxxx public void queryAndFix(String orderNo) throws Exception { String path /v3/pay/transactions/out-trade-no/ orderNo ?mchid props.getMchId(); // 注意GET 请求也要签名urlPath 必须带上 query String resp wxPayHttpClient.get(path); JsonNode node objectMapper.readTree(resp); if (SUCCESS.equals(node.path(trade_state).asText())) { int total node.path(amount).path(total).asInt(); orderService.handlePaid(orderNo, node.path(transaction_id).asText(), total); } }扫描策略我一般这么定只查创建时间在 5 分钟到 24 小时之间的UNPAID订单每分钟一批每批限 100 条走同一个handlePaid幂等逻辑天然复用。超过 24 小时的基本是用户放弃支付查下去浪费调用量5 分钟内的正常等回调过早查会拿到NOTPAY。这套组合下来「用户付了钱后台没反应」的工单量能压到接近零。5. 踩坑排查H5 支付最容易翻车的五个点这一节按「现象 → 原因 → 解决」记都是我在真实联调里反复遇到的遇到时对照着看能省不少时间。现象一手机上点支付完全没反应服务端日志显示下单成功。原因是打开页面的环境不对。H5 支付只能在系统浏览器Safari、Chrome、各家手机自带浏览器里拉起收银台在聊天软件的内置浏览器里会被拦截接口本身不会报错。解决方法是在前端做环境嗅探命中内置浏览器 UA 时引导用户「右上角打开浏览器」或者这个场景直接改走 JSAPI 支付两条链路并存。别指望后端能兜住后端拿到的信息不足以判断。现象二下单报「商家参数格式有误请联系商家解决」。八成是 H5 支付域名没配或者在商户平台配的域名和实际访问域名不一致带没带 www 都算不同。去商户平台把支付授权目录/域名补上注意协议是 https路径要精确到目录层级。还有一个隐蔽原因scene_info.payer_client_ip传了127.0.0.1或内网地址网关直接拒。取真实 IP 时看X-Forwarded-For的第一段。现象三所有接口都报SIGN_ERROR但私钥文件明明是对的。按顺序查三件事签名串第五行body后面有没有换行urlPath是不是带了 queryGET 查单最容易漏timestamp是不是用了毫秒。还有一种情况是私钥文件是 PKCS#1 格式头是BEGIN RSA PRIVATE KEY代码里却按 PKCS#8 解析KeyFactory会直接抛异常需要先转格式。现象四回调解密抛AEADBadTagException或认证失败。要么apiV3Key填错在商户平台设置的 32 位密钥不是 API 密钥也不是证书序列号要么三个参数位置传错。还有一种极容易被忽略报文里的ciphertext先被 Base64 解了一次再传进方法导致二次解码乱码。我的习惯是解密方法只接收原始字符串内部统一做一次 Base64 解码。现象五同一笔订单重复发货、重复加积分。回调没做幂等。修复方式就是 4.2 那条WHERE status UNPAID的条件更新把所有副作用挪到更新成功之后。已经产生的脏数据只能靠对账脚本回捞所以这个改动越早上越好。提示联调阶段把每次请求的Authorization、请求体、响应体原样落到一个独立的日志文件里出问题时可以直接对照签名串逐行比比在几百行业务日志里翻要快得多。6. 二次开发把支付通道抽成可替换的策略项目跑通之后最常见的需求是加第二个支付方式或者按商户主体分流。如果下单逻辑还写在PayService里加一个渠道就要复制一遍流程改一处漏一处。我的做法是先把通道抽象出来。public interface PayChannel { String code(); // WX_H5 / ALI_WAP ... String createPay(PayRequest req); // 返回给前端的跳转地址 boolean verifyNotify(MapString, String headers, String body); // 验签 PayResult parseNotify(String body); // 解密出统一结果 }三个方法各对应一段链路PayResult里只放业务关心的字段商户订单号、渠道流水号、实付金额、支付状态。上层PayService只依赖接口靠一个 Map 做注册表按code取实现Component public class PayChannelRegistry { private final MapString, PayChannel channels new HashMap(); public PayChannelRegistry(ListPayChannel list) { list.forEach(c - channels.put(c.code(), c)); // Spring 自动注入所有实现 } public PayChannel get(String code) { PayChannel c channels.get(code); if (c null) throw new IllegalArgumentException(未支持的支付渠道: code); return c; } }改造时有几个点值得提前想清楚。第一createPay的返回值统一成「跳转地址」而不是各渠道自己的响应对象H5 场景下都是跳 URL抽象成本最低如果以后接扫码支付返回的是二维码内容就在PayRequest里加一个payMode别改接口签名。第二回调入口按渠道拆成不同 URL比如/api/pay/notify/wx、/api/pay/notify/ali验签规则差异太大硬塞进一个入口会写出一堆if。第三幂等和状态机必须留在业务层通道层只负责「翻译」这样新增渠道不需要重写幂等。验证方式我用两层单元测试里 mock 掉WxPayHttpClient断言「订单先落库再调接口」的顺序以及「重复回调只触发一次副作用」集成测试用固定报文回放把历史抓下来的加密通知存成文件喂给parseNotify断言解出的金额和单号。这套测试最大的价值不是覆盖率而是以后有人改签名拼接时能立刻发现验签挂了。还有一个我踩过的坑值得提前规避多渠道之后out_trade_no的生成规则要带渠道前缀否则两个渠道的订单号可能撞车对账时根本无法区分归属。对账脚本也建议按渠道分表统计日终跑一次「本地已支付 vs 渠道已支付」的差集差额自动发起查单补偿。从那以后我每次接新的支付通道都强制先把回调幂等、主动查单、金额单位这三件事写完再动业务代码——顺序反了后面补的成本是原来的好几倍。希望帮到你。本文还有配套的精品资源点击获取