"H5 接微信支付难"不是技术难,是分支判断难——同一个 H5 页面,在微信里打开和在外面打开,走的是两条完全不同的链路。本文把 JSAPI 与 H5(MWEB) 两条主路从原理到代码完整讲透,顺便把公众号配置、签名验签、回调安全、最常见的 10 个坑一次性收齐。
"H5商城"在用户眼里是同一个东西,在支付眼里却是三种完全不同的运行环境:
公众号菜单进入、朋友圈/会话链接点击、扫码进入——所有 URL 都在微信内置浏览器里运行。
Safari / Chrome / QQ 浏览器 / UC 浏览器等原生浏览器,直接输入域名或外部引流落地。
抖音/小红书/百度等 APP 内嵌的浏览器内核,referer 指向宿主 APP,行为介于以上两者之间。
前端用 UA 判断环境 → 微信内走 JSAPI → 外部浏览器走 H5(MWEB) → 后端根据通道调用对应的统一下单接口。后面的所有内容都是围绕这句话展开。
很多人一上来就"调支付",但连自己有几种通道可用都没盘清。先用一张图把微信支付的产品矩阵摆出来。
| 支付方式 | 简称 | 适用场景 | 关键依赖 | H5 可用? |
|---|---|---|---|---|
| JSAPI 支付 | JSAPI | 微信内浏览器(公众号H5、小程序web-view) | 公众号 AppID + 商户号绑定 | ✓ 主路 |
| H5 支付 | MWEB | 手机外部浏览器 | 商户号 + H5 域名 ICP 备案 | ✓ 主路 |
| Native 支付 | NATIVE | PC 网页,生成二维码扫码 | 商户号 | △ 兜底 |
| 小程序支付 | — | 微信小程序 | 小程序 AppID + 商户号绑定 | ✕ |
| APP 支付 | APP | 原生 APP(集成微信 OpenSDK) | 开放平台 AppID + 商户号绑定 | ✕ |
| 付款码支付 | — | 线下被扫 | 商户号 + 专用硬件 | ✕ |
| 刷脸支付 | — | 线下自助终端 | 刷脸开放平台 + 商户号 | ✕ |
订阅号权限不足,无法做支付。个人/个体工商户可申请,但部分能力受限。
在 pay.weixin.qq.com 申请,需营业执照 + 对公账户,审批 1~7 个工作日。
商户平台 → 产品中心 → AppID 授权管理 → 新增 → 填入公众号 AppID → 公众号后台确认。
公众平台 → 公众号设置 → 功能设置 → 网页授权 / JSAPI 支付授权目录。需精确到发起支付页面的路径前缀,例如 https://shop.example.com/order/。
用于 OAuth 静默/授权拿 code 的回调域名。需上传验证文件。
商户平台 → API 安全 → 申请 APIv3 密钥 + 下载 apiclient_cert.pem / apiclient_key.pem,妥善保管。
// Node.js 示例:调 jsapi 统一下单,返回前端需要的支付参数 const WxPay = require('wechatpay-node-v3') const pay = new WxPay({ appid: 'wx0123456789abcdef', mchid: '1900000001', publicKey: fs.readFileSync('./apiclient_cert.pem'), privateKey: fs.readFileSync('./apiclient_key.pem'), key: 'APIv3密钥32位' }) async function createJsapiOrder(order, openid) { const result = await pay.transactions_jsapi({ description: order.goodsName, // 商品描述 out_trade_no: order.id, // 商户订单号(全局唯一) notify_url: 'https://shop.example.com/api/pay/notify', amount: { total: order.amountFen, currency: 'CNY' }, // 单位:分 payer: { openid } // ★ JSAPI 必须 }) // result.prepay_id // 用 prepay_id 在后端再次签名,生成前端调起支付所需的 6 个字段 const payParams = pay.signForAppPay(result.prepay_id) return payParams // { appId, timeStamp, nonceStr, package, signType, paySign } }
// 微信内 H5 拉起支付的关键代码 function invokeWechatPay(payParams) { function onBridgeReady() { WeixinJSBridge.invoke( 'getBrandWCPayRequest', payParams, // 后端签名后的 6 个字段 function(res) { if (res.err_msg === 'get_brand_wCPayRequest:ok') { console.log('支付成功,等异步回调') // 注意:此时只是"用户确认了",并不代表发货依据 } else if (res.err_msg === 'get_brand_wCPayRequest:cancel') { console.log('用户取消') } else { console.error('支付失败', res.err_msg) } } ) } if (typeof WeixinJSBridge === 'undefined') { document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false) } else { onBridgeReady() } }
cancel 再回调 ok 与否。不应仅凭此状态判断"支付成功"——必须等 notify_url 的异步通知,或主动调用"查单接口"轮询确认。
JSAPI 强依赖 openid,但 openid 只有在微信内才有。用户在外部浏览器打开 H5 时根本不在微信内,没法走 JSAPI——这时就得用 H5 支付(MWEB),微信专门为外部浏览器场景开的接口。
POST /v3/pay/transactions/h5,传入 scene_info.payer_client_ip 和 h5_info;https://wx.tenpay.com/...);window.location.href = h5_url,浏览器跳转到微信收银台;商户平台 → 产品中心 → H5 支付 → 申请开通,通常需要一定的网站 ICP 备案信息。
商户平台 → 产品中心 → H5 支付 → 域名管理。域名必须完成 ICP 备案,支持子域名配置。referer 必须命中已配置的域名。
回跳地址的根域名也必须在白名单中,否则微信会拒绝跳回。
不强制但强烈建议——iOS 9+ 后,scheme 跳转被沙箱限制,需要 Universal Links 才能稳定拉起微信 APP。
async function createH5Order(order, clientIp) { const result = await pay.transactions_h5({ description: order.goodsName, out_trade_no: order.id, notify_url: 'https://shop.example.com/api/pay/notify', amount: { total: order.amountFen, currency: 'CNY' }, scene_info: { // ★ MWEB 必传 payer_client_ip: clientIp, // 用户真实外网 IP(不是后端服务器 IP!) h5_info: { type: 'Wap', // 或 "iOS" / "Android" / "Wap" wap_url: 'https://shop.example.com', // 实际商品所在 H5 域名 wap_name: '示例商城' // 显示在微信支付页的应用名 } } }) return { h5Url: result.h5_url, redirectUrl: 'https://shop.example.com/pay/return' } }
// 拿到后端返回的 h5_url,直接跳 async function goPay() { const res = await axios.post('/api/order/create', { skuId: 'SKU001' }) if (res.h5Url) { window.location.href = res.h5Url // 直接跳到微信收银台 } } // redirect_url 对应的页面(/pay/return),仅用来给用户看"支付完成/失败/取消"的视觉反馈 // 真实的支付成功/失败以 notify_url 异步通知为准 function checkReturnStatus() { const params = new URLSearchParams(location.search) if (params.get('status') === 'success') showSuccessToast() else showFailToast() }
scene_info.payer_client_ip 是用户外网 IP(从请求头 X-Forwarded-For 取),不是后端服务器 IP。常见做法是前端用公共 IP 查询服务获取,或后端读 CDN 透传的 XFF 头。
servicewechat.com,被风控直接拒绝;且微信内应优先走 JSAPI,体验远好于 MWEB。
| 维度 | JSAPI 支付 | H5 支付(MWEB) |
|---|---|---|
| 运行环境 | 微信内置浏览器 | Safari / Chrome / QQ / UC 等外部浏览器 |
| 用户路径 | 点击 → 弹窗 → 完成 | 跳转 → 拉起微信 → 完成 |
| 用户体验 | 极顺,无跳出 | 中等,有跳转感 |
| 必传参数 | openid | scene_info(用户 IP + wap_url + wap_name) |
| 域名要求 | 支付授权目录 + 授权域名 | ICP 备案 + 商户平台 H5 域名配置 |
| 回跳商户 | 不需 redirect_url | 需 redirect_url(可带状态参数) |
| 风控严格度 | 较低 | 较高(限域名 / 限 IP / 限设备指纹) |
| 实现复杂度 | 中(OAuth + JSAPI) | 低(后端给 URL 前端跳转) |
| 调试友好度 | 需开发者工具 / 真机 | PC 浏览器开发者工具即可调试前端 |
| 最适场景 | 公众号内 / 微信群分享 | 短信 / 二维码 / 站外引流 / 全网落地页 |
// 前端:按 UA 决定走哪条路 function getPayChannel() { const ua = navigator.userAgent const isWechat = /MicroMessenger/i.test(ua) const isMini = /miniProgram/i.test(ua) // 小程序 web-view if (isMini) return 'miniProgram' // 需走 wx.miniProgram.navigateTo 等跳回小程序 if (isWechat) return 'jsapi' // 微信内 return 'h5' // 外部浏览器 } async function pay(orderId) { const channel = getPayChannel() if (channel === 'jsapi') { // 走 JSAPI:后端需要 openid(请后端根据 unionid/cookie 自动关联) const { payParams } = await axios.post('/api/pay/jsapi', { orderId }) invokeWechatPay(payParams) } else if (channel === 'h5') { const { h5Url } = await axios.post('/api/pay/h5', { orderId }) window.location.href = h5Url } else { showToast('请在微信中打开,或复制链接到浏览器') } }
对请求体做 SHA256-RSA2048 签名,放入 HTTP Header:
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000001", nonce_str="随机串",timestamp="时间戳秒", serial_no="商户证书序列号",signature="Base64后的签名"
HTTP 方法\n请求 URL\n请求时间戳\n请求随机串\n请求报文主体apiclient_key.pem 私钥签名,公钥(微信侧)验签微信向 notify_url POST 的报文头里会带:
Wechatpay-Timestamp: 时间戳 Wechatpay-Nonce: 随机串 Wechatpay-Signature: 签名值 Wechatpay-Serial: 平台证书序列号
验签流程:
timestamp\nnonce\nbody\n(注意 body 是原始字节);out_trade_no(商户订单号)做幂等键,同一笔订单多次回调只处理一次;GET /v3/pay/transactions/out-trade-no/{out_trade_no} 主动查单,作为异步通知丢失的兜底;| 现象 | 根因 | 排查/修复 |
|---|---|---|
| "当前页面的 URL 未注册" | JSAPI 支付授权目录未配置当前发起支付页 URL 的路径前缀 | 公众平台 → 公众号设置 → 功能设置 → JSAPI 支付授权目录 |
| "redirect_uri 域名与后台配置不一致" | OAuth 网页授权域名未配置,或回调地址用了 IP / http | 公众平台 → 功能设置 → 网页授权域名;必须 https + 域名 |
| "appid 和 mch_id 不匹配" | 商户平台未授权该 AppID,或绑定了别的主体 AppID | 商户平台 → 产品中心 → AppID 授权管理,核对 appid 串 |
| "该商户暂不支持该支付方式" | JSAPI / H5 权限未开通,或商户被风控限制 | 商户平台 → 产品中心 → 我的产品,申请开通;或联系 BD |
| H5 支付拉不起微信 | 域名未 ICP 备案 / 未在商户平台配置 / referer 不命中 | 备案并配置;确保 referer 是 https + 已配置域名 |
| "下单账号与支付账号不一致" | 当前 openid 与下单时传入的 openid 不是同一个人(测试时常见) | 统一用"当前用户"获取 openid 后再下单;不要写死 |
| 回调一直收不到 | notify_url 不可达 / 被防火墙拦截 / 返回非 200 | 用 curl 公网测试可达;返回 200 + {"code":"SUCCESS","message":"成功"} |
| 回调验签失败 | 用了过期的平台证书,或验签串拼错(尤其是 body 用了 parsed 对象) | 定期下载平台证书缓存;验签用原始 body 字节 |
| "商户订单号重复" | 同一 out_trade_no 二次下单 | 每笔订单号唯一;或查询原订单状态再决定 |
| MWEB 在微信内打开无反应 | H5 支付不允许在微信内使用(风控拦截) | 前端 UA 判断:微信内必须走 JSAPI |
| 语言 | 推荐库 | 说明 |
|---|---|---|
| Node.js | wechatpay-node-v3 / wechatpay-axios-plugin | 官方推荐思路,异步 API 支持完善 |
| Java | weixin-java-pay | 公众号/小程序/APP/H5 全覆盖,Spring 友好 |
| Python | wechatpay-v3 / python-wechatpay | 社区主流,文档中文友好 |
| PHP | wechatpay-guzzle-middleware / yansongda/pay | 国内电商项目广泛使用 |
| Go | go-wechatpay-golang | 轻量、纯 Go 实现 |
// server/pay.js —— 一个文件搞定 JSAPI + MWEB 下单 import WxPay from 'wechatpay-node-v3' import fs from 'fs' const pay = new WxPay({ appid: process.env.WX_APPID, mchid: process.env.WX_MCHID, publicKey: fs.readFileSync(process.env.WX_CERT), privateKey: fs.readFileSync(process.env.WX_KEY), key: process.env.WX_APIV3_KEY, // 32 位 }) export async function createOrder({ channel, order, openid, clientIp }) { const base = { description: order.title, out_trade_no: order.id, notify_url: process.env.WX_NOTIFY_URL, amount: { total: order.amountFen, currency: 'CNY' }, } if (channel === 'jsapi') { const r = await pay.transactions_jsapi({ ...base, payer: { openid } }) return pay.signForAppPay(r.prepay_id) } if (channel === 'h5') { const r = await pay.transactions_h5({ ...base, scene_info: { payer_client_ip: clientIp, h5_info: { type: 'Wap', wap_url: process.env.SHOP_URL, wap_name: '我的商城' } } }) return { h5Url: r.h5_url } } throw new Error('未知渠道:' + channel) } // 回调处理(/api/pay/notify) export async function handleNotify(req, res) { const ok = pay.verifySign({ // 内部:验签 + 解密 timestamp: req.headers['wechatpay-timestamp'], nonce: req.headers['wechatpay-nonce'], body: req.rawBody, // ★ 必须是 raw bytes serial: req.headers['wechatpay-serial'], signature: req.headers['wechatpay-signature'], }) if (!ok) return res.status(401).send('fail') const data = pay.decrypt(req.body.resource) await orderService.markPaid(data.out_trade_no, data.transaction_id) res.json({ code: 'SUCCESS', message: '成功' }) }