小程序 web-view 商户转账对接文档

# 小程序 web-view 商户转账对接文档

## 背景
商家转账用户确认模式下，在微信客户端通过小程序或H5拉起页面请求用户确认收款。*在微信H5环境 易企秀已经自行处理领取，对接方无需关注*。
但是如果是小程序嵌入，需要小程序原生页面来实现，所以需要一定的小程序开发

`cnWxHelper.requestMerchantTransfer` 依赖微信公众号 H5 环境下的 `WeixinJSBridge`。当 H5 页面被嵌入到**小程序 `<web-view>`** 中打开时，这套接口不可用，用户点击会没有任何响应。

解决方案：H5 在识别到小程序 web-view 环境后，跳转到宿主小程序的一个「中转页」，由中转页在小程序上下文中调用 `wx.requestMerchantTransfer` 完成领取。

本文档描述**双方对接协议**：

- **H5 侧**：设置全局变量，让 易企秀 知道确认收款页面地址。
- **小程序侧**：中转页如何接收参数并调起领取。

---

## 一、H5 侧：设置全局变量

在业务代码里，把小程序中转页的路径写入全局变量即可（**无需修改业务调用代码**）：

```js
// 小程序中转页的 path（必须以 "/" 开头，指向宿主小程序的一个 tabBar 外页面）
window.__MP_MERCHANT_TRANSFER_URL__ = '/pages/merchant-transfer/index'
```

![配置示例](/media/202607/2026-07-17_141947_0203590.9131736355494292.png)

### URL 拼接格式（重要）

H5 侧跳到小程序的 URL 格式**固定**如下：

```
<中转页 path>?mchId=<mchId>&appId=<appId>&package=<encodeURIComponent(packageInfo)>
```

规则：

- 中转页 path 已含 `?` 时，自动改用 `&` 连接
- `mchId`、`appId` 原样拼接，不做 encode
- `package` 一定 **`encodeURIComponent`** —— 因为 `packageInfo` 内包含 `=` `&` 等字符，不 encode 会破坏 query 结构
- 参数名大小写固定：`mchId` / `appId` / `package`（**不是 `packageInfo`**）

小程序侧接收参数时按上述字段名和 encode 规则处理。

---

## 二、小程序侧对接

### 2.1 中转页结构

在宿主小程序里新建一个页面（示例路径 `/pages/merchant-transfer/index`），职责：

1. `onLoad` 里从 `options` 读取参数
2. 调用 `wx.requestMerchantTransfer` 发起领取
3. 领取完成后回到上一页（或按业务需要跳转）

### 2.2 页面代码示例

**`pages/merchant-transfer/index.js`**：

```js
Page({
    data: {
        status: 'loading' // loading | success | fail
    },

onLoad(options) {
        // 1. 参数解析
        //    注意：options.package 是被 encodeURIComponent 过的，小程序框架
        //    通常会自动 decode 一次，但为稳妥起见做一次容错 decode。
        const mchId = options.mchId
        const appId = options.appId
        let pkg = options.package || ''
        try {
            // 若已经是明文（含 =），decode 会抛错，此时保留原值
            if (pkg.indexOf('%') >= 0) pkg = decodeURIComponent(pkg)
        } catch (e) {
            // ignore
        }

if (!mchId || !appId || !pkg) {
            this.setData({ status: 'fail' })
            wx.showToast({ title: '参数缺失', icon: 'none' })
            return
        }

// 2. 调起微信商户转账
        //    官方 API：wx.requestMerchantTransfer
        //    文档：https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestMerchantTransfer.html
        //    参数字段与 JSSDK 的 requestMerchantTransfer 保持一致：mchId / appId / package
        wx.requestMerchantTransfer({
            mchId: mchId,
            appId: appId,
            package: pkg,
            success: (res) => {
                // res.err_msg === 'requestMerchantTransfer:ok' 表示用户完成了确认流程
                // 注意：这不代表钱一定到账，最终结果以后端回调为准
                this.setData({ status: 'success' })
                    // 3. 领取完成后回到 web-view 页
                setTimeout(() => wx.navigateBack({ delta: 1 }), 500)
            },
            fail: (err) => {
                this.setData({ status: 'fail' })
            }
        })
    },

})
```

**`pages/merchant-transfer/index.wxml`**（简单占位即可，页面很快就 navigateBack 走了）：

```xml
<view class="loading" wx:if="{{status === 'loading'}}">正在打开领取页...</view>
<view class="tip" wx:if="{{status === 'fail'}}">打开失败，请返回重试</view>
```

**`pages/merchant-transfer/index.json`**：

```json
{
    "navigationBarTitleText": "领取转账",
    "usingComponents": {}
}
```

### 2.3 小程序 app.json 注册页面

```json
{
    "pages": [
        "pages/index/index",
        "pages/merchant-transfer/index"
    ]
}
```

### 2.4 `wx.requestMerchantTransfer` 前置要求

- 小程序基础库版本 ≥ **3.7.9**（`wx.requestMerchantTransfer` 从该版本开始支持，低版本请做兼容判断或提示升级微信）
- 小程序需**开通"商家转账到零钱"**能力，且当前小程序的 `appId` 与 H5 传入的 `appId` 一致
- `mchId` 必须是有效的商户号，且与小程序 appId 绑定
- `package` 是后端下单接口返回的、经过签名的字符串，H5 需原样透传，中间任何一环**不能重新签名或修改**
- 官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestMerchantTransfer.html

---

## 四、常见问题

**Q: H5 页面在小程序里点击按钮没反应，也没跳转？**

A: 打开控制台看是否有 `requestMerchantTransfer is not supported in miniprogram webview` 报错。有的话说明 `window.__MP_MERCHANT_TRANSFER_URL__` 没设置或值为空。

**Q: 跳到中转页了，但 `wx.requestMerchantTransfer` 报 `errMsg: requestMerchantTransfer:fail`？**

A: 依次排查：
1. 小程序基础库 < 3.7.9
2. 小程序未开通商家转账能力
3. `package` 被 URL 传输过程中破坏（未 encode 或多次 encode）—— 在中转页打印 `pkg` 与后端原文比对
4. `appId` 与小程序自身 appId 不一致

**Q: `mchId` 和 `appId` 是同一个 appId 吗？**

A: 不是。`appId` 是**小程序或公众号的 appId**（业务身份），`mchId` 是**商户号**（收款主体）。两者由后端下单接口一起返回，H5 只做透传。