微信小程序支付后台Java实现：从下单到回调的完整闭环

简介这份资源是面向Java后端开发者与小程序开发者的微信小程序支付后台实现实例聚焦于打通小程序端与微信支付接口的完整链路适合已具备一定Java与网络通信基础、希望快速落地支付功能的中级开发者参考。资源包共1个文件为1个PDF文档压缩包约71KB内容以代码实例与流程讲解为主便于直接对照阅读。目前已有2341人学习下载说明其在支付后台实现方向具备一定参考价值。文档围绕OpenId获取、订单号生成与管理、微信统一下单接口调用、XML数据解析与二次签名、前端调起支付等关键环节展开并涉及环境变量配置、异常处理、notify_url回调通知以及支付状态查询与验证等实践要点。读者可从中获取一套可参照的支付后台代码骨架与排错思路理解签名与安全校验的落地方式为构建稳定、安全、高效的支付系统提供直接帮助。1. 微信小程序支付后台 Java 实现从下单到回调一个能跑通的闭环做过微信小程序支付的人都知道前端wx.requestPayment那几行调用其实是最简单的部分。真正让人熬夜的是后台统一下单签名怎么拼、回调怎么验签、订单状态怎么保证不重复、退款怎么对账。我见过不少团队前端半天就联调完了后台却卡了整整一周最后发现是签名串里某个字段顺序错了或者回调地址外网访问不通。这篇笔记就围绕「微信小程序支付后台 Java 实现」这个主题把从商户下单、签名生成、回调处理到订单落库的完整链路拆开讲。适合正在做小程序电商、知识付费、预约类业务的 Java 后端也适合想搞清楚支付闭环到底有哪些坑的开发者。下面所有代码都是可复现的最小实现参数含义和踩坑点我会逐个标注。2. 支付后台的整体链路与 Java 侧技术选型在动手写代码之前先把「谁跟谁说话」这件事理清楚。微信小程序支付的资金流和信息流是分开的用户在小程序里点支付小程序调用wx.requestPayment唤起收银台但真正决定这笔钱能不能收的是后台拿着商户号、密钥去调用微信的统一下单接口。很多新手会误以为前端传个金额就能付结果发现签名对不上根本原因是签名必须在服务端做密钥绝不能下发到小程序。2.1 一次支付到底经过哪几个系统把链路拆成四段来看会清晰很多。第一段是小程序端发起请求把商品 ID、数量、用户标识openid传给自己的后台第二段是后台组装参数调用微信支付的统一下单接口拿到prepay_id第三段是后台把prepay_id连同签名一起返回给小程序小程序用这些参数唤起收银台第四段是用户付款成功后微信服务器异步回调后台配置的 notify_url后台验签、更新订单、返回成功应答。这四段里第一段和第三段是业务逻辑第二段和第四段才是支付的核心。第二段决定了「能不能下单」第四段决定了「钱到账后订单状态对不对」。我一般会把第二段封装成一个WxPayService第四段单独做一个PayNotifyController职责分开后面排查问题的时候一眼就能定位是哪一段出的错。提示notify_url 必须是外网可访问的 HTTPS 地址本地开发时用内网穿透工具映射一个临时域名否则回调永远收不到订单会一直停在「待支付」。2.2 Java 侧为什么选这套组合后台实现微信支付Java 生态里常见的有三种做法直接用官方 SDK、用第三方封装库、纯手写 HTTP 加签名。官方 SDK 更新不算勤但胜在稳定第三方库封装得舒服但出问题时排查链路长纯手写最透明适合想彻底搞懂签名机制的团队。我自己的习惯是核心的签名和验签逻辑手写HTTP 请求用HttpClient或OkHttpJSON 处理用Jackson或Fastjson。这样做的原因是签名是支付里最容易出错的地方手写一遍你就知道每个字段是怎么参与拼接的后面遇到「签名错误」的报错能直接定位到是哪个参数的问题而不是对着 SDK 的黑匣子干瞪眼。技术栈上Spring Boot 是主流选择配合RestController暴露下单和回调接口。数据库用 MySQL 存订单订单表里至少要有out_trade_no商户订单号、transaction_id微信订单号、total_fee金额单位分、status状态、openid这几个字段。金额一定要用「分」做单位存整数用浮点数存金额是血泪教训后面对账时会出现一分钱的差异查起来非常痛苦。2.3 商户号、密钥与证书的准备工作动手写代码前有几样东西必须先拿到商户号mch_id、API 密钥APIv2 是 32 位字符串APIv3 是证书体系、小程序 appid、以及 APIv3 需要的商户私钥和平台证书。APIv2 和 APIv3 的签名机制完全不同新手容易混用。APIv2 用的是 MD5 或 HMAC-SHA256把参数按字典序拼接后加上密钥做摘要APIv3 用的是 SHA256-RSA需要用商户私钥对请求签名回调验签则用微信平台证书的公钥。现在新接入的商户默认走 APIv3但很多存量系统还在用 APIv2。下面代码我以 APIv2 为主线讲因为它的签名逻辑最直观理解了它再去看 APIv3 会轻松很多。项目APIv2APIv3签名算法MD5 / HMAC-SHA256SHA256-RSA密钥形式32 位 API 密钥商户私钥 平台证书回调验签同样用 API 密钥用平台证书公钥验签适用场景存量系统、快速接入新接入、安全性要求高选型上没有绝对优劣如果是从零开始的新项目直接上 APIv3如果是维护老系统继续用 APIv2 也没问题关键是别把两套签名逻辑混在一起用。3. 统一下单接口的 Java 实现与签名细节这一章是整篇的核心把统一下单从参数组装到拿到prepay_id的完整过程写清楚。签名是重中之重我会把拼接规则、字段顺序、空值处理都讲透。3.1 下单参数组装与签名生成统一下单的接口地址是https://api.mch.weixin.qq.com/pay/unifiedorder请求体是 XML 格式。参数里必填的有appid、mch_id、nonce_str、body、out_trade_no、total_fee、spbill_create_ip、notify_url、trade_type。小程序支付时trade_type固定为JSAPI并且必须传openid。签名规则是这样的把所有非空参数按参数名的 ASCII 码从小到大排序用keyvaluekeyvalue的形式拼接成字符串最后拼上keyAPI密钥做 MD5 得到大写签名。注意sign字段本身不参与签名空值参数也不参与。import java.security.MessageDigest; import java.util.*; public class WxPaySignUtil { /** * 生成 APIv2 签名 * param params 参与签名的参数不含 sign不含空值 * param apiKey 商户 API 密钥 * return 大写 MD5 签名 */ public static String generateSign(MapString, String params, String apiKey) { // 1. 过滤空值并按 key 的 ASCII 码升序排序 ListString keys new ArrayList(); for (Map.EntryString, String entry : params.entrySet()) { if (entry.getValue() ! null !entry.getValue().isEmpty()) { keys.add(entry.getKey()); } } Collections.sort(keys); // 2. 拼接成 keyvaluekeyvalue 形式 StringBuilder sb new StringBuilder(); for (String key : keys) { sb.append(key).append().append(params.get(key)).append(); } // 3. 拼上 API 密钥 sb.append(key).append(apiKey); // 4. MD5 并转大写 return md5(sb.toString()).toUpperCase(); } private static String md5(String text) { try { MessageDigest md MessageDigest.getInstance(MD5); byte[] bytes md.digest(text.getBytes(UTF-8)); StringBuilder hex new StringBuilder(); for (byte b : bytes) { String s Integer.toHexString(b 0xFF); if (s.length() 1) hex.append(0); hex.append(s); } return hex.toString(); } catch (Exception e) { throw new RuntimeException(MD5 计算失败, e); } } }这段代码的关键点有三个。第一Collections.sort(keys)用的是字符串自然排序正好对应 ASCII 码升序不要用其他排序方式。第二空值过滤必须在排序之前做否则拼接串里会多出key这种片段导致签名对不上。第三MD5 结果要转大写微信要求签名是大写十六进制小写会直接报签名错误。参数说明上nonce_str是随机字符串建议用 UUID 去掉横线长度不超过 32 位out_trade_no是商户自己的订单号必须全局唯一重复下单会返回错误total_fee是整数单位分比如 1 元要传 100spbill_create_ip传调用方的 IP小程序场景下传服务器 IP 即可。3.2 发起 HTTP 请求并解析 prepay_id签名拼好后把参数转成 XML用 POST 发给统一下单接口。返回的也是 XML里面包含return_code、result_code和prepay_id。注意return_code是通信标识result_code是业务标识两个都为 SUCCESS 才算下单成功。import org.apache.http.client.methods.*; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.util.*; public class UnifiedOrderService { private static final String UNIFIED_ORDER_URL https://api.mch.weixin.qq.com/pay/unifiedorder; public String unifiedOrder(String openid, String outTradeNo, int totalFee, String apiKey, String appid, String mchId) throws Exception { MapString, String params new HashMap(); params.put(appid, appid); params.put(mch_id, mchId); params.put(nonce_str, UUID.randomUUID().toString().replace(-, )); params.put(body, 测试商品); params.put(out_trade_no, outTradeNo); params.put(total_fee, String.valueOf(totalFee)); params.put(spbill_create_ip, 127.0.0.1); params.put(notify_url, https://your-domain.com/pay/notify); params.put(trade_type, JSAPI); params.put(openid, openid); // 生成签名并放入参数 String sign WxPaySignUtil.generateSign(params, apiKey); params.put(sign, sign); // 转 XML String xml mapToXml(params); // 发送请求 try (CloseableHttpClient client HttpClients.createDefault()) { HttpPost post new HttpPost(UNIFIED_ORDER_URL); post.setEntity(new StringEntity(xml, UTF-8)); post.setHeader(Content-Type, application/xml); try (CloseableHttpResponse response client.execute(post)) { String respXml EntityUtils.toString(response.getEntity(), UTF-8); // 解析返回的 prepay_id MapString, String respMap xmlToMap(respXml); if (SUCCESS.equals(respMap.get(return_code)) SUCCESS.equals(respMap.get(result_code))) { return respMap.get(prepay_id); } throw new RuntimeException(下单失败: respXml); } } } private String mapToXml(MapString, String map) { StringBuilder sb new StringBuilder(xml); for (Map.EntryString, String e : map.entrySet()) { sb.append().append(e.getKey()).append() .append(e.getValue()) .append(/).append(e.getKey()).append(); } return sb.append(/xml).toString(); } private MapString, String xmlToMap(String xml) { // 简化实现实际可用 dom4j 或 JAXB 解析 MapString, String map new HashMap(); // 解析逻辑略按标签名提取文本内容 return map; } }逻辑说明先组装参数再调签名工具生成sign然后转 XML 发送。返回结果里prepay_id是后续小程序唤起收银台的关键。参数上notify_url必须和后台实际暴露的接口一致body是商品描述会显示在用户账单里不要写特殊字符。注意XML 里的金额、订单号等字段不要做 URL 编码微信接口对 XML 内容有格式要求编码后反而会解析失败。3.3 返回给小程序端的二次签名拿到prepay_id后不能直接丢给小程序还要做一次「二次签名」。这次签名的参数是appId、timeStamp、nonceStr、package格式为prepay_idxxx、signType。签名算法和上面一样只是参数集合不同。public MapString, String buildPayParams(String prepayId, String appid, String apiKey) { MapString, String params new HashMap(); params.put(appId, appid); params.put(timeStamp, String.valueOf(System.currentTimeMillis() / 1000)); params.put(nonceStr, UUID.randomUUID().toString().replace(-, )); params.put(package, prepay_id prepayId); params.put(signType, MD5); String paySign WxPaySignUtil.generateSign(params, apiKey); params.put(paySign, paySign); return params; }这里有个容易翻车的点appId的写法是驼峰而统一下单里是appid全小写两个地方不一样混用会导致签名错误。timeStamp是秒级时间戳不是毫秒。返回给小程序后前端用这些字段调wx.requestPayment即可。4. 支付回调处理与订单状态一致性保障回调是支付里最容易被忽视、又最容易出事故的环节。用户付了钱微信会往notify_url发一个 POST 请求后台必须验签、处理业务、返回成功应答。如果处理不当会出现「钱扣了订单还是待支付」或者「重复发货」的问题。4.1 回调验签与应答格式回调的请求体也是 XML里面包含return_code、result_code、out_trade_no、transaction_id、total_fee、sign等字段。验签的逻辑和下单时一样把除sign外的非空参数排序拼接加上 API 密钥做 MD5和回调里的sign比对。RestController RequestMapping(/pay) public class PayNotifyController { PostMapping(/notify) public String notify(RequestBody String xmlBody) { MapString, String params xmlToMap(xmlBody); String signFromWx params.get(sign); // 1. 验签 MapString, String signParams new HashMap(params); signParams.remove(sign); String calcSign WxPaySignUtil.generateSign(signParams, API_KEY); if (!calcSign.equals(signFromWx)) { return xmlreturn_code![CDATA[FAIL]]/return_code/xml; } // 2. 判断业务结果 if (!SUCCESS.equals(params.get(result_code))) { return xmlreturn_code![CDATA[SUCCESS]]/return_code/xml; } // 3. 处理订单幂等 String outTradeNo params.get(out_trade_no); String transactionId params.get(transaction_id); orderService.markPaid(outTradeNo, transactionId); // 4. 返回成功应答 return xmlreturn_code![CDATA[SUCCESS]]/return_codemessage![CDATA[OK]]/message/xml; } }逻辑说明验签失败直接返回 FAIL微信会重试业务处理成功返回 SUCCESS微信就不再重发。应答格式必须是 XML且return_code用 CDATA 包裹。4.2 幂等处理同一笔回调可能来很多次微信的回调是「至少一次」语义同一笔订单的回调可能重复到达。如果后台不做幂等就会出现重复加积分、重复发货。常见做法是在订单表上加唯一索引或者用状态机控制只有状态为「待支付」的订单才允许更新为「已支付」。Service public class OrderService { Transactional public void markPaid(String outTradeNo, String transactionId) { // 悲观锁或乐观锁保证并发安全 Order order orderMapper.selectForUpdate(outTradeNo); if (order null) { throw new RuntimeException(订单不存在); } // 幂等判断已支付直接返回 if (PAID.equals(order.getStatus())) { return; } order.setStatus(PAID); order.setTransactionId(transactionId); orderMapper.updateById(order); } }参数说明selectForUpdate是行锁查询保证同一订单的并发回调串行处理。状态判断放在锁内避免两个线程同时通过判断。如果不用数据库锁也可以用 Redis 分布式锁key 用订单号。4.3 金额校验与订单落库回调里带的total_fee必须和后台订单的金额比对防止被篡改。虽然微信本身有签名保护但多一道校验不亏。金额不一致时记录日志并告警不要直接更新订单。if (!String.valueOf(order.getTotalFee()).equals(params.get(total_fee))) { log.error(金额不一致订单号{}本地{}回调{}, outTradeNo, order.getTotalFee(), params.get(total_fee)); return xmlreturn_code![CDATA[FAIL]]/return_code/xml; }订单落库时transaction_id要存下来后面退款和对账都要用。状态字段建议用枚举不要用魔法数字。5. 避坑与常见问题排查这一章记录几个我在实际项目里踩过的坑每条按「现象 → 原因 → 解决」写希望能帮你少走弯路。5.1 签名错误90% 是这几个原因现象调用统一下单返回「签名错误」。原因通常有四种一是参数里有空值没过滤拼接串多了key二是字段顺序没按 ASCII 升序三是 API 密钥填错比如把 APIv3 的密钥用在 APIv2 上四是编码问题中文参数没做 UTF-8 处理。解决方法是把拼接前的字符串打印出来和微信官方文档的示例逐字比对重点看有没有多余的空格或换行。5.2 回调收不到先查网络再查代码现象用户付款成功但订单状态一直是待支付。原因可能是notify_url外网访问不通、接口返回的不是 XML、或者返回了非 SUCCESS 导致微信重试但一直失败。解决方法是先用工具模拟微信发一个回调请求确认接口能正常响应再检查服务器防火墙和域名解析。如果用的是云服务器安全组要放行 443 端口。5.3 重复回调导致重复发货现象用户收到两份商品。原因是回调没有做幂等两次回调都执行了发货逻辑。解决方法是在订单表加唯一索引或者用状态机加行锁。我一般会在markPaid方法里先查状态已支付直接返回配合数据库行锁基本能杜绝。5.4 金额单位搞错1 元变成 1 分现象用户付了 1 分钱买到了 100 元的商品。原因是前端传的金额是元后台没乘 100 就传给微信。解决方法是统一约定前端传元后台转分数据库存分回调校验也用分。所有涉及金额的地方都加注释标明单位。5.5 证书过期导致 APIv3 调用失败现象某天突然所有支付都失败报证书相关错误。原因是 APIv3 的平台证书有有效期过期后验签会失败。解决方法是定期检查证书有效期提前更换。可以在启动时加一个健康检查证书快过期时发告警。6. 对账、退款与一个可复用的验证习惯支付做完不是终点对账和退款才是长期要维护的部分。这一章讲两个进阶话题再分享一个我自己的验证习惯。对账的核心是「拿微信的账单和本地订单比对」。微信提供下载对账单的接口每天定时拉取解析后和本地订单逐笔核对。差异通常来自三种情况本地有订单微信没有可能是下单失败但本地记录了、微信有订单本地没有回调丢失、金额不一致篡改或 bug。对账脚本建议用定时任务跑差异结果落库并告警。退款接口和下单类似也需要签名。关键参数是out_trade_no或transaction_id、out_refund_no退款单号、total_fee、refund_fee。退款是异步的也要配置回调。退款成功后订单状态要更新为「已退款」并记录退款单号。场景接口关键参数注意事项下单unifiedorderout_trade_no, total_fee订单号唯一退款refundout_refund_no, refund_fee退款金额不能超过订单金额对账downloadbillbill_date, bill_type账单有延迟建议凌晨拉取最后说一个我自己的验证习惯每次改完支付相关代码不要只在测试环境点一下。我会写一个小的脚本模拟完整的「下单 → 回调 → 查单」流程把每一步的请求和响应都打印出来。这样即使后面换了参数或者升级了依赖跑一遍脚本就知道有没有回归问题。支付这东西玄学的地方不多大部分问题都能通过「把中间结果打出来」定位。别怕日志多出问题的时候你会感谢自己当初多打的那几行。希望帮到你。本文还有配套的精品资源点击获取