深浅模式
微信支付（完整配置手册）
本篇从 微信商户平台 到 灵萌管理后台 到 客户端验收，逐步说明如何开通微信支付、配置回调、处理提现打款。
后台入口： 系统设置 → 系统配置 → 微信支付 Tab
前置条件
- 站点 HTTPS 已配置，域名与 网站信息 / 初始化向导 网站地址 一致
- 支付 模块已在 系统设置 → 我的模块 中开通
- 小程序 AppID 已在商户平台与商户号 绑定
一、整体流程概览
text
1. 注册微信支付商户号（企业资质）
2. 商户平台绑定小程序 AppID
3. 申请 API 证书、设置 APIv3 密钥
4. 配置支付通知 URL（回调）
5. 灵萌后台填写商户号、密钥、证书
6. 区域/业务侧开启付费能力
7. 0.01 元测试单验收
8. （可选）申请商家转账 → 填转账场景 ID → 提现自动打款二、微信商户平台操作（逐步）
登录 微信支付商户平台
2.1 确认商户号
路径：账户中心 → 商户信息
记下 商户号（10 位数字），填入灵萌后台 商户号 字段。
2.2 绑定 AppID
路径：产品中心 → AppID账号管理 → 关联AppID
| 步骤 | 操作 |
|---|---|
| 1 | 点击 关联 AppID |
| 2 | 填写小程序 AppID（与 系统配置 → 微信小程序 一致） |
| 3 | 小程序管理员扫码确认 |
未绑定则无法支付
AppID 与商户号主体可以不同，但必须在此完成关联。
2.3 设置 APIv3 密钥
路径：账户中心 → API安全 → 设置APIv3密钥
- 设置 32 位密钥，妥善保存
- 填入灵萌 支付密钥 字段（页面提示 v2/v3，按实际接入填 APIv3 密钥）
2.4 申请 API 证书
路径：账户中心 → API安全 → 申请API证书
下载后得到：
| 文件 | 对应灵萌字段 |
|---|---|
apiclient_cert.pem | CERT 证书（完整粘贴含 BEGIN/END 行） |
apiclient_key.pem | KEY 密钥（商户私钥） |
同时记录 证书序列号 → 填入 v3 证书序列号。
2.5 设置支付回调 URL
路径：产品中心 → 开发配置 → 支付配置
找到 Native支付 / JSAPI支付 等已开通产品的 支付通知URL，填写：
text
https://你的域名/api/payment/wx-notify| 注意项 | 说明 |
|---|---|
| 必须 HTTPS | 微信只回调 443 |
| 路径大小写 | 必须是 /api/payment/wx-notify |
| 无多余斜杠 | 域名后不要双斜杠 |
| 外网可达 | 微信服务器能 POST 到该地址 |
如何自测回调可达：
- 用浏览器访问会 405/404 正常（须接受 POST）
- 看 Nginx 是否把
/api/反代到 Go 服务 - 勿 对
/api/payment/wx-notify做 CDN 缓存
2.6 开通「商家转账到零钱」（提现自动打款，可选）
路径：产品中心 → 商家转账 → 按指引开通
开通后申请 转账场景，获得 场景 ID → 填入灵萌 转账场景 ID。
未开通时：用户提现只能 人工打款 或在 财务管理 → 提现处理 手动处理。
三、灵萌管理后台填写（逐字段）
路径：系统设置 → 系统配置 → 微信支付
3.1 基本信息区
| 后台字段 | 填什么 | 必填 | 常见错误 |
|---|---|---|---|
| 商户号 | 商户平台 10 位商户号 | ✅ | 填成 AppID |
| 支付密钥 | APIv3 密钥 | ✅ | 用错 v2 密钥；多空格 |
| v3 证书序列号 | 证书管理页序列号 | ✅ | 证书更新后未改 |
| 支付公钥 ID | 平台公钥 ID | 视接入 | — |
| 转账场景 ID | 商家转账场景 ID | 自动打款必填 | 未开通转账就填 |
3.2 证书内容区
| 后台字段 | 填什么 |
|---|---|
| CERT 证书 | 完整 apiclient_cert.pem 内容 |
| KEY 密钥 | 完整 apiclient_key.pem 私钥 |
| 支付公钥 | 微信支付平台公钥 PEM |
粘贴时注意：
- 保留
-----BEGIN ...-----和-----END ...----- - 不要多空行或缺行
- 私钥 切勿 泄露到公开仓库
填写完成后 保存 该 Tab。
四、与小程序配置的关联
微信支付 不能单独工作，须与小程序配置一致：
| 配置位置 | 字段 | 要求 |
|---|---|---|
| 系统配置 → 微信小程序 | AppID / Secret | Token 测试通过 |
| 微信商户平台 | AppID 绑定 | 已关联同一 AppID |
| 小程序后台 | 服务器域名 | request 合法域名含 API 域名 |
用户 微信小程序登录 与支付用的是 同一小程序 AppID。
五、哪些业务会用到微信支付
配置完成后，以下场景会调起微信支付（须对应 功能/区域 也已开启）：
| 业务 | 典型入口 | 后台相关 |
|---|---|---|
| 商城/订单 | 商品下单 | 商户配置 |
| 红包 | 私信/群聊发红包 | 支付 + 余额 |
| 转账 | 用户间转账 | 同上 |
| 闲置交易 | 闲置帖成交 | 区域闲置配置 |
| 外卖 | 外卖订单 | 外卖配置 |
| 跑腿 | 服务表单提交 | 跑腿 |
| 用户充值 | 钱包充值 | 财务管理 |
| 提现打款 | 提现到微信零钱 | 转账场景 ID + 提现审核 |
六、提现与打款
6.1 用户提现流程
text
用户 App 申请提现
↓
财务管理 → 提现处理（待审核）
↓
管理员审核通过
↓
已配置商家转账 → 自动打款到微信零钱
未配置 → 人工线下转账6.2 后台菜单
| 菜单 | 作用 |
|---|---|
| 财务管理 → 提现处理 | 审核通过/拒绝 |
| 财务管理 → 资金交易 | 支付、退款、转账流水 |
| 财务管理 → 余额流水 | 用户余额变动 |
6.3 打款失败常见原因
| 原因 | 处理 |
|---|---|
| 未填转账场景 ID | 商户平台申请场景并填入后台 |
| 证书/密钥错误 | 重新下载证书并更新 |
| 用户未实名 / 未绑微信 | 用户侧完成绑定 |
| 商户运营账户余额不足 | 商户平台充值 |
七、完整验收 checklist
7.1 配置阶段
- [ ] 商户号与 AppID 已绑定
- [ ] APIv3 密钥、证书序列号、CERT、KEY 已填入并 保存
- [ ] 回调 URL 已在商户平台配置为
https://域名/api/payment/wx-notify - [ ] 小程序 系统配置 → 微信小程序 Token 成功
7.2 支付测试
- [ ] 小程序发起 0.01 元 测试支付
- [ ] 支付成功，订单状态变为已支付
- [ ] 财务管理 → 资金交易 有 SUCCESS 记录
- [ ] 商户平台 交易中心 有对应订单
7.3 回调测试
- [ ] 支付后 5 秒内 订单状态更新（非长时间待支付）
- [ ] 服务器日志无持续「验签失败」
- [ ] Nginx 未对 POST 回调返回 301/302 到错误页
7.4 提现测试（若启用）
- [ ] 转账场景 ID 已填
- [ ] 测试用户小额提现 → 审核通过 → 微信零钱到账
八、故障排查表
| 现象 | 排查顺序 |
|---|---|
| 支付页提示未配置 | 支付模块是否开通 → 微信支付 Tab 是否保存 → 商户号是否填 |
| 调起支付失败 | AppID 绑定 → 小程序与后台 AppID 一致 → 用户 openid 有效 |
| 已付款仍待支付 | 回调 URL → 证书/公钥 → Nginx 反代 → 防火墙 |
| 验签失败 | KEY/CERT 是否配对 → 平台公钥是否最新 → 序列号是否匹配 |
| 退款失败 | 证书权限 → 订单状态 → 商户平台退款记录 |
| 提现不到账 | 转账场景 ID → 审核是否通过 → 商户转账产品是否开通 |
日志与监控位置
| 位置 | 看什么 |
|---|---|
| 财务管理 → 资金交易 | 订单号、状态、金额 |
| 系统监控 → 系统状态 | 支付链路健康 |
| 系统监控 → 对账中心 | 异常对账（有权限时） |
| 服务器日志 | wx-notify、验签、回调 body |
九、与支付宝并存
灵萌支持 微信 + 支付宝 同时配置，用户支付时可选择渠道。
| 项目 | 微信 | 支付宝 |
|---|---|---|
| 后台 Tab | 微信支付 | 支付宝 |
| 回调 | /api/payment/wx-notify | /api/payment/alipay-notify |
| 手册 | 本文 | 支付与提现 |
十、生产环境安全建议
- 商户 API 证书仅保存在服务器，不要通过 IM 传播
- 定期在商户平台 轮换 APIv3 密钥 并同步更新后台
- 回调 URL 仅允许微信 IP 段访问（可选 WAF 规则）
- 提现审核与打款权限分离，避免单人可操作全流程