PAYMENT · H5 · WECHATPAY

H5商城接入微信支付:
原理拆解与主流连接方式全解

"H5 接微信支付难"不是技术难,是分支判断难——同一个 H5 页面,在微信里打开和在外面打开,走的是两条完全不同的链路。本文把 JSAPI 与 H5(MWEB) 两条主路从原理到代码完整讲透,顺便把公众号配置、签名验签、回调安全、最常见的 10 个坑一次性收齐。

📚 10 个章节 🧭 JSAPI / H5(MWEB) 双主线 🔐 APIv3 签名 + 回调验签 💻 含可直接套用的代码片段 🚧 10+ 常见踩坑与排查清单
01 分支困境 02 支付全家桶 03 核心原理 04 JSAPI 主路 05 H5(MWEB) 主路 06 对比与选型 07 接入全流程 08 安全与签名 09 踩坑清单 10 工具与模板
PART 01

前言:H5 接微信支付是个"分支题"

"H5商城"在用户眼里是同一个东西,在支付眼里却是三种完全不同的运行环境:

场景 1 · 微信内打开

公众号菜单进入、朋友圈/会话链接点击、扫码进入——所有 URL 都在微信内置浏览器里运行。

场景 2 · 外部浏览器打开

Safari / Chrome / QQ 浏览器 / UC 浏览器等原生浏览器,直接输入域名或外部引流落地。

场景 3 · 第三方 APP WebView

抖音/小红书/百度等 APP 内嵌的浏览器内核,referer 指向宿主 APP,行为介于以上两者之间。

关键认知:微信支付的 6 种通道里,H5 真正能用的只有两种——JSAPI(微信内)和 H5/移动端网页支付(MWEB)。前者最顺,后者最广。判断不准环境,就会出现"在微信里调起失败"或"在外面怎么也拉不起微信"这两类经典故障。

一句话定方向

前端用 UA 判断环境 → 微信内走 JSAPI → 外部浏览器走 H5(MWEB) → 后端根据通道调用对应的统一下单接口。后面的所有内容都是围绕这句话展开。

PART 02

先把图谱看清:微信支付全家桶

很多人一上来就"调支付",但连自己有几种通道可用都没盘清。先用一张图把微信支付的产品矩阵摆出来。

支付方式简称适用场景关键依赖H5 可用?
JSAPI 支付JSAPI微信内浏览器(公众号H5、小程序web-view)公众号 AppID + 商户号绑定✓ 主路
H5 支付MWEB手机外部浏览器商户号 + H5 域名 ICP 备案✓ 主路
Native 支付NATIVEPC 网页,生成二维码扫码商户号△ 兜底
小程序支付—微信小程序小程序 AppID + 商户号绑定✕
APP 支付APP原生 APP(集成微信 OpenSDK)开放平台 AppID + 商户号绑定✕
付款码支付—线下被扫商户号 + 专用硬件✕
刷脸支付—线下自助终端刷脸开放平台 + 商户号✕

H5 商城实际能选的三种组合

PART 03

核心原理:一次支付,涉及哪些"角色"和"动作"

链路全景图

用户浏览器 商户 H5 前端 商户后端服务 Server / API 微信支付后端 api.mch.weixin.qq.com 微信客户端 用户确认支付 异步回调 (notify_url) 微信 → 商户后端,POST JSON,签名验证,处理订单 ①下单 ②统一下单 ③返回 ④支付参数/URL ⑤前端拉起 ⑥拉起/跳转微信客户端 ⑦同步结果回前端 (仅 MWEB) ⑧异步通知 (真正的支付结果) ↑
图 3-1 一次 H5 微信支付的完整链路(以 MWEB 为例,JSAPI 在第⑤步通过 WeixinJSBridge 直接弹窗,省掉⑥⑦)

6 个核心概念先记住

PART 04

主路 A · JSAPI 支付:微信内 H5 的"丝滑主路"

4.1 适用与不适用

4.2 完整调用时序

用户(微信内) H5 前端 商户后端 微信支付 ①进入 H5,触发 OAuth 拿 code ②code → 后端换 openid 并缓存 ③点击"支付",前端请求下单 ④后端调统一下单(JSAPI) ⑤返回 prepay_id ⑥签名后返回前端 paySign 等参数 ⑦WeixinJSBridge.invoke 拉起支付
图 4-1 JSAPI 支付时序(异步回调在 ⑤~⑦ 之外的另一条独立通道,见 PART 08)

4.3 前置配置清单

1
申请服务号并完成认证

订阅号权限不足,无法做支付。个人/个体工商户可申请,但部分能力受限。

2
申请微信支付商户号

在 pay.weixin.qq.com 申请,需营业执照 + 对公账户,审批 1~7 个工作日。

3
商户平台绑定公众号 AppID

商户平台 → 产品中心 → AppID 授权管理 → 新增 → 填入公众号 AppID → 公众号后台确认。

4
配置【支付授权目录】

公众平台 → 公众号设置 → 功能设置 → 网页授权 / JSAPI 支付授权目录。需精确到发起支付页面的路径前缀,例如 https://shop.example.com/order/。

5
配置【网页授权域名】

用于 OAuth 静默/授权拿 code 的回调域名。需上传验证文件。

6
开通 APIv3 并下载商户证书

商户平台 → API 安全 → 申请 APIv3 密钥 + 下载 apiclient_cert.pem / apiclient_key.pem,妥善保管。

4.4 后端下单:APIv3 统一下单(JSAPI)

// 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 }
}

4.5 前端拉起支付

// 微信内 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()
  }
}
坑位提醒 ①:用户在支付弹窗点"取消"时,JS 会先回调 cancel 再回调 ok 与否。不应仅凭此状态判断"支付成功"——必须等 notify_url 的异步通知,或主动调用"查单接口"轮询确认。
PART 05

主路 B · H5(MWEB)支付:外部浏览器的"专属通道"

5.1 为什么必须再开一条路

JSAPI 强依赖 openid,但 openid 只有在微信内才有。用户在外部浏览器打开 H5 时根本不在微信内,没法走 JSAPI——这时就得用 H5 支付(MWEB),微信专门为外部浏览器场景开的接口。

5.2 链路原理

  1. 商户后端调 POST /v3/pay/transactions/h5,传入 scene_info.payer_client_ip 和 h5_info;
  2. 微信返回 h5_url(形如 https://wx.tenpay.com/...);
  3. 商户前端 window.location.href = h5_url,浏览器跳转到微信收银台;
  4. 微信通过 URL Scheme / Universal Links 自动唤起微信 APP;
  5. 用户在微信内输入密码 / 指纹完成支付;
  6. 微信将浏览器重定向回商户指定的 redirect_url(带状态参数);
  7. 与此同时,微信向商户 notify_url 发送真正的异步支付结果通知。

5.3 前置配置

1
开通 H5 支付权限

商户平台 → 产品中心 → H5 支付 → 申请开通,通常需要一定的网站 ICP 备案信息。

2
配置 H5 支付域名

商户平台 → 产品中心 → H5 支付 → 域名管理。域名必须完成 ICP 备案,支持子域名配置。referer 必须命中已配置的域名。

3
配置 redirect_url 域名白名单

回跳地址的根域名也必须在白名单中,否则微信会拒绝跳回。

4
iOS Universal Links(强烈建议)

不强制但强烈建议——iOS 9+ 后,scheme 跳转被沙箱限制,需要 Universal Links 才能稳定拉起微信 APP。

5.4 后端下单(APIv3 H5)

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' }
}

5.5 前端跳转

// 拿到后端返回的 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 头。
坑位提醒 ③:H5 支付不允许在微信内使用。微信内发起时 referer 会带 servicewechat.com,被风控直接拒绝;且微信内应优先走 JSAPI,体验远好于 MWEB。
PART 06

JSAPI vs H5(MWEB) 对比与选型

维度JSAPI 支付H5 支付(MWEB)
运行环境微信内置浏览器Safari / Chrome / QQ / UC 等外部浏览器
用户路径点击 → 弹窗 → 完成跳转 → 拉起微信 → 完成
用户体验极顺,无跳出中等,有跳转感
必传参数openidscene_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('请在微信中打开,或复制链接到浏览器')
  }
}
PART 07

接入全流程:从 0 到上线

1. 注册服务号 企业认证 2. 申请商户号 1~7 工作日 3. 绑定 AppID 商户平台授权 4. 配置域名 授权目录 / H5 域名 5. APIv3 密钥 + 商户证书 6. 后端对接 统一下单 + 查单 7. 前端分流 UA 路由 + 拉起 8. notify_url 签名验证 + 幂等 9. 沙箱测试 沙箱账号 10. 小额真测 0.01 元 11. 退款 + 对账 下载账单 / 调账 12. 上线运营 风控观察
图 7-1 接入 12 步路线(上中下三排分别对应:申请 → 对接 → 上线)

几个容易被卡住的"长耗时项"

PART 08

安全与签名:最容易被忽视的一环

8.1 APIv3 签名规则(下单必做)

对请求体做 SHA256-RSA2048 签名,放入 HTTP Header:

Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000001",
  nonce_str="随机串",timestamp="时间戳秒",
  serial_no="商户证书序列号",signature="Base64后的签名"

8.2 回调验签(发货依据)

微信向 notify_url POST 的报文头里会带:

Wechatpay-Timestamp: 时间戳
Wechatpay-Nonce: 随机串
Wechatpay-Signature: 签名值
Wechatpay-Serial: 平台证书序列号

验签流程:

  1. 从本地缓存找到 serial 对应的平台公钥证书(微信定期轮换,定期下载);
  2. 验签串 = timestamp\nnonce\nbody\n(注意 body 是原始字节);
  3. 用公钥对 signature 做 SHA256-RSA 验签;
  4. 校验通过后,处理订单逻辑;必须做幂等(微信可能重发);
  5. 返回 HTTP 200 + 特定 JSON 体,告诉微信"我收到了"。
铁律三连:① 验签不通过的回调必须返回 4xx,让微信重试,不要静默丢弃;② 解密的 resource.ciphertext 才是真正的业务字段;③ 商户证书要加密存储,绝不能放进前端 / Git 仓库。

8.3 幂等与对账

PART 09

踩坑清单:10 个最常见故障与排查

现象根因排查/修复
"当前页面的 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
PART 10

工具与代码模板

10.1 各语言 SDK 一览

语言推荐库说明
Node.jswechatpay-node-v3 / wechatpay-axios-plugin官方推荐思路,异步 API 支持完善
Javaweixin-java-pay公众号/小程序/APP/H5 全覆盖,Spring 友好
Pythonwechatpay-v3 / python-wechatpay社区主流,文档中文友好
PHPwechatpay-guzzle-middleware / yansongda/pay国内电商项目广泛使用
Gogo-wechatpay-golang轻量、纯 Go 实现

10.2 一段可直接抄走的下单模板(Node.js,带注释)

// 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: '成功' })
}

10.3 测试与上线建议

最后一句话:H5 接微信支付,本质上是"前端识别环境 + 后端两套下单 + 一套稳健回调"。把这三件事各做一遍,基本就接通了 95% 的场景。剩下 5% 的边界(风控 / 海外 / 子商户),那是另一份专题了。