1. 项目概述为什么选择银联商务作为微信小程序的支付通道在微信小程序的生态里支付功能几乎是商业类应用的标配。一提到小程序支付大家的第一反应往往是“微信支付”。这没错微信支付确实是官方原生的、最直接的方案。但在我经手的多个项目中尤其是涉及多商户、分账、对账复杂或者需要对接特定银行渠道的场景直接使用微信支付的原生接口有时会显得“不够用”或者“太麻烦”。这时候像银联商务这样的第三方支付服务商就提供了一个非常值得考虑的备选方案。简单来说银联商务是一个拥有全牌照的综合性支付服务机构它就像一个“支付中台”背后聚合了包括微信支付、支付宝、银联云闪付、各大银行网关在内的多种支付渠道。当我们的小程序通过银联商务的接口发起支付时用户在前端看到的依然是熟悉的微信支付收银台体验上几乎无感。但对于我们开发者尤其是后台开发者而言整个对接逻辑、订单管理和资金结算的流程都变成了与银联商务的单一接口进行交互。这样做最直接的好处是统一化和专业化你只需要对接一套API就能获得微信支付的能力同时还能享受银联商务在风控、对账、分账、大额交易等方面的增值服务。特别适合那些本身业务系统已经与银联商务有合作或者未来有拓展多支付渠道计划的项目。所以这个项目的核心就是在微信小程序的前端框架下绕开微信支付的原生SDK通过调用银联商务提供的API实现从下单、调起支付到支付结果通知的完整闭环。这不仅仅是换一个接口调用那么简单它涉及到支付流程的重新设计、参数传递方式的变化以及安全策略的调整。接下来我会把整个实现过程拆解清楚包括设计思路、具体步骤和那些官方文档里不会写的“坑”。2. 核心流程设计与银联商务通道解析在动手写代码之前我们必须把两个支付流程的差异理解透彻。这是决定项目成败的关键。2.1 标准微信支付流程 vs. 银联商务中转流程标准微信小程序支付流程官方小程序前端调用wx.login()获取用户临时凭证code传给后台。后台用code、小程序appid和secret调用微信接口换取用户的openid。后台用openid、商户号、订单信息等参数调用微信支付统一下单接口获得一个prepay_id预支付交易会话标识。后台再根据prepay_id生成支付所需的签名参数包包括timeStamp,nonceStr,package,signType,paySign返回给小程序前端。小程序前端调用wx.requestPayment()传入这个参数包即可调起微信支付。这个流程中你的后台服务器需要直接保管微信支付的商户密钥APIv3密钥或API密钥并直接与微信支付服务器通信。通过银联商务的微信小程序支付流程本项目小程序前端同样获取code并传给后台。后台用code向自己的服务器换取openid这一步不变因为openid是微信用户在当前小程序下的唯一标识银联商务也需要它来标识付款用户。关键变化点后台不再调用微信的统一下单接口而是组装订单数据调用银联商务的“小程序支付”或“统一下单”接口。这个接口的请求参数中会包含微信小程序的appid、用户的openid、订单信息以及最重要的——你在银联商务后台配置的商户号和签名密钥。银联商务服务器收到请求后会在其系统内生成一个它自己的订单号并代替你的后台去调用微信支付的统一下单接口拿到微信侧的prepay_id。银联商务将支付所需的参数一个类似package的字符串或一个完整的参数包返回给你的后台。你的后台将这些参数原样或稍作格式转换返回给小程序前端。小程序前端依然调用wx.requestPayment()传入这些参数调起支付。此时用户看到的界面和体验与标准流程完全一致。注意流程3-5是核心。你的后台不再接触微信支付的密钥而是使用银联商务分配的密钥进行通信。支付请求的发起方在逻辑上变成了银联商务。2.2 技术选型与准备工作后台语言以最常用的 Spring Boot (Java) 为例。其他语言如 Python (Django/Flask)、Node.js、Go 等流程完全一致只是 HTTP 客户端和签名库不同。你需要提前准备好的关键信息微信小程序方面小程序AppID小程序AppSecret(用于后端换openid)银联商务方面需在银联商务商户平台申请开通“微信小程序支付”能力商户号 (merId): 银联商务分配给你的唯一标识。前台通知地址 (frontUrl)支付完成后用户点击“完成”或“返回”时页面跳转的地址通常是小程序内的某个页面路径。后台通知地址 (backUrl)支付成功后银联商务服务器会主动发送一个 POST 请求到这个地址告诉你最终的支付结果。这是进行订单状态更新、发货等业务逻辑的唯一可靠依据必须为公网可访问的 URL。签名密钥这是安全的核心。银联商务通常使用 RSA 公私钥对或 MD5 密钥。本项目以更常见的RSA 私钥签名为例。你需要在银联商务平台生成一对 RSA 密钥将公钥上传私钥妥善保存在你的后台服务器上绝对不要泄露。接口网关地址银联商务提供的 API 入口 URL。3. 后台服务端核心实现详解后台是整个支付流程的调度中心。我们将其拆解为三个核心模块。3.1 用户身份获取与订单创建这一步与标准流程无异目的是获取到当前用户的openid并创建业务订单。// 示例AuthController.java RestController RequestMapping(/api/pay) public class PayController { Value(${wechat.appid}) private String appId; Value(${wechat.secret}) private String secret; /** * 1. 前端传入code后端换取openid并创建订单 */ PostMapping(/create) public ApiResponse createOrder(RequestParam String code, RequestBody OrderCreateDTO orderDTO) { // 1.1 用code换取openid String openId wechatAuthService.getOpenIdByCode(code); if (StringUtils.isEmpty(openId)) { return ApiResponse.error(获取用户标识失败); } // 1.2 创建你自己的业务订单存入数据库 String yourOrderNo YOUR_ORDER_ System.currentTimeMillis(); // 生成你自己的业务订单号 Order order new Order(); order.setOrderNo(yourOrderNo); order.setOpenId(openId); order.setAmount(orderDTO.getAmount()); // 单位分 order.setSubject(orderDTO.getSubject()); order.setStatus(OrderStatus.WAIT_PAY); orderService.save(order); // 1.3 调用银联商务接口获取支付参数 MapString, String payParams unionPayService.createMiniProgramOrder(order, openId); return ApiResponse.success(payParams); // 将支付参数返回给前端 } }3.2 银联商务接口封装与签名这是最核心的部分。我们需要构造符合银联商务要求的请求数据并生成数字签名。// 示例UnionPayServiceImpl.java Service Slf4j public class UnionPayServiceImpl implements UnionPayService { Value(${unionpay.merId}) private String merId; Value(${unionpay.gateway}) private String gateway; Value(${unionpay.frontUrl}) private String frontUrl; Value(${unionpay.backUrl}) private String backUrl; Value(${unionpay.privateKey}) private String privateKey; // RSA私钥字符串 Override public MapString, String createMiniProgramOrder(Order order, String openId) { // 1. 组装请求参数Map MapString, String requestData new TreeMap(); // 使用TreeMap保证参数按字母排序这对签名很重要 requestData.put(merId, merId); requestData.put(orderNo, order.getOrderNo()); // 传入你的业务订单号 requestData.put(orderAmount, String.valueOf(order.getAmount())); // 单位分 requestData.put(orderCurrency, CNY); requestData.put(orderTime, new SimpleDateFormat(yyyyMMddHHmmss).format(new Date())); requestData.put(payType, WX_APPLET); // 支付类型微信小程序 requestData.put(subAppId, appId); // 微信小程序AppID requestData.put(openId, openId); // 用户OpenID requestData.put(subject, order.getSubject()); requestData.put(frontUrl, frontUrl); requestData.put(backUrl, backUrl); // ... 其他可选参数如商品详情、附加数据等 // 2. 关键步骤生成签名 String sign generateSignature(requestData); requestData.put(signature, sign); // 将签名放入请求参数 requestData.put(signMethod, RSA); // 签名方法 // 3. 发送HTTP POST请求到银联商务网关 String response httpClient.postForm(gateway, requestData); MapString, String respMap parseResponse(response); // 4. 验证银联商务返回的签名重要 if (!verifySignature(respMap)) { log.error(银联商务返回签名验证失败响应数据{}, respMap); throw new RuntimeException(支付平台返回异常); } // 5. 解析响应获取前端支付所需参数 // 银联商务返回的格式可能与微信原生格式不同需要转换。 // 假设银联返回了一个 payInfo 字段里面是微信支付所需的参数包package String payInfo respMap.get(payInfo); MapString, String wxPayParams parseWxPayInfo(payInfo); // 6. 将参数返回给前端 return wxPayParams; // 格式应为{ timeStamp: ..., nonceStr: ..., package: ..., signType: RSA, paySign: ... } } /** * RSA签名生成方法 */ private String generateSignature(MapString, String data) throws Exception { // 1. 拼接签名字符串按“参数名参数值”的格式排除signature本身并拼接起来 StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : data.entrySet()) { String key entry.getKey(); String value entry.getValue(); if (value ! null !value.isEmpty() !signature.equals(key) !signMethod.equals(key)) { sb.append(key).append().append(value).append(); } } String signString sb.substring(0, sb.length() - 1); // 去掉最后一个 // 2. 使用SHA256WithRSA算法和你的私钥进行签名 Signature signature Signature.getInstance(SHA256WithRSA); PrivateKey priKey getPrivateKey(privateKey); // 将字符串私钥转换为PrivateKey对象 signature.initSign(priKey); signature.update(signString.getBytes(StandardCharsets.UTF_8)); byte[] signed signature.sign(); // 3. 将签名结果Base64编码 return Base64.getEncoder().encodeToString(signed); } }实操心得一签名与验签签名是支付安全的重中之重。务必严格按照银联商务的文档说明拼接参数字符串。常见的坑有1) 参数顺序不对必须按字母升序2) 空值参数是否参与拼接文档会说明3) 签名算法字符串编码必须是 UTF-8。每次对接新渠道先用测试订单和日志把签名生成和验证的流程跑通再谈业务逻辑。3.3 支付结果异步通知处理支付成功后银联商务会主动 POST 一个表单或 JSON 数据到你配置的backUrl。你必须正确处理并返回成功应答否则银联商务会认为通知失败进行多次重试。// 示例UnionPayNotifyController.java RestController RequestMapping(/notify) Slf4j public class UnionPayNotifyController { PostMapping(/unionpay) public String unionpayNotify(HttpServletRequest request) { // 1. 获取所有通知参数 MapString, String params new HashMap(); EnumerationString parameterNames request.getParameterNames(); while (parameterNames.hasMoreElements()) { String name parameterNames.nextElement(); params.put(name, request.getParameter(name)); } log.info(收到银联商务支付通知{}, params); // 2. 验证签名同上文verifySignature方法 if (!unionPayService.verifySignature(params)) { log.error(异步通知签名验证失败); return FAIL; // 返回FAIL银联商务会重发通知 } // 3. 校验订单状态和金额 String orderNo params.get(orderNo); // 这是你传给银联的订单号 String respAmount params.get(orderAmount); String respCode params.get(respCode); // 响应码如“00”表示成功 if (!00.equals(respCode)) { log.warn(订单{}支付未成功响应码{}, orderNo, respCode); // 更新你的订单状态为失败 orderService.updateStatus(orderNo, OrderStatus.PAY_FAILED); return SUCCESS; // 即使失败也要返回SUCCESS表示已成功接收通知 } // 4. 根据orderNo查询你自己的业务订单 Order order orderService.getByOrderNo(orderNo); if (order null) { log.error(通知中的订单号不存在{}, orderNo); return FAIL; } // 金额一致性校验防止数据篡改 if (order.getAmount() ! Long.parseLong(respAmount)) { log.error(订单{}金额不一致本地{}通知{}, orderNo, order.getAmount(), respAmount); return FAIL; } // 幂等性处理检查订单是否已处理过 if (order.getStatus() OrderStatus.PAID) { log.info(订单{}已支付跳过重复处理, orderNo); return SUCCESS; } // 5. 核心业务逻辑更新订单状态、记录支付信息、发货、增加用户权益等 boolean success orderService.processPaidOrder(orderNo, params); if (success) { log.info(订单{}支付成功业务处理完成, orderNo); // 6. 返回成功响应必须是纯文本的SUCCESS不能有空格或换行 return SUCCESS; } else { log.error(订单{}支付成功但业务处理失败, orderNo); // 业务处理失败可以返回FAIL让银联重试但需注意避免重复执行业务逻辑造成错误如重复发货。 // 更稳妥的做法是返回SUCCESS但记录错误日志并启动人工或自动补偿任务。 return SUCCESS; } } }实操心得二异步通知的“坑”1)必须做签名验证这是防止伪造通知的唯一手段。2)必须做金额校验防止订单金额被恶意篡改。3)必须实现幂等性因为网络问题可能导致银联商务重复发送通知。你的业务逻辑要能判断“这个订单是否已经处理过”。4)响应必须快速且准确通常在3秒内返回SUCCESS或FAIL的纯文本超时或返回格式错误会被视为通知失败。5)业务逻辑与通知处理解耦不要在通知接口里写冗长的业务代码如发邮件、调用外部API应该只更新状态然后通过消息队列等方式触发后续业务避免接口超时。4. 微信小程序前端调用支付前端的工作相对简单但细节决定成败。// 示例pages/pay/pay.js Page({ data: { orderId: , amount: 0 }, onLoad(options) { // 从上一页或通过options获取订单信息 this.setData({ orderId: options.orderId }); }, // 发起支付 async handlePayment() { const that this; // 1. 获取用户登录code wx.login({ success: async (loginRes) { if (loginRes.code) { // 2. 调用自己的后端接口传入code和订单信息获取支付参数 wx.request({ url: https://your-domain.com/api/pay/create, method: POST, data: { code: loginRes.code, orderId: that.data.orderId }, success: async (res) { if (res.data.code 200) { const payParams res.data.data; // 后端返回的支付参数包 // 3. 调用微信支付API wx.requestPayment({ timeStamp: payParams.timeStamp, nonceStr: payParams.nonceStr, package: payParams.package, // 注意参数名是package是关键字后端返回时可能需要别名如packageStr signType: payParams.signType, paySign: payParams.paySign, success: (payRes) { // 支付成功前端提示 wx.showToast({ title: 支付成功, icon: success }); // 跳转到成功页面 setTimeout(() { wx.redirectTo({ url: /pages/order/success?id that.data.orderId }); }, 1500); }, fail: (err) { console.error(支付失败, err); // 支付失败处理用户取消支付也走这里 if (err.errCode -2) { wx.showToast({ title: 用户取消支付, icon: none }); } else { wx.showToast({ title: 支付失败请重试, icon: none }); } } }); } else { wx.showToast({ title: 创建支付失败 res.data.msg, icon: none }); } }, fail: (err) { wx.showToast({ title: 网络请求失败, icon: none }); } }); } else { wx.showToast({ title: 登录失败, icon: none }); } } }); } })实操心得三前端支付调起的细节1)wx.requestPayment的package参数是个关键字在JavaScript中不能直接使用。如果你的后端返回的字段名就是package在接收时可能需要特殊处理如解构赋值。更常见的做法是后端返回时改用packageStr等别名前端再对应赋值给package。2) 支付成功后的前端跳转 (frontUrl) 是用户点击“完成”按钮后的行为不能作为支付成功的依据。用户可能不点完成直接切出小程序。订单状态的唯一依据是后台的异步通知 (backUrl)。3) 做好加载状态和错误提示提升用户体验。5. 环境配置、联调与上线 checklist5.1 关键配置项核对表在开发、测试、生产环境切换时务必检查以下配置环境微信小程序appid银联商务merId后台通知地址backUrl签名密钥接口网关开发/测试测试号或正式号的开发配置银联商务测试商户号https://dev.your.com/notify/unionpay(需内网穿透如ngrok)测试环境密钥测试环境网关生产环境正式小程序appid正式生产商户号https://api.your.com/notify/unionpay(必须HTTPS)生产环境密钥生产环境网关5.2 联调测试全流程准备测试工具内网穿透工具确保你的本地开发环境能被银联商务服务器访问到用于接收异步通知。推荐使用ngrok或natapp。日志系统在关键节点如接收通知、签名验证、业务处理打印详细日志方便排查。API测试工具如 Postman用于手动模拟银联商务的异步通知测试你的backUrl接口是否健壮。测试步骤步骤A正向流程在小程序测试环境完成一次完整的支付使用1分钱测试金额。观察a) 后端日志是否成功收到code并换到openidb) 调用银联商务接口是否成功并返回支付参数c) 前端是否能成功调起支付d) 支付成功后你的backUrl是否收到通知并正确处理订单。步骤B通知模拟用 Postman 构造一个模拟的银联商务通知请求直接发向你的backUrl。测试签名错误、金额不一致、重复通知等异常情况确保你的接口都能正确响应 (SUCCESS/FAIL) 并做好日志记录。步骤C对账在测试环境每天从银联商务后台下载对账单与你自己数据库的订单记录进行比对确保金额、状态、数量完全一致。这个习惯能提前发现很多隐藏的bug。5.3 常见问题排查实录问题1前端调用wx.requestPayment失败报错requestPayment:fail。排查思路参数格式错误检查后端返回给前端的五个参数 (timeStamp,nonceStr,package,signType,paySign) 是否齐全、类型是否为字符串。timeStamp必须是字符串格式的数字。签名错误这是最常见的原因。检查paySign的生成方式。通过银联商务中转时这个paySign可能是银联商务用它的私钥签的也可能是它返回了微信原生格式的参数让你自己签。必须严格按照接口文档说明处理。可以先将后端返回的参数打印到小程序控制台与一个正常的微信支付请求参数对比。package值错误package的值格式应为prepay_idwx261620...。检查这个值是否有效且未过期。小程序权限确认当前小程序是否已关联了正确的微信支付商户号虽然走了银联商务但最终支付账户还是你的微信支付商户号。在小程序后台的“微信支付”栏位查看。问题2支付成功后收不到银联商务的异步通知 (backUrl没被调用)。排查思路网络不通检查你的backUrl是否公网可访问且没有防火墙拦截。使用curl或浏览器直接访问该 URL 测试。通知地址错误检查在调用银联商务下单接口时传入的backUrl参数是否正确无误。银联商务端配置登录银联商务商户平台检查“通知地址”配置是否有误或未生效。支付未真正成功用户输入密码后可能因为余额不足等原因支付最终失败。以异步通知为准前端成功回调不可信。通知延迟有时会有几分钟的延迟属于正常现象。可以登录银联商务后台查看该笔订单的状态。问题3收到异步通知但签名验证失败。排查思路签名方法不一致检查通知参数中的signMethod字段确认与你使用的签名算法如RSA是否一致。参与签名的参数不一致仔细阅读银联商务文档确认通知参数中哪些参数需要参与签名空值参数如何处理。自己拼接签名字符串的逻辑必须与文档完全一致。密钥错误确认你用于验签的公钥是否是银联商务平台提供的、与当前环境测试/生产匹配的正确公钥。参数编码问题确保拼接签名字符串和验签时的字符串编码都是 UTF-8。问题4支付成功后用户点击“完成”按钮没有跳转到预期的frontUrl页面。排查思路页面路径错误frontUrl需要是小程序内的合法路径如/pages/order/success且不能带.html后缀。页面未发布如果跳转的页面仅在开发版本中存在体验版或正式版用户可能无法访问。请确保该页面已包含在提交审核的代码包中。支付完成后的小程序生命周期支付完成后小程序可能被销毁。在frontUrl对应的页面onLoad函数里可以从options中获取订单号等参数并主动去后台查询一次支付状态以确保页面显示正确。整个对接过程本质上是一个“信任转移”的过程小程序信任你的后台你的后台信任银联商务银联商务信任微信支付。每一层通信的签名、验签和状态确认都是构建这个信任链条的基石。把上述流程走通特别是把异步通知和异常处理做扎实一个稳定可靠的、基于银联商务的微信小程序支付功能就搭建完成了。这套方案的扩展性很好未来如果需要增加支付宝小程序支付、H5支付等只需要在银联商务侧配置新的支付类型后台的对接模式几乎可以复用。
1. 项目概述为什么选择银联商务作为微信小程序的支付通道在微信小程序的生态里支付功能几乎是商业类应用的标配。一提到小程序支付大家的第一反应往往是“微信支付”。这没错微信支付确实是官方原生的、最直接的方案。但在我经手的多个项目中尤其是涉及多商户、分账、对账复杂或者需要对接特定银行渠道的场景直接使用微信支付的原生接口有时会显得“不够用”或者“太麻烦”。这时候像银联商务这样的第三方支付服务商就提供了一个非常值得考虑的备选方案。简单来说银联商务是一个拥有全牌照的综合性支付服务机构它就像一个“支付中台”背后聚合了包括微信支付、支付宝、银联云闪付、各大银行网关在内的多种支付渠道。当我们的小程序通过银联商务的接口发起支付时用户在前端看到的依然是熟悉的微信支付收银台体验上几乎无感。但对于我们开发者尤其是后台开发者而言整个对接逻辑、订单管理和资金结算的流程都变成了与银联商务的单一接口进行交互。这样做最直接的好处是统一化和专业化你只需要对接一套API就能获得微信支付的能力同时还能享受银联商务在风控、对账、分账、大额交易等方面的增值服务。特别适合那些本身业务系统已经与银联商务有合作或者未来有拓展多支付渠道计划的项目。所以这个项目的核心就是在微信小程序的前端框架下绕开微信支付的原生SDK通过调用银联商务提供的API实现从下单、调起支付到支付结果通知的完整闭环。这不仅仅是换一个接口调用那么简单它涉及到支付流程的重新设计、参数传递方式的变化以及安全策略的调整。接下来我会把整个实现过程拆解清楚包括设计思路、具体步骤和那些官方文档里不会写的“坑”。2. 核心流程设计与银联商务通道解析在动手写代码之前我们必须把两个支付流程的差异理解透彻。这是决定项目成败的关键。2.1 标准微信支付流程 vs. 银联商务中转流程标准微信小程序支付流程官方小程序前端调用wx.login()获取用户临时凭证code传给后台。后台用code、小程序appid和secret调用微信接口换取用户的openid。后台用openid、商户号、订单信息等参数调用微信支付统一下单接口获得一个prepay_id预支付交易会话标识。后台再根据prepay_id生成支付所需的签名参数包包括timeStamp,nonceStr,package,signType,paySign返回给小程序前端。小程序前端调用wx.requestPayment()传入这个参数包即可调起微信支付。这个流程中你的后台服务器需要直接保管微信支付的商户密钥APIv3密钥或API密钥并直接与微信支付服务器通信。通过银联商务的微信小程序支付流程本项目小程序前端同样获取code并传给后台。后台用code向自己的服务器换取openid这一步不变因为openid是微信用户在当前小程序下的唯一标识银联商务也需要它来标识付款用户。关键变化点后台不再调用微信的统一下单接口而是组装订单数据调用银联商务的“小程序支付”或“统一下单”接口。这个接口的请求参数中会包含微信小程序的appid、用户的openid、订单信息以及最重要的——你在银联商务后台配置的商户号和签名密钥。银联商务服务器收到请求后会在其系统内生成一个它自己的订单号并代替你的后台去调用微信支付的统一下单接口拿到微信侧的prepay_id。银联商务将支付所需的参数一个类似package的字符串或一个完整的参数包返回给你的后台。你的后台将这些参数原样或稍作格式转换返回给小程序前端。小程序前端依然调用wx.requestPayment()传入这些参数调起支付。此时用户看到的界面和体验与标准流程完全一致。注意流程3-5是核心。你的后台不再接触微信支付的密钥而是使用银联商务分配的密钥进行通信。支付请求的发起方在逻辑上变成了银联商务。2.2 技术选型与准备工作后台语言以最常用的 Spring Boot (Java) 为例。其他语言如 Python (Django/Flask)、Node.js、Go 等流程完全一致只是 HTTP 客户端和签名库不同。你需要提前准备好的关键信息微信小程序方面小程序AppID小程序AppSecret(用于后端换openid)银联商务方面需在银联商务商户平台申请开通“微信小程序支付”能力商户号 (merId): 银联商务分配给你的唯一标识。前台通知地址 (frontUrl)支付完成后用户点击“完成”或“返回”时页面跳转的地址通常是小程序内的某个页面路径。后台通知地址 (backUrl)支付成功后银联商务服务器会主动发送一个 POST 请求到这个地址告诉你最终的支付结果。这是进行订单状态更新、发货等业务逻辑的唯一可靠依据必须为公网可访问的 URL。签名密钥这是安全的核心。银联商务通常使用 RSA 公私钥对或 MD5 密钥。本项目以更常见的RSA 私钥签名为例。你需要在银联商务平台生成一对 RSA 密钥将公钥上传私钥妥善保存在你的后台服务器上绝对不要泄露。接口网关地址银联商务提供的 API 入口 URL。3. 后台服务端核心实现详解后台是整个支付流程的调度中心。我们将其拆解为三个核心模块。3.1 用户身份获取与订单创建这一步与标准流程无异目的是获取到当前用户的openid并创建业务订单。// 示例AuthController.java RestController RequestMapping(/api/pay) public class PayController { Value(${wechat.appid}) private String appId; Value(${wechat.secret}) private String secret; /** * 1. 前端传入code后端换取openid并创建订单 */ PostMapping(/create) public ApiResponse createOrder(RequestParam String code, RequestBody OrderCreateDTO orderDTO) { // 1.1 用code换取openid String openId wechatAuthService.getOpenIdByCode(code); if (StringUtils.isEmpty(openId)) { return ApiResponse.error(获取用户标识失败); } // 1.2 创建你自己的业务订单存入数据库 String yourOrderNo YOUR_ORDER_ System.currentTimeMillis(); // 生成你自己的业务订单号 Order order new Order(); order.setOrderNo(yourOrderNo); order.setOpenId(openId); order.setAmount(orderDTO.getAmount()); // 单位分 order.setSubject(orderDTO.getSubject()); order.setStatus(OrderStatus.WAIT_PAY); orderService.save(order); // 1.3 调用银联商务接口获取支付参数 MapString, String payParams unionPayService.createMiniProgramOrder(order, openId); return ApiResponse.success(payParams); // 将支付参数返回给前端 } }3.2 银联商务接口封装与签名这是最核心的部分。我们需要构造符合银联商务要求的请求数据并生成数字签名。// 示例UnionPayServiceImpl.java Service Slf4j public class UnionPayServiceImpl implements UnionPayService { Value(${unionpay.merId}) private String merId; Value(${unionpay.gateway}) private String gateway; Value(${unionpay.frontUrl}) private String frontUrl; Value(${unionpay.backUrl}) private String backUrl; Value(${unionpay.privateKey}) private String privateKey; // RSA私钥字符串 Override public MapString, String createMiniProgramOrder(Order order, String openId) { // 1. 组装请求参数Map MapString, String requestData new TreeMap(); // 使用TreeMap保证参数按字母排序这对签名很重要 requestData.put(merId, merId); requestData.put(orderNo, order.getOrderNo()); // 传入你的业务订单号 requestData.put(orderAmount, String.valueOf(order.getAmount())); // 单位分 requestData.put(orderCurrency, CNY); requestData.put(orderTime, new SimpleDateFormat(yyyyMMddHHmmss).format(new Date())); requestData.put(payType, WX_APPLET); // 支付类型微信小程序 requestData.put(subAppId, appId); // 微信小程序AppID requestData.put(openId, openId); // 用户OpenID requestData.put(subject, order.getSubject()); requestData.put(frontUrl, frontUrl); requestData.put(backUrl, backUrl); // ... 其他可选参数如商品详情、附加数据等 // 2. 关键步骤生成签名 String sign generateSignature(requestData); requestData.put(signature, sign); // 将签名放入请求参数 requestData.put(signMethod, RSA); // 签名方法 // 3. 发送HTTP POST请求到银联商务网关 String response httpClient.postForm(gateway, requestData); MapString, String respMap parseResponse(response); // 4. 验证银联商务返回的签名重要 if (!verifySignature(respMap)) { log.error(银联商务返回签名验证失败响应数据{}, respMap); throw new RuntimeException(支付平台返回异常); } // 5. 解析响应获取前端支付所需参数 // 银联商务返回的格式可能与微信原生格式不同需要转换。 // 假设银联返回了一个 payInfo 字段里面是微信支付所需的参数包package String payInfo respMap.get(payInfo); MapString, String wxPayParams parseWxPayInfo(payInfo); // 6. 将参数返回给前端 return wxPayParams; // 格式应为{ timeStamp: ..., nonceStr: ..., package: ..., signType: RSA, paySign: ... } } /** * RSA签名生成方法 */ private String generateSignature(MapString, String data) throws Exception { // 1. 拼接签名字符串按“参数名参数值”的格式排除signature本身并拼接起来 StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : data.entrySet()) { String key entry.getKey(); String value entry.getValue(); if (value ! null !value.isEmpty() !signature.equals(key) !signMethod.equals(key)) { sb.append(key).append().append(value).append(); } } String signString sb.substring(0, sb.length() - 1); // 去掉最后一个 // 2. 使用SHA256WithRSA算法和你的私钥进行签名 Signature signature Signature.getInstance(SHA256WithRSA); PrivateKey priKey getPrivateKey(privateKey); // 将字符串私钥转换为PrivateKey对象 signature.initSign(priKey); signature.update(signString.getBytes(StandardCharsets.UTF_8)); byte[] signed signature.sign(); // 3. 将签名结果Base64编码 return Base64.getEncoder().encodeToString(signed); } }实操心得一签名与验签签名是支付安全的重中之重。务必严格按照银联商务的文档说明拼接参数字符串。常见的坑有1) 参数顺序不对必须按字母升序2) 空值参数是否参与拼接文档会说明3) 签名算法字符串编码必须是 UTF-8。每次对接新渠道先用测试订单和日志把签名生成和验证的流程跑通再谈业务逻辑。3.3 支付结果异步通知处理支付成功后银联商务会主动 POST 一个表单或 JSON 数据到你配置的backUrl。你必须正确处理并返回成功应答否则银联商务会认为通知失败进行多次重试。// 示例UnionPayNotifyController.java RestController RequestMapping(/notify) Slf4j public class UnionPayNotifyController { PostMapping(/unionpay) public String unionpayNotify(HttpServletRequest request) { // 1. 获取所有通知参数 MapString, String params new HashMap(); EnumerationString parameterNames request.getParameterNames(); while (parameterNames.hasMoreElements()) { String name parameterNames.nextElement(); params.put(name, request.getParameter(name)); } log.info(收到银联商务支付通知{}, params); // 2. 验证签名同上文verifySignature方法 if (!unionPayService.verifySignature(params)) { log.error(异步通知签名验证失败); return FAIL; // 返回FAIL银联商务会重发通知 } // 3. 校验订单状态和金额 String orderNo params.get(orderNo); // 这是你传给银联的订单号 String respAmount params.get(orderAmount); String respCode params.get(respCode); // 响应码如“00”表示成功 if (!00.equals(respCode)) { log.warn(订单{}支付未成功响应码{}, orderNo, respCode); // 更新你的订单状态为失败 orderService.updateStatus(orderNo, OrderStatus.PAY_FAILED); return SUCCESS; // 即使失败也要返回SUCCESS表示已成功接收通知 } // 4. 根据orderNo查询你自己的业务订单 Order order orderService.getByOrderNo(orderNo); if (order null) { log.error(通知中的订单号不存在{}, orderNo); return FAIL; } // 金额一致性校验防止数据篡改 if (order.getAmount() ! Long.parseLong(respAmount)) { log.error(订单{}金额不一致本地{}通知{}, orderNo, order.getAmount(), respAmount); return FAIL; } // 幂等性处理检查订单是否已处理过 if (order.getStatus() OrderStatus.PAID) { log.info(订单{}已支付跳过重复处理, orderNo); return SUCCESS; } // 5. 核心业务逻辑更新订单状态、记录支付信息、发货、增加用户权益等 boolean success orderService.processPaidOrder(orderNo, params); if (success) { log.info(订单{}支付成功业务处理完成, orderNo); // 6. 返回成功响应必须是纯文本的SUCCESS不能有空格或换行 return SUCCESS; } else { log.error(订单{}支付成功但业务处理失败, orderNo); // 业务处理失败可以返回FAIL让银联重试但需注意避免重复执行业务逻辑造成错误如重复发货。 // 更稳妥的做法是返回SUCCESS但记录错误日志并启动人工或自动补偿任务。 return SUCCESS; } } }实操心得二异步通知的“坑”1)必须做签名验证这是防止伪造通知的唯一手段。2)必须做金额校验防止订单金额被恶意篡改。3)必须实现幂等性因为网络问题可能导致银联商务重复发送通知。你的业务逻辑要能判断“这个订单是否已经处理过”。4)响应必须快速且准确通常在3秒内返回SUCCESS或FAIL的纯文本超时或返回格式错误会被视为通知失败。5)业务逻辑与通知处理解耦不要在通知接口里写冗长的业务代码如发邮件、调用外部API应该只更新状态然后通过消息队列等方式触发后续业务避免接口超时。4. 微信小程序前端调用支付前端的工作相对简单但细节决定成败。// 示例pages/pay/pay.js Page({ data: { orderId: , amount: 0 }, onLoad(options) { // 从上一页或通过options获取订单信息 this.setData({ orderId: options.orderId }); }, // 发起支付 async handlePayment() { const that this; // 1. 获取用户登录code wx.login({ success: async (loginRes) { if (loginRes.code) { // 2. 调用自己的后端接口传入code和订单信息获取支付参数 wx.request({ url: https://your-domain.com/api/pay/create, method: POST, data: { code: loginRes.code, orderId: that.data.orderId }, success: async (res) { if (res.data.code 200) { const payParams res.data.data; // 后端返回的支付参数包 // 3. 调用微信支付API wx.requestPayment({ timeStamp: payParams.timeStamp, nonceStr: payParams.nonceStr, package: payParams.package, // 注意参数名是package是关键字后端返回时可能需要别名如packageStr signType: payParams.signType, paySign: payParams.paySign, success: (payRes) { // 支付成功前端提示 wx.showToast({ title: 支付成功, icon: success }); // 跳转到成功页面 setTimeout(() { wx.redirectTo({ url: /pages/order/success?id that.data.orderId }); }, 1500); }, fail: (err) { console.error(支付失败, err); // 支付失败处理用户取消支付也走这里 if (err.errCode -2) { wx.showToast({ title: 用户取消支付, icon: none }); } else { wx.showToast({ title: 支付失败请重试, icon: none }); } } }); } else { wx.showToast({ title: 创建支付失败 res.data.msg, icon: none }); } }, fail: (err) { wx.showToast({ title: 网络请求失败, icon: none }); } }); } else { wx.showToast({ title: 登录失败, icon: none }); } } }); } })实操心得三前端支付调起的细节1)wx.requestPayment的package参数是个关键字在JavaScript中不能直接使用。如果你的后端返回的字段名就是package在接收时可能需要特殊处理如解构赋值。更常见的做法是后端返回时改用packageStr等别名前端再对应赋值给package。2) 支付成功后的前端跳转 (frontUrl) 是用户点击“完成”按钮后的行为不能作为支付成功的依据。用户可能不点完成直接切出小程序。订单状态的唯一依据是后台的异步通知 (backUrl)。3) 做好加载状态和错误提示提升用户体验。5. 环境配置、联调与上线 checklist5.1 关键配置项核对表在开发、测试、生产环境切换时务必检查以下配置环境微信小程序appid银联商务merId后台通知地址backUrl签名密钥接口网关开发/测试测试号或正式号的开发配置银联商务测试商户号https://dev.your.com/notify/unionpay(需内网穿透如ngrok)测试环境密钥测试环境网关生产环境正式小程序appid正式生产商户号https://api.your.com/notify/unionpay(必须HTTPS)生产环境密钥生产环境网关5.2 联调测试全流程准备测试工具内网穿透工具确保你的本地开发环境能被银联商务服务器访问到用于接收异步通知。推荐使用ngrok或natapp。日志系统在关键节点如接收通知、签名验证、业务处理打印详细日志方便排查。API测试工具如 Postman用于手动模拟银联商务的异步通知测试你的backUrl接口是否健壮。测试步骤步骤A正向流程在小程序测试环境完成一次完整的支付使用1分钱测试金额。观察a) 后端日志是否成功收到code并换到openidb) 调用银联商务接口是否成功并返回支付参数c) 前端是否能成功调起支付d) 支付成功后你的backUrl是否收到通知并正确处理订单。步骤B通知模拟用 Postman 构造一个模拟的银联商务通知请求直接发向你的backUrl。测试签名错误、金额不一致、重复通知等异常情况确保你的接口都能正确响应 (SUCCESS/FAIL) 并做好日志记录。步骤C对账在测试环境每天从银联商务后台下载对账单与你自己数据库的订单记录进行比对确保金额、状态、数量完全一致。这个习惯能提前发现很多隐藏的bug。5.3 常见问题排查实录问题1前端调用wx.requestPayment失败报错requestPayment:fail。排查思路参数格式错误检查后端返回给前端的五个参数 (timeStamp,nonceStr,package,signType,paySign) 是否齐全、类型是否为字符串。timeStamp必须是字符串格式的数字。签名错误这是最常见的原因。检查paySign的生成方式。通过银联商务中转时这个paySign可能是银联商务用它的私钥签的也可能是它返回了微信原生格式的参数让你自己签。必须严格按照接口文档说明处理。可以先将后端返回的参数打印到小程序控制台与一个正常的微信支付请求参数对比。package值错误package的值格式应为prepay_idwx261620...。检查这个值是否有效且未过期。小程序权限确认当前小程序是否已关联了正确的微信支付商户号虽然走了银联商务但最终支付账户还是你的微信支付商户号。在小程序后台的“微信支付”栏位查看。问题2支付成功后收不到银联商务的异步通知 (backUrl没被调用)。排查思路网络不通检查你的backUrl是否公网可访问且没有防火墙拦截。使用curl或浏览器直接访问该 URL 测试。通知地址错误检查在调用银联商务下单接口时传入的backUrl参数是否正确无误。银联商务端配置登录银联商务商户平台检查“通知地址”配置是否有误或未生效。支付未真正成功用户输入密码后可能因为余额不足等原因支付最终失败。以异步通知为准前端成功回调不可信。通知延迟有时会有几分钟的延迟属于正常现象。可以登录银联商务后台查看该笔订单的状态。问题3收到异步通知但签名验证失败。排查思路签名方法不一致检查通知参数中的signMethod字段确认与你使用的签名算法如RSA是否一致。参与签名的参数不一致仔细阅读银联商务文档确认通知参数中哪些参数需要参与签名空值参数如何处理。自己拼接签名字符串的逻辑必须与文档完全一致。密钥错误确认你用于验签的公钥是否是银联商务平台提供的、与当前环境测试/生产匹配的正确公钥。参数编码问题确保拼接签名字符串和验签时的字符串编码都是 UTF-8。问题4支付成功后用户点击“完成”按钮没有跳转到预期的frontUrl页面。排查思路页面路径错误frontUrl需要是小程序内的合法路径如/pages/order/success且不能带.html后缀。页面未发布如果跳转的页面仅在开发版本中存在体验版或正式版用户可能无法访问。请确保该页面已包含在提交审核的代码包中。支付完成后的小程序生命周期支付完成后小程序可能被销毁。在frontUrl对应的页面onLoad函数里可以从options中获取订单号等参数并主动去后台查询一次支付状态以确保页面显示正确。整个对接过程本质上是一个“信任转移”的过程小程序信任你的后台你的后台信任银联商务银联商务信任微信支付。每一层通信的签名、验签和状态确认都是构建这个信任链条的基石。把上述流程走通特别是把异步通知和异常处理做扎实一个稳定可靠的、基于银联商务的微信小程序支付功能就搭建完成了。这套方案的扩展性很好未来如果需要增加支付宝小程序支付、H5支付等只需要在银联商务侧配置新的支付类型后台的对接模式几乎可以复用。
条款深度解析与合规实践)
