六、本地支付联调前配置
第 5 章已经确认 web-pay 能在本地启动并登录运营平台。本章先在运营平台里创建商户和应用,把 saas-starter 后面调用 web-pay 所需的支付身份准备好;第 7 章再把这些值写入 SaaS 配置并启动 saas-starter。
重要
🎯 本章目标: 在 web-pay 运营平台中创建商户和应用,记录 mchNo、appId、AppSecret,并在资料齐全时配置支付宝 / 微信参数和支付通道。身份信息必须完成,支付通道可以等官方资料齐全后再补。
6.1 配置关系
本地联调时的关系是:
saas-starter 业务订单
│
▼
saas-starter 使用 mchNo + appId + AppSecret 调用 web-pay
│
▼
web-pay 根据应用和支付通道参数请求微信 / 支付宝
│
▼
支付平台回调 web-pay,web-pay 再通知 saas-starter
所以本章不是再启动服务,而是在运营平台里确认“哪个 SaaS 应用有权用哪个商户身份收款”。
备注
📌 如果第 5 章已经创建过商户、应用、支付参数和支付通道,本章可以当作复核清单来过一遍。重点确认记录值准确,而不是重复创建一套新商户或新应用。
需要先分清 3 类身份:
| 身份 | 从哪里来 | 用在哪里 |
|---|---|---|
web-pay 商户号 mchNo |
web-pay 运营平台商户列表 | saas-starter 调用 web-pay 时标识收款商户 |
web-pay 应用 appId / AppSecret |
web-pay 运营平台应用列表 | saas-starter 调用 web-pay 时签名和鉴权 |
| 微信 / 支付宝商户资料 | 微信支付商户平台、支付宝开放平台 | web-pay 代表真实商户请求支付平台 |
重要
🎯 先把三类身份拆开记录。 mchNo、appId、AppSecret 是 SaaS 调用 web-pay 的身份;微信 / 支付宝资料是 web-pay 调支付平台的身份。它们会在同一条支付链路里同时出现,但来源和用途不同。
6.2 创建商户
浏览器打开运营平台:
http://localhost:8002
使用第 5 章的初始化账号登录后进入:
商户管理 -> 商户列表 -> 新建
小技巧
🎯 先创建商户,再创建应用。 商户代表“谁在收款”,应用代表“哪个业务系统要调用 web-pay”。
新增商户时重点填写这些字段:
| 字段 | 建议填写 |
|---|---|
| 商户名称 | 你的公司 |
| 登录名 | 6-18 位,字母开头,例如 demo001 |
| 商户简称 | 收银台和订单里更短的展示名 |
| 联系人姓名 | 负责人姓名 |
| 联系人手机号 | 真实可用手机号,格式为 11 位 |
| 商户类型 | 普通商户 |
| 状态 | 启用 |
保存成功后,回到商户列表记录商户号:
| 要记录 | 在哪里看 | 后面用途 |
|---|---|---|
商户号 mchNo |
商户列表的「商户号」列 | 创建应用时要带上它;后面 saas-starter 调用 web-pay 时也要填它 |
这个商户号是 web-pay 自己生成的商户身份,可以理解成 web-pay 内部识别“哪个商户在收款”的编号。后面 saas-starter 发起支付时会把 mchNo 传给 web-pay,web-pay 再根据这个商户号找到对应的应用、支付参数和支付通道。
警告
⚠️ 两个“商户号”不是同一个东西。 mchNo 是 web-pay 运营平台里的商户号;微信支付商户号来自微信支付商户平台。两者填错会让后面排查很痛苦。
6.3 创建应用
商户创建完成后,继续给商户创建应用。可以从两个入口进入:
商户管理 -> 商户列表 -> 应用配置
也可以直接进入:
商户管理 -> 应用列表
重要
🎯 应用是 SaaS 调用 web-pay 的身份。 后面 saas-starter 发起支付时,会带着这里的应用 AppId 和 AppSecret 请求 web-pay。
点击「新建」后重点填写:
| 字段 | 建议填写 |
|---|---|
| 商户号 | 从商户列表带入;如果是直接进入应用列表,就填写刚才创建的商户号 |
| 应用名称 | 当前 SaaS 或业务系统名称,例如 SaaS Starter |
| 状态 | 启用 |
| 私钥 AppSecret | 点击「随机生成私钥」生成 |
| 备注 | 可写这个应用对应哪个业务项目 |
「私钥 AppSecret」非常重要。它不是支付宝或微信的密钥,而是 web-pay 给这个业务应用使用的签名密钥。后面 saas-starter 请求 web-pay 创建订单、查询订单、接收回调结果时,会用它来签名或校验签名。
危险
🔐 AppSecret 只给后端使用。 它不能写进前端 .env,也不要出现在公开截图、公开文档或聊天记录里。
点击「随机生成私钥」后,保存前先把 AppSecret 记录到你自己的本地私密记录里。不要放到前端 .env、公开文档、截图或聊天群里。
保存后,回到应用列表记录这些值:
| 要记录 | 在哪里看 | 后面用途 |
|---|---|---|
商户号 mchNo |
应用列表的「商户号」列,应与 6.2 记录的一致 | saas-starter 调用 web-pay 时标识商户 |
应用 AppId appId |
应用列表的「应用AppId」列 | saas-starter 调用 web-pay 时标识具体业务应用 |
应用私钥 AppSecret |
新建应用时点击「随机生成私钥」得到 | saas-starter 请求签名和验签 |
警告
⚠️ 这 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 |
重要
📌 这里记录的是给 SaaS 后端用的调用身份。 第 7 章脚本会把它们写入 saas-starter 后端配置,让 SaaS 能创建 web-pay 支付订单并校验 web-pay 通知。
警告
⚠️ 特别注意这 2 个值必须来自同一个应用:
ZHCPAY_APP_ID=刚才记录的应用AppId
ZHCPAY_APP_SECRET=刚才记录的应用AppSecret
警告
⚠️ 不要把 B 应用的 appId、C 应用的 AppSecret 混在一起。混用后最常见的结果是:创建支付订单失败、验签失败、收银台没有可用通道,或者回调能进 web-pay 但通知不到业务系统。
如果后面已经启动过 SaaS 后端,重新运行第 7 章的配置脚本后,还需要停止并重新启动 SaaS 后端,让新的配置生效。
6.5 可选配置支付宝参数
如果你已经有支付宝开放平台资料,进入应用的支付配置后,在「支付宝官方」卡片点击「填写参数」。
备注
📌 支付宝参数是支付联调准备项,不是进入第 7 章的硬门槛。如果暂时没有真实应用资料,先保证 6.2 到 6.4 的 web-pay 商户和应用身份已经记录完整。
备注
📌 这里填写的是支付宝开放平台应用资料。 本教程主流程演示网站应用收款,所以优先填网站应用对应的 AppID、应用私钥和支付宝公钥。
这一步的目的:把支付宝开放平台中的应用身份和签名信息保存到 web-pay。保存后,web-pay 才知道调用支付宝接口时该用哪个 AppID、哪个私钥签名,以及该用哪个支付宝公钥校验返回结果。
重点字段按下面理解:
| 字段 | 填写什么 | 目的 |
|---|---|---|
| 状态 | 选择 启用 |
告诉 web-pay 这个支付宝配置可以被使用 |
| 环境配置 | 本地真实付款测试选 生产环境;只连支付宝沙箱时选 沙箱环境 |
决定 web-pay 请求支付宝正式接口还是沙箱接口 |
| 应用 AppID | 支付宝开放平台应用的 AppID | 标识当前支付宝应用 |
| 应用私钥 | 你自己生成的应用私钥 | web-pay 用它给支付请求签名 |
| 支付宝公钥 | 支付宝开放平台提供的支付宝公钥 | web-pay 用它校验支付宝通知和接口响应 |
| 接口签名方式 | 推荐选 RSA2 |
使用支付宝当前推荐的签名算法 |
| 公钥证书 | 如果你使用证书模式就上传证书;普通公钥模式选择不使用证书 | 决定验签时使用证书还是普通公钥 |
| 是否开启加密 | 按支付宝应用配置保持一致 | 如果支付宝侧开启接口内容加密,这里也要开启并填写密钥 |
保存后先不要急着付款测试,还需要继续到「支付通道配置」里启用具体的支付宝付款方式。
6.6 可选配置微信参数
如果你已经有微信支付商户平台资料,回到支付参数配置页,在「微信支付官方」卡片点击「填写参数」。
备注
📌 微信参数也可以后补。没有商户号、APPID、API 密钥或证书文件时,不要先随便填占位值;占位值会让后面排查变得更像“配置成功但支付失败”。
备注
📌 这里填写的是微信支付商户平台和微信应用资料。 微信多种支付方式共用一套商户密钥和证书,但每种支付产品仍要在官方平台单独开通。
这一步的目的:把微信支付商户平台和微信应用里的信息保存到 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 个文件分别是:
危险
🔐 这 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) |
后端校验微信支付回调签名 |
本地测试时,这些文件通过运营平台上传后会保存到:
tmp/local-test/upload/private/cert
正式上线后,也要把这 4 个文件上传到云服务器的私有证书目录。当前生产配置默认使用:
/www/wwwroot/zhcpay/uploads/private/cert
如果你后面改过 isys.oss.file-private-path,就以线上实际配置的私有目录为准。无论本地还是线上,微信 API 密钥、证书序列号、证书文件和私钥文件都不能暴露或公开,不要提交到公开仓库,不要放进前端目录,也不要出现在公开截图里。
6.7 可选启用支付通道
支付参数保存后,点击页面顶部的「下一步」进入「支付通道配置」。
重要
🎯 支付窗口决定用户能看到什么付款方式。 支付参数配置正确只是“后端具备能力”,通道开启后收银台才会展示对应入口。
列表里的每一行都是一种支付方式:
| 支付方式代码 | 支付方式名称 | 适合场景 |
|---|---|---|
ALI_QR |
支付宝二维码 | 用户用支付宝扫码付款,适合本地联调和电脑网页收款 |
ALI_PC |
支付宝 PC 网站 | 用户在电脑浏览器跳转到支付宝付款 |
ALI_WAP |
支付宝 WAP | 用户在手机浏览器里打开付款 |
ALI_APP |
支付宝 APP | 手机 App 内调起支付宝付款 |
WX_NATIVE |
微信扫码 | 用户用微信扫码付款,适合本地联调和电脑网页收款 |
WX_JSAPI |
微信公众号 | 用户在微信内网页付款 |
WX_APP |
微信 APP | 手机 App 内调起微信付款 |
WX_H5 |
微信 H5 | 手机浏览器内调起微信支付 |
警告
⚠️ 官方未开通,这里开启也不会生效。 这里的「启用」只是 web-pay 内部开关,真正能不能收款还要看微信 / 支付宝官方产品权限。
本地从零开始测试时,建议先只启用最容易验证的通道:
测支付宝扫码:配置并启用
ALI_QR。测微信扫码:配置并启用
WX_NATIVE。
点击某一行右侧的「配置」后,在弹出的通道卡片里确认:
| 字段 | 建议 | 目的 |
|---|---|---|
| 状态 | 确认为 已启用 |
表示这个通道已经可以被 web-pay 使用 |
| 费率 | 按实际费率填写,例如 0.6 代表 0.6% |
用于系统展示或内部记录通道成本 |
| 启用开关 | 打开 | 让收银台真正展示这个付款方式 |
小技巧
💡 不要一次性把所有通道都打开。每个通道对应的支付宝 / 微信产品权限、APPID 类型、域名要求都可能不同。先用二维码通道跑通一条完整支付链路,确认能下单、付款、回调、改订单状态后,再逐个打开其他通道,排查会简单很多。
6.8 配置完成后检查
离开运营平台前,先把下面这些信息整理到自己的本地私密记录里。后面第 9 章会反复用到。
| 要确认 | 应该是什么状态 | 是否必达 |
|---|---|---|
商户号 mchNo |
已从商户列表记录 | 必达 |
应用 AppId appId |
已从应用列表记录 | 必达 |
应用私钥 AppSecret |
已在新建应用时记录 | 必达 |
saas-starter-deploy-info.md |
已记录同一组 mchNo、appId、AppSecret,供第 7 章配置脚本填写 |
必达 |
| 支付参数 | 支付宝或微信资料齐全时保存并启用 | 可后补 |
| 支付通道 | 至少启用 ALI_QR 或 WX_NATIVE |
可后补 |
备注
📌 如果你现在还没有微信或支付宝真实资料,也可以先继续整理第 8 章的 web-pay 线上部署。等官方资料齐全后,再回到本章补支付参数和支付通道,然后进入第 9 章做真实支付闭环。
重要
✅ 本章完成标准: 至少要完成商户、应用、mchNo、appId、AppSecret 的记录。支付宝 / 微信参数与通道属于支付联调前置项,资料齐全时再配置即可。
参见
➡️ 下一步进入第 7 章,把这里记录的 mchNo、appId、AppSecret 写入 saas-starter,先验证 SaaS 自己能本地启动、连接业务库并创建匿名会话。