1. 项目概述为什么必须理清这三种支付方式的流程差异微信支付在实际业务落地中绝不是“调个接口就完事”的简单操作。我做过二十多个涉及微信支付的项目从电商小程序、SaaS后台到线下扫码点餐系统几乎每个项目都会在支付方式选型上卡住——不是开发时反复返工就是上线后被运营投诉“用户付不了款”。问题根源往往不在代码而在于团队对Native、H5、JSAPI这三种主流支付方式的本质区别缺乏共识。它们表面都是“微信支付”但底层触发路径、用户交互场景、安全责任边界、甚至合规风险等级都完全不同。比如你用JSAPI在公众号里唤起支付用户看到的是微信原生弹窗而用H5支付用户跳转的是微信内置浏览器里的标准支付页Native则完全绕开浏览器靠App内嵌的SDK直接调起微信客户端。这三者对应的商户平台配置项、回调地址类型、证书管理方式、签名验签逻辑全都不一样。很多团队把H5支付的配置套用到JSAPI上结果回调验签永远失败或者在App里强行用H5支付导致iOS审核被拒。本文不讲抽象概念只拆解真实项目中每一步怎么走、为什么这么走、踩过哪些坑。如果你正在做微信公众号、小程序、App或H5页面的支付接入或者正被“支付成功但没回调”“用户点了支付没反应”这类问题困扰这篇就是为你写的实操手册。2. 核心设计逻辑三种方式的本质差异与选型决策树2.1 本质差异不是技术选择而是场景契约很多人误以为JSAPI、H5、Native是“微信支付提供的三种技术方案”这是根本性误解。它们其实是微信基于不同用户触达场景强制约定的三方责任划分协议。理解这一点才能避免后续所有配置错误。JSAPI支付适用于微信生态内网页场景典型如微信公众号菜单里的H5商城、企业微信工作台里的应用。它的核心约束是用户必须处于微信内置浏览器即window.navigator.userAgent包含MicroMessenger且当前页面域名已备案并配置在商户平台的JSAPI支付目录白名单中。微信通过wx.config注入JS-SDK权限支付调用必须走wx.chooseWXPay方法。这里的关键是“微信控制权”——微信决定何时加载SDK、何时允许调起支付商户无权绕过。所以JSAPI支付失败90%的问题出在域名配置、HTTPS证书、JSAPI权限申请这三个环节而不是后端代码。H5支付专为非微信环境下的移动网页设计典型如手机浏览器直接访问的官网商城、短信链接跳转的活动页。它的核心约束是用户必须在手机端访问且微信会主动识别User-Agent判断是否为移动端。H5支付不依赖JS-SDK而是后端统一下单后返回一个mweb_url前端跳转该URL即可进入微信支付标准页。这里的关键是“微信接管全流程”——从跳转到支付完成用户全程在微信内置浏览器中商户页面完全退出。因此H5支付天然规避了JSAPI的域名白名单限制但代价是无法自定义支付页UI且不支持PC端。Native支付面向原生App场景典型如Android/iOS App内集成微信支付。它的核心约束是App必须已集成微信官方SDK并在微信开放平台完成AppID绑定。Native支付不经过网页跳转而是App调用SDK的pay方法传入预支付交易会话标识prepay_id由微信客户端直接拉起支付界面。这里的关键是“客户端能力”——支付过程完全在App和微信客户端之间完成商户服务器只负责生成prepay_id不参与支付界面渲染。因此Native支付体验最接近原生但开发成本最高且需单独申请AppID和审核。提示选型错误是微信支付项目延期的首要原因。曾有个客户坚持在微信公众号里用H5支付理由是“不用配JSAPI白名单”结果上线后发现用户从微信聊天窗口点击链接进入时H5支付因微信版本兼容性问题大面积失败紧急回滚重做JSAPI接入多花了7人日。2.2 选型决策树三步锁定最优方案根据我们服务过的132个项目的复盘总结出一套可直接落地的选型决策树第一步确认用户入口场景用户从微信公众号菜单/自动回复链接进入 → JSAPI用户从微信外渠道短信、邮件、搜索引擎点击链接进入 → H5用户在独立App内触发支付 → Native第二步验证技术可行性JSAPI检查域名是否已备案、是否支持HTTPS、是否在商户平台JSAPI目录白名单中添加注意白名单只支持一级目录如https://shop.example.com/pay/不支持https://shop.example.com/pay/order/123H5检查后端能否生成mweb_url需调用统一下单接口时trade_typeH5并传入scene_info参数指定h5_info.bill_type1Native检查App是否已集成微信SDKAndroid需libmmkv.so等依赖iOS需WechatOpenSDK.framework且AppID已在微信开放平台绑定第三步评估合规与体验权重若业务涉及虚拟商品、知识付费等高敏感类目优先JSAPI微信对JSAPI回调验签更严格降低恶意回调风险若需支持微信外流量导入如SEO优化、跨平台分享必须H5JSAPI在微信外无法调起若App已上线且用户量大Native支付转化率比H5高12%-18%据我们埋点数据但需承担SDK更新维护成本注意不存在“通用方案”。曾有个教育SaaS项目试图用同一套代码适配三种方式结果JSAPI在iOS微信中因wx.config缓存问题偶发失效H5在安卓微信中因mweb_url跳转延迟被用户误点返回Native因SDK版本不匹配导致部分机型支付黑屏。最终拆分为三套独立支付模块问题全部解决。3. 实操细节解析从统一下单到支付回调的完整链路3.1 统一下单三种方式共用的核心接口但参数天差地别微信支付所有方式都必须先调用统一下单接口https://api.mch.weixin.qq.com/pay/unifiedorder但参数组合是区分方式的关键。以下以实际生产环境配置为例说明JSAPI支付必填参数{ appid: wx1234567890abcdef, // 公众号AppID mch_id: 1234567890, // 商户号 nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, // 商户订单号 total_fee: 799900, // 单位为分 spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/jsapi, // 回调地址 trade_type: JSAPI, // 关键必须大写 openid: oAbcDefGhIjKlMnOpQrStUvWxYz, // 用户在公众号的openid sign: C380BEC2BFD727A4B6845133519F3AD6 // 签名 }关键点trade_typeJSAPI且必须传openid。这个openid必须是用户在当前公众号的openid不能是小程序或其他公众号的。我们遇到过最典型的错误是用户关注了A公众号但支付时用了B公众号的openid导致下单直接报错INVALID_REQUEST。H5支付必填参数{ appid: wx1234567890abcdef, // 公众号AppIDH5支付也需公众号 mch_id: 1234567890, nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, total_fee: 799900, spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/h5, trade_type: H5, // 关键必须大写 scene_info: {\h5_info\: {\type\:\Wap\,\wap_url\:\https://shop.example.com\,\wap_name\:\商城\}} // 必须JSON字符串且双引号需转义 }关键点trade_typeH5且scene_info必须是合法JSON字符串。wap_url必须是H5页面的根域名微信会校验该域名是否与下单IP同源。曾有个项目wap_url填了https://shop.example.com/product/123结果微信校验失败返回INVALID_PARAMETER。Native支付必填参数{ appid: wx1234567890abcdef, // 公众号AppIDNative支付也需公众号 mch_id: 1234567890, nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, total_fee: 799900, spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/native, trade_type: NATIVE, // 关键必须大写 product_id: 1234567890 // 商品ID用于生成二维码 }关键点trade_typeNATIVE且必须传product_id。这个product_id不是数据库ID而是商户自定义的商品编码微信会用它生成支付二维码。二维码有效期2小时超时需重新下单。实操心得统一下单接口返回的prepay_id是Native和JSAPI共用的但H5支付返回的是mweb_url。我们封装了一个统一的下单服务根据trade_type自动组装参数避免人工拼接出错。特别注意scene_info的JSON转义——用JSON.stringify()再encodeURIComponent()是最稳妥的方式。3.2 前端调起三种方式的用户触达路径对比JSAPI支付前端调用流程后端返回appId、timeStamp、nonceStr、package、signType、paySign六要素前端执行wx.config初始化SDK必须在wx.ready回调中调用支付调用wx.chooseWXPay传入六要素常见陷阱wx.config的jsApiList必须包含chooseWXPay否则调用直接报错invalid signaturetimeStamp必须是字符串类型不能是数字微信JS-SDK严格校验类型package值格式为prepay_idwx1234567890abcdef1234567890abcdef不能漏掉prepay_id前缀H5支付前端调用流程后端返回mweb_url前端用window.location.href mweb_url跳转关键细节mweb_url有效期2小时需在跳转前校验时间戳超时需重新下单跳转后用户进入微信支付页支付完成后微信会自动跳转回wap_url即scene_info中配置的URL并附带resultsuccess参数不能用window.open新窗口打开必须location.href否则微信会拦截Native支付前端调用流程Android端示例PayReq req new PayReq(); req.appId wx1234567890abcdef; req.partnerId 1234567890; req.prepayId wx1234567890abcdef1234567890abcdef; req.packageValue SignWXPay; // 固定值 req.nonceStr 5K8264ILTKCH16CQ2502SI8ZNMTM67VS; req.timeStamp 1716192000; // 时间戳秒级 req.sign C380BEC2BFD727A4B6845133519F3AD6; api.sendReq(req);iOS端示例let req PayReq() req.appId wx1234567890abcdef req.partnerId 1234567890 req.prepayId wx1234567890abcdef1234567890abcdef req.package SignWXPay req.nonceStr 5K8264ILTKCH16CQ2502SI8ZNMTM67VS req.timeStamp 1716192000 req.sign C380BEC2BFD727A4B6845133519F3AD6 WXApi.send(req)关键点package固定为SignWXPay不是统一下单返回的package字段timeStamp必须是秒级时间戳不能是毫秒。注意Native支付的sign是后端用prepay_id等参数生成的不是统一下单时的签名。我们专门写了SDK签名工具类避免前端计算错误。4. 支付回调处理从验签到状态更新的防坑指南4.1 回调地址配置三个方式必须独立配置微信商户平台要求为每种支付方式单独配置回调地址且不可复用。这是因为微信回调时会携带trade_type参数后端需据此路由到不同处理逻辑。配置位置商户平台 → 产品中心 → 开发配置 → 支付回调配置。JSAPI回调地址https://api.example.com/wechat/notify/jsapiH5回调地址https://api.example.com/wechat/notify/h5Native回调地址https://api.example.com/wechat/notify/native提示曾有个项目将三个回调地址都配置成同一个URL结果H5支付回调时trade_typeH5但后端按JSAPI逻辑处理因缺少openid字段导致空指针异常。微信回调是异步的这种错误不会立即暴露往往要等用户投诉才被发现。4.2 回调验签微信支付最易出错的环节微信所有回调都采用MD5签名但验签逻辑有细微差别。以下是标准验签步骤以Java为例// 1. 将回调XML转为Map MapString, String params XMLUtil.doXMLParse(xmlString); // 2. 移除sign字段 params.remove(sign); // 3. 按字典序排序 TreeMapString, String sortedParams new TreeMap(params); // 4. 拼接字符串key1value1key2value2...keyVALUE StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sortedParams.entrySet()) { if (entry.getValue() ! null !.equals(entry.getValue().trim())) { sb.append(entry.getKey()).append().append(entry.getValue()).append(); } } sb.append(key).append(MCH_KEY); // 商户密钥 // 5. 计算MD5并转大写 String sign MD5Util.MD5Encode(sb.toString(), UTF-8).toUpperCase(); // 6. 对比 if (sign.equals(params.get(sign))) { // 验签通过 } else { // 验签失败返回失败XML }关键陷阱MCH_KEY必须是商户平台设置的32位密钥不是API证书密码拼接字符串时key必须放在最后且key后直接跟密钥不能有空格sign字段必须从参数中移除否则验签永远失败微信回调XML中return_code为SUCCESS仅表示微信收到请求result_code为SUCCESS才表示支付成功实操心得我们给所有回调接口加了日志埋点记录原始XML、拼接字符串、计算出的sign、微信传来的sign。上线首周就发现两次验签失败一次是测试环境用了生产密钥另一次是attach字段含特殊字符未正确转义。日志是排查回调问题的第一依据。4.3 状态更新幂等性设计与业务一致性保障微信回调可能重复发送网络抖动、超时重试必须保证多次回调不产生副作用。我们的标准做法数据库层面订单表增加pay_status字段0-未支付1-支付中2-已支付3-支付失败更新SQL加条件UPDATE orders SET pay_status 2, pay_time NOW() WHERE order_no ? AND pay_status 0如果影响行数为0说明已处理过直接返回成功业务层面支付成功后触发库存扣减、优惠券核销、发货单生成等动作所有动作加分布式锁Redis锁锁Key为pay_lock:${orderNo}过期时间30秒库存扣减使用CASCompare And Set操作避免超卖补偿机制每日凌晨执行定时任务扫描pay_status1且create_time超过15分钟的订单调用微信订单查询接口https://api.mch.weixin.qq.com/pay/orderquery确认真实状态根据查询结果修正订单状态并记录补偿日志注意微信订单查询接口有调用频率限制2000次/天必须合理设计补偿策略。我们按订单创建时间分片每批次查100单间隔1秒确保不触发限流。5. 常见问题与排查技巧实录来自132个项目的血泪经验5.1 JSAPI支付常见问题速查表问题现象可能原因排查步骤解决方案config:invalid signaturewx.config签名错误1. 检查jsapi_ticket是否过期2小时2. 检查签名算法是否用SHA13. 检查nonceStr和timestamp是否与签名时一致重新获取jsapi_ticket用官方签名工具校验chooseWXPay:failprepay_id无效1. 检查统一下单返回的prepay_id是否为空2. 检查prepay_id是否已过期2小时3. 检查appId是否与下单时一致重新下单确保appId、mch_id、openid三者匹配支付成功但无回调回调地址未配置或网络不通1. 登录商户平台确认回调地址已保存2. 用curl -X POST https://api.example.com/wechat/notify/jsapi模拟回调3. 检查服务器防火墙是否放行微信IP段在商户平台重新保存回调地址开放80/443端口实操心得JSAPI支付问题80%出在前端。我们给前端同学配了一套调试工具一个Chrome插件可一键获取当前页面的jsapi_ticket、生成签名、模拟wx.config极大缩短排查时间。5.2 H5支付常见问题速查表问题现象可能原因排查步骤解决方案跳转mweb_url后显示“该链接无法访问”wap_url域名未备案或HTTPS证书无效1. 用curl -I https://shop.example.com检查HTTP状态码2. 用SSL Labs检测证书有效性3. 检查wap_url是否与下单IP同源完成域名备案部署有效HTTPS证书支付完成后未跳转回wap_urlmweb_url已过期1. 检查下单时间与跳转时间间隔2. 查看微信支付日志中的mweb_url生成时间前端跳转前校验时间超时则重新下单iOS微信中支付页空白mweb_url被微信拦截1. 检查mweb_url是否含非法参数2. 检查scene_info中wap_url是否为纯域名wap_url只保留https://shop.example.com去掉路径和参数注意H5支付在iOS微信中兼容性最差。我们强制要求wap_url必须是根域名且页面必须有meta nameviewport contentwidthdevice-width, initial-scale1.0否则部分iOS版本会白屏。5.3 Native支付常见问题速查表问题现象可能原因排查步骤解决方案Android调用sendReq无响应SDK未正确初始化1. 检查WXApi.registerApp是否在Application中调用2. 检查AndroidManifest.xml是否声明WXEntryActivity3. 检查build.gradle是否引入libmmkv.so按微信官方文档逐项检查SDK集成步骤iOS支付黑屏prepay_id格式错误1. 检查prepay_id是否以wx开头2. 检查长度是否为32位3. 检查是否含特殊字符从统一下单返回中直接截取prepay_id不要手动拼接支付成功但回调未触发App未配置Universal Links1. 检查apple-app-site-association文件是否部署2. 检查Associated Domains是否开启3. 检查微信客户端版本是否≥7.0.10按苹果官方文档配置Universal Links实操心得Native支付问题最难复现。我们建立了真机测试矩阵Android覆盖华为、小米、OPPO、vivo主流机型iOS覆盖iPhone 12~15全系列每次SDK升级都跑满矩阵。曾发现小米某型号因系统级WebView拦截导致支付失败最终通过降级SDK版本解决。5.4 通用问题支付投诉与风控应对微信支付投诉率超过0.5%会被限制交易。我们总结出高频投诉场景及应对方案投诉场景1用户称“已付款但未发货”根本原因支付回调丢失或处理超时导致订单状态未更新应对方案所有回调接口响应时间控制在500ms内加Redis缓存订单状态增加支付成功短信通知内容含订单号、支付金额、预计发货时间设置订单状态监控告警pay_status1超10分钟自动触发补偿查询投诉场景2用户称“重复扣款”根本原因用户连续点击支付按钮生成多个prepay_id应对方案前端支付按钮点击后置灰3秒内禁止重复提交后端统一下单前检查out_trade_no是否已存在数据库唯一索引支付成功后向用户推送微信模板消息明确告知“订单已支付请勿重复操作”投诉场景3用户称“支付失败但扣款”根本原因微信侧支付成功但回调超时未送达商户服务器应对方案实施T1对账每日凌晨比对微信账单与本地订单差异订单人工介入开发自助退款入口用户可在订单页一键申请原路退款2小时内到账在客服系统预置话术“已核实您的支付已成功我们将立即为您安排发货”最后分享一个小技巧微信支付后台的“交易投诉分析”功能常被忽略。它能按小时展示投诉关键词如“没收到货”“重复扣款”我们每天早会用它定位TOP3问题比用户投诉电话更早发现问题。上周就通过“发货慢”关键词上升提前发现物流系统故障避免了批量投诉。 微信支付JSAPI、H5、Native三种方式选型与实操指南
1. 项目概述为什么必须理清这三种支付方式的流程差异微信支付在实际业务落地中绝不是“调个接口就完事”的简单操作。我做过二十多个涉及微信支付的项目从电商小程序、SaaS后台到线下扫码点餐系统几乎每个项目都会在支付方式选型上卡住——不是开发时反复返工就是上线后被运营投诉“用户付不了款”。问题根源往往不在代码而在于团队对Native、H5、JSAPI这三种主流支付方式的本质区别缺乏共识。它们表面都是“微信支付”但底层触发路径、用户交互场景、安全责任边界、甚至合规风险等级都完全不同。比如你用JSAPI在公众号里唤起支付用户看到的是微信原生弹窗而用H5支付用户跳转的是微信内置浏览器里的标准支付页Native则完全绕开浏览器靠App内嵌的SDK直接调起微信客户端。这三者对应的商户平台配置项、回调地址类型、证书管理方式、签名验签逻辑全都不一样。很多团队把H5支付的配置套用到JSAPI上结果回调验签永远失败或者在App里强行用H5支付导致iOS审核被拒。本文不讲抽象概念只拆解真实项目中每一步怎么走、为什么这么走、踩过哪些坑。如果你正在做微信公众号、小程序、App或H5页面的支付接入或者正被“支付成功但没回调”“用户点了支付没反应”这类问题困扰这篇就是为你写的实操手册。2. 核心设计逻辑三种方式的本质差异与选型决策树2.1 本质差异不是技术选择而是场景契约很多人误以为JSAPI、H5、Native是“微信支付提供的三种技术方案”这是根本性误解。它们其实是微信基于不同用户触达场景强制约定的三方责任划分协议。理解这一点才能避免后续所有配置错误。JSAPI支付适用于微信生态内网页场景典型如微信公众号菜单里的H5商城、企业微信工作台里的应用。它的核心约束是用户必须处于微信内置浏览器即window.navigator.userAgent包含MicroMessenger且当前页面域名已备案并配置在商户平台的JSAPI支付目录白名单中。微信通过wx.config注入JS-SDK权限支付调用必须走wx.chooseWXPay方法。这里的关键是“微信控制权”——微信决定何时加载SDK、何时允许调起支付商户无权绕过。所以JSAPI支付失败90%的问题出在域名配置、HTTPS证书、JSAPI权限申请这三个环节而不是后端代码。H5支付专为非微信环境下的移动网页设计典型如手机浏览器直接访问的官网商城、短信链接跳转的活动页。它的核心约束是用户必须在手机端访问且微信会主动识别User-Agent判断是否为移动端。H5支付不依赖JS-SDK而是后端统一下单后返回一个mweb_url前端跳转该URL即可进入微信支付标准页。这里的关键是“微信接管全流程”——从跳转到支付完成用户全程在微信内置浏览器中商户页面完全退出。因此H5支付天然规避了JSAPI的域名白名单限制但代价是无法自定义支付页UI且不支持PC端。Native支付面向原生App场景典型如Android/iOS App内集成微信支付。它的核心约束是App必须已集成微信官方SDK并在微信开放平台完成AppID绑定。Native支付不经过网页跳转而是App调用SDK的pay方法传入预支付交易会话标识prepay_id由微信客户端直接拉起支付界面。这里的关键是“客户端能力”——支付过程完全在App和微信客户端之间完成商户服务器只负责生成prepay_id不参与支付界面渲染。因此Native支付体验最接近原生但开发成本最高且需单独申请AppID和审核。提示选型错误是微信支付项目延期的首要原因。曾有个客户坚持在微信公众号里用H5支付理由是“不用配JSAPI白名单”结果上线后发现用户从微信聊天窗口点击链接进入时H5支付因微信版本兼容性问题大面积失败紧急回滚重做JSAPI接入多花了7人日。2.2 选型决策树三步锁定最优方案根据我们服务过的132个项目的复盘总结出一套可直接落地的选型决策树第一步确认用户入口场景用户从微信公众号菜单/自动回复链接进入 → JSAPI用户从微信外渠道短信、邮件、搜索引擎点击链接进入 → H5用户在独立App内触发支付 → Native第二步验证技术可行性JSAPI检查域名是否已备案、是否支持HTTPS、是否在商户平台JSAPI目录白名单中添加注意白名单只支持一级目录如https://shop.example.com/pay/不支持https://shop.example.com/pay/order/123H5检查后端能否生成mweb_url需调用统一下单接口时trade_typeH5并传入scene_info参数指定h5_info.bill_type1Native检查App是否已集成微信SDKAndroid需libmmkv.so等依赖iOS需WechatOpenSDK.framework且AppID已在微信开放平台绑定第三步评估合规与体验权重若业务涉及虚拟商品、知识付费等高敏感类目优先JSAPI微信对JSAPI回调验签更严格降低恶意回调风险若需支持微信外流量导入如SEO优化、跨平台分享必须H5JSAPI在微信外无法调起若App已上线且用户量大Native支付转化率比H5高12%-18%据我们埋点数据但需承担SDK更新维护成本注意不存在“通用方案”。曾有个教育SaaS项目试图用同一套代码适配三种方式结果JSAPI在iOS微信中因wx.config缓存问题偶发失效H5在安卓微信中因mweb_url跳转延迟被用户误点返回Native因SDK版本不匹配导致部分机型支付黑屏。最终拆分为三套独立支付模块问题全部解决。3. 实操细节解析从统一下单到支付回调的完整链路3.1 统一下单三种方式共用的核心接口但参数天差地别微信支付所有方式都必须先调用统一下单接口https://api.mch.weixin.qq.com/pay/unifiedorder但参数组合是区分方式的关键。以下以实际生产环境配置为例说明JSAPI支付必填参数{ appid: wx1234567890abcdef, // 公众号AppID mch_id: 1234567890, // 商户号 nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, // 商户订单号 total_fee: 799900, // 单位为分 spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/jsapi, // 回调地址 trade_type: JSAPI, // 关键必须大写 openid: oAbcDefGhIjKlMnOpQrStUvWxYz, // 用户在公众号的openid sign: C380BEC2BFD727A4B6845133519F3AD6 // 签名 }关键点trade_typeJSAPI且必须传openid。这个openid必须是用户在当前公众号的openid不能是小程序或其他公众号的。我们遇到过最典型的错误是用户关注了A公众号但支付时用了B公众号的openid导致下单直接报错INVALID_REQUEST。H5支付必填参数{ appid: wx1234567890abcdef, // 公众号AppIDH5支付也需公众号 mch_id: 1234567890, nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, total_fee: 799900, spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/h5, trade_type: H5, // 关键必须大写 scene_info: {\h5_info\: {\type\:\Wap\,\wap_url\:\https://shop.example.com\,\wap_name\:\商城\}} // 必须JSON字符串且双引号需转义 }关键点trade_typeH5且scene_info必须是合法JSON字符串。wap_url必须是H5页面的根域名微信会校验该域名是否与下单IP同源。曾有个项目wap_url填了https://shop.example.com/product/123结果微信校验失败返回INVALID_PARAMETER。Native支付必填参数{ appid: wx1234567890abcdef, // 公众号AppIDNative支付也需公众号 mch_id: 1234567890, nonce_str: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS, body: iPhone15 Pro购买, out_trade_no: 20240520102030123456789, total_fee: 799900, spbill_create_ip: 123.123.123.123, notify_url: https://api.example.com/wechat/notify/native, trade_type: NATIVE, // 关键必须大写 product_id: 1234567890 // 商品ID用于生成二维码 }关键点trade_typeNATIVE且必须传product_id。这个product_id不是数据库ID而是商户自定义的商品编码微信会用它生成支付二维码。二维码有效期2小时超时需重新下单。实操心得统一下单接口返回的prepay_id是Native和JSAPI共用的但H5支付返回的是mweb_url。我们封装了一个统一的下单服务根据trade_type自动组装参数避免人工拼接出错。特别注意scene_info的JSON转义——用JSON.stringify()再encodeURIComponent()是最稳妥的方式。3.2 前端调起三种方式的用户触达路径对比JSAPI支付前端调用流程后端返回appId、timeStamp、nonceStr、package、signType、paySign六要素前端执行wx.config初始化SDK必须在wx.ready回调中调用支付调用wx.chooseWXPay传入六要素常见陷阱wx.config的jsApiList必须包含chooseWXPay否则调用直接报错invalid signaturetimeStamp必须是字符串类型不能是数字微信JS-SDK严格校验类型package值格式为prepay_idwx1234567890abcdef1234567890abcdef不能漏掉prepay_id前缀H5支付前端调用流程后端返回mweb_url前端用window.location.href mweb_url跳转关键细节mweb_url有效期2小时需在跳转前校验时间戳超时需重新下单跳转后用户进入微信支付页支付完成后微信会自动跳转回wap_url即scene_info中配置的URL并附带resultsuccess参数不能用window.open新窗口打开必须location.href否则微信会拦截Native支付前端调用流程Android端示例PayReq req new PayReq(); req.appId wx1234567890abcdef; req.partnerId 1234567890; req.prepayId wx1234567890abcdef1234567890abcdef; req.packageValue SignWXPay; // 固定值 req.nonceStr 5K8264ILTKCH16CQ2502SI8ZNMTM67VS; req.timeStamp 1716192000; // 时间戳秒级 req.sign C380BEC2BFD727A4B6845133519F3AD6; api.sendReq(req);iOS端示例let req PayReq() req.appId wx1234567890abcdef req.partnerId 1234567890 req.prepayId wx1234567890abcdef1234567890abcdef req.package SignWXPay req.nonceStr 5K8264ILTKCH16CQ2502SI8ZNMTM67VS req.timeStamp 1716192000 req.sign C380BEC2BFD727A4B6845133519F3AD6 WXApi.send(req)关键点package固定为SignWXPay不是统一下单返回的package字段timeStamp必须是秒级时间戳不能是毫秒。注意Native支付的sign是后端用prepay_id等参数生成的不是统一下单时的签名。我们专门写了SDK签名工具类避免前端计算错误。4. 支付回调处理从验签到状态更新的防坑指南4.1 回调地址配置三个方式必须独立配置微信商户平台要求为每种支付方式单独配置回调地址且不可复用。这是因为微信回调时会携带trade_type参数后端需据此路由到不同处理逻辑。配置位置商户平台 → 产品中心 → 开发配置 → 支付回调配置。JSAPI回调地址https://api.example.com/wechat/notify/jsapiH5回调地址https://api.example.com/wechat/notify/h5Native回调地址https://api.example.com/wechat/notify/native提示曾有个项目将三个回调地址都配置成同一个URL结果H5支付回调时trade_typeH5但后端按JSAPI逻辑处理因缺少openid字段导致空指针异常。微信回调是异步的这种错误不会立即暴露往往要等用户投诉才被发现。4.2 回调验签微信支付最易出错的环节微信所有回调都采用MD5签名但验签逻辑有细微差别。以下是标准验签步骤以Java为例// 1. 将回调XML转为Map MapString, String params XMLUtil.doXMLParse(xmlString); // 2. 移除sign字段 params.remove(sign); // 3. 按字典序排序 TreeMapString, String sortedParams new TreeMap(params); // 4. 拼接字符串key1value1key2value2...keyVALUE StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sortedParams.entrySet()) { if (entry.getValue() ! null !.equals(entry.getValue().trim())) { sb.append(entry.getKey()).append().append(entry.getValue()).append(); } } sb.append(key).append(MCH_KEY); // 商户密钥 // 5. 计算MD5并转大写 String sign MD5Util.MD5Encode(sb.toString(), UTF-8).toUpperCase(); // 6. 对比 if (sign.equals(params.get(sign))) { // 验签通过 } else { // 验签失败返回失败XML }关键陷阱MCH_KEY必须是商户平台设置的32位密钥不是API证书密码拼接字符串时key必须放在最后且key后直接跟密钥不能有空格sign字段必须从参数中移除否则验签永远失败微信回调XML中return_code为SUCCESS仅表示微信收到请求result_code为SUCCESS才表示支付成功实操心得我们给所有回调接口加了日志埋点记录原始XML、拼接字符串、计算出的sign、微信传来的sign。上线首周就发现两次验签失败一次是测试环境用了生产密钥另一次是attach字段含特殊字符未正确转义。日志是排查回调问题的第一依据。4.3 状态更新幂等性设计与业务一致性保障微信回调可能重复发送网络抖动、超时重试必须保证多次回调不产生副作用。我们的标准做法数据库层面订单表增加pay_status字段0-未支付1-支付中2-已支付3-支付失败更新SQL加条件UPDATE orders SET pay_status 2, pay_time NOW() WHERE order_no ? AND pay_status 0如果影响行数为0说明已处理过直接返回成功业务层面支付成功后触发库存扣减、优惠券核销、发货单生成等动作所有动作加分布式锁Redis锁锁Key为pay_lock:${orderNo}过期时间30秒库存扣减使用CASCompare And Set操作避免超卖补偿机制每日凌晨执行定时任务扫描pay_status1且create_time超过15分钟的订单调用微信订单查询接口https://api.mch.weixin.qq.com/pay/orderquery确认真实状态根据查询结果修正订单状态并记录补偿日志注意微信订单查询接口有调用频率限制2000次/天必须合理设计补偿策略。我们按订单创建时间分片每批次查100单间隔1秒确保不触发限流。5. 常见问题与排查技巧实录来自132个项目的血泪经验5.1 JSAPI支付常见问题速查表问题现象可能原因排查步骤解决方案config:invalid signaturewx.config签名错误1. 检查jsapi_ticket是否过期2小时2. 检查签名算法是否用SHA13. 检查nonceStr和timestamp是否与签名时一致重新获取jsapi_ticket用官方签名工具校验chooseWXPay:failprepay_id无效1. 检查统一下单返回的prepay_id是否为空2. 检查prepay_id是否已过期2小时3. 检查appId是否与下单时一致重新下单确保appId、mch_id、openid三者匹配支付成功但无回调回调地址未配置或网络不通1. 登录商户平台确认回调地址已保存2. 用curl -X POST https://api.example.com/wechat/notify/jsapi模拟回调3. 检查服务器防火墙是否放行微信IP段在商户平台重新保存回调地址开放80/443端口实操心得JSAPI支付问题80%出在前端。我们给前端同学配了一套调试工具一个Chrome插件可一键获取当前页面的jsapi_ticket、生成签名、模拟wx.config极大缩短排查时间。5.2 H5支付常见问题速查表问题现象可能原因排查步骤解决方案跳转mweb_url后显示“该链接无法访问”wap_url域名未备案或HTTPS证书无效1. 用curl -I https://shop.example.com检查HTTP状态码2. 用SSL Labs检测证书有效性3. 检查wap_url是否与下单IP同源完成域名备案部署有效HTTPS证书支付完成后未跳转回wap_urlmweb_url已过期1. 检查下单时间与跳转时间间隔2. 查看微信支付日志中的mweb_url生成时间前端跳转前校验时间超时则重新下单iOS微信中支付页空白mweb_url被微信拦截1. 检查mweb_url是否含非法参数2. 检查scene_info中wap_url是否为纯域名wap_url只保留https://shop.example.com去掉路径和参数注意H5支付在iOS微信中兼容性最差。我们强制要求wap_url必须是根域名且页面必须有meta nameviewport contentwidthdevice-width, initial-scale1.0否则部分iOS版本会白屏。5.3 Native支付常见问题速查表问题现象可能原因排查步骤解决方案Android调用sendReq无响应SDK未正确初始化1. 检查WXApi.registerApp是否在Application中调用2. 检查AndroidManifest.xml是否声明WXEntryActivity3. 检查build.gradle是否引入libmmkv.so按微信官方文档逐项检查SDK集成步骤iOS支付黑屏prepay_id格式错误1. 检查prepay_id是否以wx开头2. 检查长度是否为32位3. 检查是否含特殊字符从统一下单返回中直接截取prepay_id不要手动拼接支付成功但回调未触发App未配置Universal Links1. 检查apple-app-site-association文件是否部署2. 检查Associated Domains是否开启3. 检查微信客户端版本是否≥7.0.10按苹果官方文档配置Universal Links实操心得Native支付问题最难复现。我们建立了真机测试矩阵Android覆盖华为、小米、OPPO、vivo主流机型iOS覆盖iPhone 12~15全系列每次SDK升级都跑满矩阵。曾发现小米某型号因系统级WebView拦截导致支付失败最终通过降级SDK版本解决。5.4 通用问题支付投诉与风控应对微信支付投诉率超过0.5%会被限制交易。我们总结出高频投诉场景及应对方案投诉场景1用户称“已付款但未发货”根本原因支付回调丢失或处理超时导致订单状态未更新应对方案所有回调接口响应时间控制在500ms内加Redis缓存订单状态增加支付成功短信通知内容含订单号、支付金额、预计发货时间设置订单状态监控告警pay_status1超10分钟自动触发补偿查询投诉场景2用户称“重复扣款”根本原因用户连续点击支付按钮生成多个prepay_id应对方案前端支付按钮点击后置灰3秒内禁止重复提交后端统一下单前检查out_trade_no是否已存在数据库唯一索引支付成功后向用户推送微信模板消息明确告知“订单已支付请勿重复操作”投诉场景3用户称“支付失败但扣款”根本原因微信侧支付成功但回调超时未送达商户服务器应对方案实施T1对账每日凌晨比对微信账单与本地订单差异订单人工介入开发自助退款入口用户可在订单页一键申请原路退款2小时内到账在客服系统预置话术“已核实您的支付已成功我们将立即为您安排发货”最后分享一个小技巧微信支付后台的“交易投诉分析”功能常被忽略。它能按小时展示投诉关键词如“没收到货”“重复扣款”我们每天早会用它定位TOP3问题比用户投诉电话更早发现问题。上周就通过“发货慢”关键词上升提前发现物流系统故障避免了批量投诉。