# 六、本地支付联调前配置

第 5 章已经确认 web-pay 能在本地启动并登录运营平台。本章先在运营平台里创建商户和应用,把 `saas-starter` 后面调用 web-pay 所需的支付身份准备好;第 7 章再把这些值写入 SaaS 配置并启动 `saas-starter`。

```{important}
🎯 **本章目标:** 在 web-pay 运营平台中创建商户和应用,记录 `mchNo`、`appId`、`AppSecret`,并在资料齐全时配置支付宝 / 微信参数和支付通道。身份信息必须完成,支付通道可以等官方资料齐全后再补。
```

## 6.1 配置关系

本地联调时的关系是:

```text
saas-starter 业务订单
        │
        ▼
saas-starter 使用 mchNo + appId + AppSecret 调用 web-pay
        │
        ▼
web-pay 根据应用和支付通道参数请求微信 / 支付宝
        │
        ▼
支付平台回调 web-pay,web-pay 再通知 saas-starter
```

所以本章不是再启动服务,而是在运营平台里确认“哪个 SaaS 应用有权用哪个商户身份收款”。

```{note}
📌 如果第 5 章已经创建过商户、应用、支付参数和支付通道,本章可以当作复核清单来过一遍。重点确认记录值准确,而不是重复创建一套新商户或新应用。
```

需要先分清 3 类身份:

| 身份 | 从哪里来 | 用在哪里 |
| ---- | -------- | -------- |
| web-pay 商户号 `mchNo` | web-pay 运营平台商户列表 | `saas-starter` 调用 web-pay 时标识收款商户 |
| web-pay 应用 `appId` / `AppSecret` | web-pay 运营平台应用列表 | `saas-starter` 调用 web-pay 时签名和鉴权 |
| 微信 / 支付宝商户资料 | 微信支付商户平台、支付宝开放平台 | web-pay 代表真实商户请求支付平台 |

```{important}
🎯 **先把三类身份拆开记录。** `mchNo`、`appId`、`AppSecret` 是 SaaS 调用 web-pay 的身份;微信 / 支付宝资料是 web-pay 调支付平台的身份。它们会在同一条支付链路里同时出现,但来源和用途不同。
```

![web-pay 支付参数和支付通道两层关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-14-059-payment-layers.png)

## 6.2 创建商户

浏览器打开运营平台:

```text
http://localhost:8002
```

使用第 5 章的初始化账号登录后进入:

```text
商户管理 -> 商户列表 -> 新建
```

```{tip}
🎯 **先创建商户,再创建应用。** 商户代表“谁在收款”,应用代表“哪个业务系统要调用 web-pay”。
```

新增商户时重点填写这些字段:

| 字段 | 建议填写 |
| ---- | -------- |
| 商户名称 | 你的公司 |
| 登录名 | 6-18 位,字母开头,例如 `demo001` |
| 商户简称 | 收银台和订单里更短的展示名 |
| 联系人姓名 | 负责人姓名 |
| 联系人手机号 | 真实可用手机号,格式为 11 位 |
| 商户类型 | `普通商户` |
| 状态 | `启用` |

![web-pay 商户号和微信商户号不要混用](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-12-057-merchant-identity.png)

![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-03.png)

保存成功后,回到商户列表记录商户号:

| 要记录 | 在哪里看 | 后面用途 |
| ------ | -------- | -------- |
| 商户号 `mchNo` | 商户列表的「商户号」列 | 创建应用时要带上它;后面 `saas-starter` 调用 web-pay 时也要填它 |

这个商户号是 web-pay 自己生成的商户身份,可以理解成 web-pay 内部识别“哪个商户在收款”的编号。后面 `saas-starter` 发起支付时会把 `mchNo` 传给 web-pay,web-pay 再根据这个商户号找到对应的应用、支付参数和支付通道。

```{warning}
⚠️ **两个“商户号”不是同一个东西。** `mchNo` 是 web-pay 运营平台里的商户号;微信支付商户号来自微信支付商户平台。两者填错会让后面排查很痛苦。
```

## 6.3 创建应用

商户创建完成后,继续给商户创建应用。可以从两个入口进入:

```text
商户管理 -> 商户列表 -> 应用配置
```

也可以直接进入:

```text
商户管理 -> 应用列表
```

```{important}
🎯 **应用是 SaaS 调用 web-pay 的身份。** 后面 `saas-starter` 发起支付时,会带着这里的应用 AppId 和 AppSecret 请求 web-pay。
```

点击「新建」后重点填写:

| 字段 | 建议填写 |
| ---- | -------- |
| 商户号 | 从商户列表带入;如果是直接进入应用列表,就填写刚才创建的商户号 |
| 应用名称 | 当前 SaaS 或业务系统名称,例如 `SaaS Starter` |
| 状态 | `启用` |
| 私钥 AppSecret | 点击「随机生成私钥」生成 |
| 备注 | 可写这个应用对应哪个业务项目 |

「私钥 AppSecret」非常重要。它不是支付宝或微信的密钥,而是 web-pay 给这个业务应用使用的签名密钥。后面 `saas-starter` 请求 web-pay 创建订单、查询订单、接收回调结果时,会用它来签名或校验签名。

```{danger}
🔐 **AppSecret 只给后端使用。** 它不能写进前端 `.env`,也不要出现在公开截图、公开文档或聊天记录里。
```

点击「随机生成私钥」后,保存前先把 `AppSecret` 记录到你自己的本地私密记录里。不要放到前端 `.env`、公开文档、截图或聊天群里。

![web-pay 应用身份和 AppSecret 使用关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-13-058-app-identity.png)

![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-04.png)

保存后,回到应用列表记录这些值:

| 要记录 | 在哪里看 | 后面用途 |
| ------ | -------- | -------- |
| 商户号 `mchNo` | 应用列表的「商户号」列,应与 6.2 记录的一致 | `saas-starter` 调用 web-pay 时标识商户 |
| 应用 AppId `appId` | 应用列表的「应用AppId」列 | `saas-starter` 调用 web-pay 时标识具体业务应用 |
| 应用私钥 `AppSecret` | 新建应用时点击「随机生成私钥」得到 | `saas-starter` 请求签名和验签 |

```{warning}
⚠️ 这 3 个值要对应同一个应用,不要把 A 商户的 `mchNo` 和 B 应用的 `appId` 混在一起。
```

## 6.4 记录 SaaS 支付身份

把 6.2 和 6.3 记录的值先写到第 3 章准备的 `saas-starter-deploy-info.md` 里。第 7 章执行 `saas-starter/env-scripts/rename-saas-service.sh` 时,脚本会询问这 3 项并直接写入 `saas-starter` 的后端配置:

| 要记录 | 第 7 章脚本提示项 |
| ------ | ---------------- |
| 商户号 `mchNo` | `Zhcpay 商户号` |
| 应用 AppId `appId` | `Zhcpay AppID` |
| 应用私钥 `AppSecret` | `Zhcpay AppSecret` |

```{important}
📌 **这里记录的是给 SaaS 后端用的调用身份。** 第 7 章脚本会把它们写入 `saas-starter` 后端配置,让 SaaS 能创建 web-pay 支付订单并校验 web-pay 通知。
```

```{warning}
⚠️ 特别注意这 2 个值必须来自同一个应用:
```

```bash
ZHCPAY_APP_ID=刚才记录的应用AppId
ZHCPAY_APP_SECRET=刚才记录的应用AppSecret
```

```{warning}
⚠️ 不要把 B 应用的 `appId`、C 应用的 `AppSecret` 混在一起。混用后最常见的结果是:创建支付订单失败、验签失败、收银台没有可用通道,或者回调能进 web-pay 但通知不到业务系统。
```

如果后面已经启动过 SaaS 后端,重新运行第 7 章的配置脚本后,还需要停止并重新启动 SaaS 后端,让新的配置生效。

## 6.5 可选配置支付宝参数

如果你已经有支付宝开放平台资料,进入应用的支付配置后,在「支付宝官方」卡片点击「填写参数」。

```{note}
📌 支付宝参数是支付联调准备项,不是进入第 7 章的硬门槛。如果暂时没有真实应用资料,先保证 6.2 到 6.4 的 web-pay 商户和应用身份已经记录完整。
```

```{note}
📌 **这里填写的是支付宝开放平台应用资料。** 本教程主流程演示网站应用收款,所以优先填网站应用对应的 AppID、应用私钥和支付宝公钥。
```

这一步的目的:把支付宝开放平台中的应用身份和签名信息保存到 web-pay。保存后,web-pay 才知道调用支付宝接口时该用哪个 AppID、哪个私钥签名,以及该用哪个支付宝公钥校验返回结果。

重点字段按下面理解:

| 字段 | 填写什么 | 目的 |
| ---- | -------- | ---- |
| 状态 | 选择 `启用` | 告诉 web-pay 这个支付宝配置可以被使用 |
| 环境配置 | 本地真实付款测试选 `生产环境`;只连支付宝沙箱时选 `沙箱环境` | 决定 web-pay 请求支付宝正式接口还是沙箱接口 |
| 应用 AppID | 支付宝开放平台应用的 AppID | 标识当前支付宝应用 |
| 应用私钥 | 你自己生成的应用私钥 | web-pay 用它给支付请求签名 |
| 支付宝公钥 | 支付宝开放平台提供的支付宝公钥 | web-pay 用它校验支付宝通知和接口响应 |
| 接口签名方式 | 推荐选 `RSA2` | 使用支付宝当前推荐的签名算法 |
| 公钥证书 | 如果你使用证书模式就上传证书;普通公钥模式选择不使用证书 | 决定验签时使用证书还是普通公钥 |
| 是否开启加密 | 按支付宝应用配置保持一致 | 如果支付宝侧开启接口内容加密,这里也要开启并填写密钥 |

保存后先不要急着付款测试,还需要继续到「支付通道配置」里启用具体的支付宝付款方式。

![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-05.png)

## 6.6 可选配置微信参数

如果你已经有微信支付商户平台资料,回到支付参数配置页,在「微信支付官方」卡片点击「填写参数」。

```{note}
📌 微信参数也可以后补。没有商户号、APPID、API 密钥或证书文件时,不要先随便填占位值;占位值会让后面排查变得更像“配置成功但支付失败”。
```

```{note}
📌 **这里填写的是微信支付商户平台和微信应用资料。** 微信多种支付方式共用一套商户密钥和证书,但每种支付产品仍要在官方平台单独开通。
```

这一步的目的:把微信支付商户平台和微信应用里的信息保存到 web-pay。保存后,web-pay 才能向微信支付创建订单、查询订单,并在支付成功回调时完成验签。

重点字段按下面理解:

| 字段 | 填写什么 | 目的 |
| ---- | -------- | ---- |
| 状态 | 选择 `启用` | 告诉 web-pay 这个微信支付配置可以被使用 |
| 微信支付商户号 | 微信支付商户平台的商户号 | 标识收款商户 |
| 微信应用 APPID | 公众号、小程序或开放平台应用的 APPID | 标识发起支付的微信应用 |
| 应用 AppSecret | 微信应用后台的 AppSecret | 某些微信支付场景需要配合 APPID 使用 |
| 微信支付 API 版本 | 按你的商户配置选择 `V2` 或 `V3` | 决定 web-pay 使用哪套微信支付签名和证书规则 |
| APIv2 密钥 | 微信支付商户平台配置的 APIv2 Key | V2 接口签名和部分兼容场景会用到 |
| APIv3 秘钥 | 微信支付商户平台配置的 APIv3 Key | V3 接口解密回调和敏感数据时会用到 |
| 序列号 | 商户 API 证书序列号 | 微信支付用它识别你当前使用哪张商户证书 |
| API 证书 / 证书文件 / 私钥文件 | 从微信支付商户平台下载的商户证书文件 | web-pay 用它们完成请求签名 |
| 微信侧公钥 ID / 微信侧公钥证书 | 微信支付平台证书或公钥配置 | web-pay 用它校验微信支付返回的数据 |
| 微信转账版本 | 保持和微信支付平台要求一致,截图中选择 `新版202501` | 只影响微信转账相关能力,普通收款场景先按当前配置保存 |

新手可以先记住一个判断方法:

- 商户号、APPID、AppSecret 用来说明“我是谁”。
- API 密钥、证书、序列号用来证明“请求确实是我发的”。
- 微信侧公钥或平台证书用来确认“返回结果确实是微信发的”。

如果只是先跑通收款,优先保证商户号、APPID、APIv3 密钥、商户证书、商户私钥、平台公钥 / 证书这些核心信息正确。保存成功后,再去启用具体的微信支付通道。

微信证书文件要特别保管。运营平台这里要上传的 4 个文件分别是:

```{danger}
🔐 **这 4 个文件非常重要。** 它们不是普通附件,而是后端请求微信支付、校验回调和完成安全接口调用时要读取的证书 / 私钥文件。
```

| 文件 | 上传到哪个字段 | 作用 |
| ---- | -------------- | ---- |
| `apiclient_cert.p12` | `API证书(apiclient_cert.p12)` | V2 退款等安全接口可能会用到 |
| `apiclient_cert.pem` | `证书文件(apiclient_cert.pem)` | 商户证书身份校验 |
| `apiclient_key.pem` | `私钥文件(apiclient_key.pem)` | 后端发起 V3 请求签名 |
| `pub_key.pem` | `微信侧公钥证书(pub_key.pem)` | 后端校验微信支付回调签名 |

本地测试时,这些文件通过运营平台上传后会保存到:

```text
tmp/local-test/upload/private/cert
```

正式上线后,也要把这 4 个文件上传到云服务器的私有证书目录。当前生产配置默认使用:

```text
/www/wwwroot/zhcpay/uploads/private/cert
```

如果你后面改过 `isys.oss.file-private-path`,就以线上实际配置的私有目录为准。无论本地还是线上,微信 API 密钥、证书序列号、证书文件和私钥文件都不能暴露或公开,不要提交到公开仓库,不要放进前端目录,也不要出现在公开截图里。

![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-06.png)
![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-07.png)

## 6.7 可选启用支付通道

支付参数保存后,点击页面顶部的「下一步」进入「支付通道配置」。

```{important}
🎯 **支付窗口决定用户能看到什么付款方式。** 支付参数配置正确只是“后端具备能力”,通道开启后收银台才会展示对应入口。
```

列表里的每一行都是一种支付方式:

| 支付方式代码 | 支付方式名称 | 适合场景 |
| ------------ | ------------ | -------- |
| `ALI_QR` | 支付宝二维码 | 用户用支付宝扫码付款,适合本地联调和电脑网页收款 |
| `ALI_PC` | 支付宝 PC 网站 | 用户在电脑浏览器跳转到支付宝付款 |
| `ALI_WAP` | 支付宝 WAP | 用户在手机浏览器里打开付款 |
| `ALI_APP` | 支付宝 APP | 手机 App 内调起支付宝付款 |
| `WX_NATIVE` | 微信扫码 | 用户用微信扫码付款,适合本地联调和电脑网页收款 |
| `WX_JSAPI` | 微信公众号 | 用户在微信内网页付款 |
| `WX_APP` | 微信 APP | 手机 App 内调起微信付款 |
| `WX_H5` | 微信 H5 | 手机浏览器内调起微信支付 |

```{warning}
⚠️ **官方未开通,这里开启也不会生效。** 这里的「启用」只是 web-pay 内部开关,真正能不能收款还要看微信 / 支付宝官方产品权限。
```

本地从零开始测试时,建议先只启用最容易验证的通道:

- 测支付宝扫码:配置并启用 `ALI_QR`。
- 测微信扫码:配置并启用 `WX_NATIVE`。

点击某一行右侧的「配置」后,在弹出的通道卡片里确认:

| 字段 | 建议 | 目的 |
| ---- | ---- | ---- |
| 状态 | 确认为 `已启用` | 表示这个通道已经可以被 web-pay 使用 |
| 费率 | 按实际费率填写,例如 `0.6` 代表 0.6% | 用于系统展示或内部记录通道成本 |
| 启用开关 | 打开 | 让收银台真正展示这个付款方式 |

```{tip}
💡 不要一次性把所有通道都打开。每个通道对应的支付宝 / 微信产品权限、APPID 类型、域名要求都可能不同。先用二维码通道跑通一条完整支付链路,确认能下单、付款、回调、改订单状态后,再逐个打开其他通道,排查会简单很多。
```

![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-08.png)
![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-09.png)
![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-10.png)

## 6.8 配置完成后检查

离开运营平台前,先把下面这些信息整理到自己的本地私密记录里。后面第 9 章会反复用到。

| 要确认 | 应该是什么状态 | 是否必达 |
| ------ | -------------- | -------- |
| 商户号 `mchNo` | 已从商户列表记录 | 必达 |
| 应用 AppId `appId` | 已从应用列表记录 | 必达 |
| 应用私钥 `AppSecret` | 已在新建应用时记录 | 必达 |
| `saas-starter-deploy-info.md` | 已记录同一组 `mchNo`、`appId`、`AppSecret`,供第 7 章配置脚本填写 | 必达 |
| 支付参数 | 支付宝或微信资料齐全时保存并启用 | 可后补 |
| 支付通道 | 至少启用 `ALI_QR` 或 `WX_NATIVE` | 可后补 |

![web-pay 配置完成后的本地记录检查](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-15-0510-final-check.png)

```{note}
📌 如果你现在还没有微信或支付宝真实资料,也可以先继续整理第 8 章的 web-pay 线上部署。等官方资料齐全后,再回到本章补支付参数和支付通道,然后进入第 9 章做真实支付闭环。
```

```{important}
✅ **本章完成标准:** 至少要完成商户、应用、`mchNo`、`appId`、`AppSecret` 的记录。支付宝 / 微信参数与通道属于支付联调前置项,资料齐全时再配置即可。
```

```{seealso}
➡️ 下一步进入第 7 章,把这里记录的 `mchNo`、`appId`、`AppSecret` 写入 `saas-starter`,先验证 SaaS 自己能本地启动、连接业务库并创建匿名会话。
```