UniApp H5 端接入微信支付完整指南

在 UniApp 中开发 H5 应用并接入微信支付时,需要根据用户访问的环境区分两种主要场景:微信内网页(JSAPI 支付) 和 微信外浏览器(H5 支付)。两者的配置、技术实现和用户体验都有较大差异。本文档将详细说明这两种场景的接入流程,并总结关键注意事项,帮助开发者顺利完成支付集成。

---

目录

• 场景一:微信内网页(JSAPI 支付)
• 场景二:微信外浏览器(H5 支付)
• 关键步骤总结与注意事项
• 常见问题解答

---

场景一:微信内网页(JSAPI 支付)

用户在微信客户端内打开 H5 页面,调起微信支付控件完成支付。这是最常见且体验最流畅的支付方式。

1. 前期准备与配置

1.1 必备账号

账号类型	用途	获取内容
微信服务号	公众号平台	AppID
微信商户号	支付平台	商户号 mch_id

⚠️ 注意:服务号需要已认证,并在商户平台将服务号与商户号绑定。

1.2 配置网页授权域名

在公众号后台「设置与开发」→「公众号设置」→「功能设置」中,配置网页授权域名。

• 该域名用于获取用户的 OpenID
• 必须与你的 H5 页面域名一致

1.3 设置支付授权目录

在微信商户平台「产品中心」→「开发配置」中,添加 JSAPI 支付授权目录。

**示例:**如果你的支付页面为 https://yourdomain.com/pay,则授权目录应设置为:

https://yourdomain.com/pay/

⚠️ 微信会校验发起支付的页面 URL 是否在此目录下。

2. 技术实现流程

① 引入微信 JS-SDK

虽然支付主要使用 wx.chooseWXPay,但建议先进行 JS-SDK 权限验证配置,确保环境可靠。

安装方式:

• 安装 jweixin-module 或通过 <script> 标签引入
• 通过后端获取签名等信息,调用 wx.config 注入权限

② 获取用户 OpenID

在用户进入支付页面前,需要通过微信网页授权机制(OAuth2.0)获取用户的唯一标识 openid。

流程:

1. 引导用户跳转至微信授权 URL
2. 授权后微信会重定向至回调页面并附带 code 参数
3. 后端通过 code 换取 openid 并返回给前端

// 授权 URL 示例
https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_base&state=STATE#wechat_redirect

⚠️ openid 是后续统一下单接口的必传参数。

③ 后端统一下单

后端服务器调用微信支付统一下单接口,获取预支付会话标识 prepay_id。

API 地址(V3版):

POST https://api.mch.weixin.qq.com/v3/combine-transactions/jsapi

请求参数:

参数	说明
appid	公众号 AppID
mchid	商户号
openid	用户唯一标识
out_trade_no	商户订单号
total_fee	订单金额
body	商品描述

成功后会返回 prepay_id。

④ 前端调起支付

后端拿到 prepay_id 后,按 JSAPI 支付规则生成签名等参数,返回给前端。前端调用 wx.chooseWXPay 拉起支付控件。

// 前端示例代码
wx.chooseWXPay({
    timestamp: 1741171200,            // 后端返回的时间戳
    nonceStr: "随机字符串",            // 后端返回的随机串
    package: "prepay_id=xxx",          // 后端返回的prepay_id
    signType: "RSA",                   // 签名类型,与后端下单时一致
    paySign: "签名值",                  // 后端生成的签名
    success: function (res) {
        // 支付成功(仅表示调起成功,最终结果以后端通知为准)
    },
    fail: function (err) {
        // 支付失败或用户取消
    }
});

---

场景二:微信外浏览器(H5 支付)

用户在手机自带浏览器、QQ、百度等非微信内置浏览器中打开 H5 页面,需要跳转到微信 App 完成支付。

1. 前期准备与配置

1.1 开通 H5 支付权限

在微信商户平台「产品中心」→「我的产品」中申请开通「H5 支付」功能。

⚠️ 该功能主要面向企业资质商户,审核较严,建议优先使用 JSAPI 支付。

1.2 设置 H5 支付域名

在商户平台「产品中心」→「开发配置」中,添加 H5 支付域名。

• 这是你发起支付的网页所对应的顶级域名
• 必须通过 ICP 备案

2. 技术实现流程

① 后端统一下单获取支付链接

后端调用微信 H5 支付统一下单接口,获取支付跳转链接 h5_url。

API 地址(V3版):

POST https://api.mch.weixin.qq.com/v3/combine-transactions/h5

请求参数:

参数	说明
appid	公众号 AppID
mchid	商户号
out_trade_no	商户订单号
total_fee	订单金额
body	商品描述
client_ip	用户客户端 IP
h5_info	场景信息(含 type、app_name、app_url)

成功返回 h5_url 字段,例如: https://wx.tenpay.com/...

② 前端重定向到支付链接

前端从后端获取 h5_url,直接通过 window.location.href 进行跳转。该链接会在当前浏览器打开一个中间页,然后自动拉起微信 App。

// 前端重定向
window.location.href = h5_url;

③ 处理支付返回

用户完成支付后,默认会返回到拉起支付前的页面。可以在下单时通过拼接 redirect_url 参数(部分接口支持)指定支付完成后的自定义跳转地址。

💡 返回后,建议通过主动查询订单状态来确认最终结果。

---

关键步骤总结与注意事项

1. 两种场景对比

对比项	微信内网页 (JSAPI 支付)	微信外浏览器 (H5 支付)
核心配置	公众号网页授权域名 + 商户平台支付授权目录	商户平台开通 H5 支付并设置 H5 支付域名
前端技术	调用 wx.chooseWXPay(需引入微信 JS-SDK)	后端返回 h5_url,前端重定向跳转
用户标识	必须获取用户的 openid	无需 openid,但需获取用户 IP 和 UserAgent
难点	配置繁琐,需处理网页授权	功能申请门槛高,支付跳转流程较长

2. ⚠️ 通用注意事项

🔐 安全第一

• 所有涉及金额、签名的操作必须在后端完成
• 严禁在前端计算签名或暴露密钥
• 下单参数中的金额、商品信息应由后端生成,防止篡改

✅ 支付结果确认

• 前端 wx.chooseWXPay 的 success 回调仅代表调起支付成功
• 不代表资金已到账
• 最终订单状态必须以后端接收到的微信支付异步通知(webhook)为准,并更新订单状态

📱 UniApp 适配

• UniApp 的 uni.requestPayment API 在 H5 端不会自动转换为 JSAPI 或 H5 支付
• 需要开发者自行根据环境编写上述逻辑
• 建议在支付页面通过 navigator.userAgent 判断当前是否在微信内,从而选择对应支付流程

🧪 测试环境

• 可使用微信官方提供的沙箱环境(如 V2 版的沙箱)进行支付流程测试
• 避免产生真实交易
• 测试时需使用真机,模拟器可能无法正常调起微信支付

---

常见问题解答

Q1: 如何判断当前环境是在微信内还是微信外?

function isWechat() {
    const ua = navigator.userAgent.toLowerCase();
    return ua.indexOf('micromessenger') !== -1;
}

Q2: 支付回调的 success 可以作为支付成功的依据吗?

❌ 不可以。前端回调仅表示用户完成了支付操作(或取消了支付),最终结果以后端的异步通知为准。

Q3: H5 支付可以自定义返回 URL 吗?

部分接口支持在下单时拼接 redirect_url 参数,但并非所有情况都支持。建议用户返回后主动查询订单状态。

Q4: 如何测试支付功能?

• 使用微信沙箱环境(V2 版)
• 使用真机测试,模拟器可能无法正常调起
• 使用小额订单进行测试

---

结语

微信 H5 支付接入的关键在于分清场景、准确配置、安全实现。无论是 JSAPI 支付还是 H5 支付,都需严格遵守微信官方文档,确保用户体验和资金安全。

如果在实际开发中遇到具体问题(如签名生成、网页授权调试等),建议查阅微信支付官方技术文档或咨询微信支付技术支持。

希望本文档能帮助你在 UniApp 项目中顺利集成微信支付! 🎉

---

更新日期: 2026-03-05