支付渠道配置
本篇覆盖易支付、支付宝当面付与微信支付 API v2/v3 三类渠道的参数来源、填写要点与排错顺序。所有渠道都遵循「创建订单 → 查询/通知 → 验签 → 金额核对 → 出库」的完整链路。
🛡️ 共同安全规则
二维码出现不代表已经接入成功,必须完成一次真实小额支付。无论使用哪个渠道:
- 只启用已经签约并测试通过的渠道;
- 商户订单号应能在支付平台后台查到;
- 渠道返回「成功」但签名不可信时,插件不会发货;
- 实付金额必须与插件订单金额一致;
- 不要通过聊天发送商户 KEY、私钥、证书或 API v3 Key;
- 机器人电脑的时间、时区和网络必须正常。
💠 易支付
| 控制台字段 | 从哪里获取 |
|---|---|
| 网关地址 | 易支付服务商提供的商户站点地址 |
| 商户 ID(PID) | 服务商商户后台 |
| 商户密钥(KEY) | 服务商商户后台 |
| 支付类型 | 服务商支持的 alipay、wxpay 或 qqpay |
| 站点名称 | 付款页面展示的站点名 |
| 异步通知地址 | 有公网接收服务时填写,否则可留空 |
| 同步跳转地址 | 用户付款后跳转页面,可留空 |
不同服务商可能修改接口规则
如果创建订单、查单字段与标准易支付协议不兼容,应向服务商确认接口文档,而不是反复更换 PID/KEY。
使用 z-pay(zpayz.cn)等网关时请额外注意(0.0.17/0.0.18 已适配):
- 商户 ID 与商户密钥必须与网关后台完全一致,PID 抄错一位会报「pid错误,未找到对应商家」;
- 网关的「担保时效 mprotect」参数只传参、不参与签名,插件已按此规则处理,无需手动干预;
- 插件统一走网关预下单短链:付款链接与二维码内容完全一致,点链接和扫码都能正常支付,链接不会再出现超长的中文编码参数;
- 报「MD5签名错误」时优先核对 PID/KEY 是否抄错、网关地址是否填写了服务商提供的商户站点地址;
- 报「请求重入时参数与首次请求不一致」为旧版本问题,更新插件到 0.0.18 及以上即可。
验收方法:
- 创建 0.01 元订单;
- 打开二维码或支付链接;
- 付款后等待插件主动查单;
- 检查订单变为已支付/已发货;
- 在易支付后台核对商户订单号和实收金额。
🏦 支付宝当面付
必备条件:
- 支付宝开放平台应用可用,并已开通当面付相关能力;
- 接口加签方式为 RSA2;
- 应用私钥与开放平台上传的应用公钥为同一密钥对;
- 已取得支付宝公钥。
三把「钥匙」不要混淆:
| 密钥 | 谁生成 | 用途 |
|---|---|---|
| 应用私钥 | 你自己 | 插件用它给请求签名,必须保密 |
| 应用公钥 | 你自己,并上传给支付宝 | 配套验签材料,通常不填到本插件的「支付宝公钥」字段 |
| 支付宝公钥 | 支付宝平台 | 插件用它验证支付宝响应签名,必须填到控制台 |
看到响应验签失败先查支付宝公钥
提示「支付宝响应验签失败:请确认填写的是支付宝公钥(不是应用公钥)」时,优先检查上表第 3 项,而不是重新生成二维码。
参数填写:
- AppId:开放平台对应应用的 AppId;
- 应用私钥:支持 PEM 或纯 Base64,使用 RSA2;
- 支付宝公钥:应用密钥管理页面提供的支付宝公钥;
- 正式网关:
https://openapi.alipay.com/gateway.do; - 异步通知地址:可留空,插件会主动查单;若填写需确保公网可达;
- 沙箱:沙箱 AppId、密钥和网关必须成套使用,不能与正式参数混搭。
常见失败与处理:
| 现象 | 处理方向 |
|---|---|
isv.invalid-signature | 私钥与上传公钥不配套,或签名方式不对 |
| 响应验签失败 | 支付宝公钥填写错误、复制不完整或环境混用 |
| 无权限 | 应用未签约产品或能力未生效 |
| IP 限制 | 需要加入白名单的是实际运行 UniQQ 机器的公网出口 IP,不一定是网站服务器 IP |
💚 微信支付 API v2 简易模式
API v2 Native 下单和查单不需要证书。它与 API v3 是两套不同的签名方式,请按控制台选中的模式填写。
| 字段 | 说明 |
|---|---|
| AppID | 微信公众号或服务号后台「基本配置」中的开发者 ID |
| 商户号 | 微信支付商户平台「商户信息」中的 mchid |
| API 密钥(v2) | 商户平台「账户中心 / API 安全」中设置的 32 位 API 密钥,不是 API v3 Key |
| 通知地址 | 微信统一下单强制要求的公网 HTTPS 地址 |
普通用户推荐选择「ZL 官方回调中心」:登录 https://uniqq.pay.zxiaolin.com 创建插件实例,将一次性显示的连接密钥填入插件,保存并重启,即可自动取得专属公网通知地址,无需自己的域名。商户 API 密钥、私钥和卡密仍只保存在用户电脑上,官网只暂存原始支付通知。
需要完全独立部署时,可选择「自建公网回调」:插件会在机器人电脑上启动本地回调接口,默认地址为 http://127.0.0.1:18765/wechat/notify,再通过 Cloudflare Tunnel 或自己的服务器映射为公网 HTTPS 地址。插件会每 8 秒主动查单,但微信下单请求本身仍要求提供 notify_url。
自建公网支付通知地址的步骤:
- 准备一个已托管到 Cloudflare 的域名,例如
example.com; - 规划支付子域名,例如
pay.example.com; - 保持插件运行,在浏览器访问
http://127.0.0.1:18765/health,看到"ok":true; - 按安装包中
工具/微信回调隧道/README.md创建 Cloudflare Tunnel; - Tunnel 的源站服务填写
http://127.0.0.1:18765,不要追加/wechat/notify; - 访问
https://pay.example.com/health验证公网连通; - 插件「公网支付通知地址」最终填写
https://pay.example.com/wechat/notify; - 保存并重启插件,用 0.01 元商品完成真实支付测试。
保持隧道在线
公网地址不要使用临时随机域名作为正式支付配置。机器人电脑关机、插件停止或 Tunnel 未运行时,微信通知将无法送达;插件仍会主动查单作为补充,但正式环境应保持隧道在线。
API v2 使用 MD5 签名。插件会验证统一下单、主动查单和支付通知的签名,并核对 AppID、商户号、订单号与支付金额。
🔷 微信支付 API v3 高级模式
| 字段 | 说明 |
|---|---|
| AppId | 与商户号绑定的公众号、小程序或应用 AppId |
| 商户号 | 微信支付 mchid |
| API v3 Key | 商户平台设置的 32 位密钥,用于通知解密 |
| 商户 API 证书序列号 | 与当前商户私钥配套的证书序列号 |
| 商户 API 私钥 | apiclient_key.pem 的完整内容 |
| 微信支付公钥 ID | 商户平台下载公钥时提供的 ID |
| 微信支付公钥 | 与公钥 ID 配套的 PEM 内容 |
| 通知地址 | 公网可访问的 HTTPS 地址 |
三类材料用途不同
「商户 API 证书」「商户 API 私钥」「微信支付公钥」不是同一个文件,用途不同,不要混为一谈。
微信 Native 返回的通常是 weixin:// 二维码内容,适合扫码,不一定能像 HTTPS 链接一样在普通浏览器直接打开。插件会展示二维码;其他渠道返回 HTTP/HTTPS 时会同时提供可点击支付链接。
微信 Native 要求公网 HTTPS 通知地址。插件也会主动查单,但通知地址仍应按微信平台要求正确配置。通知内容会使用 API v3 Key 解密,平台响应则使用微信支付公钥验签。
🔀 默认渠道与多渠道
「默认渠道」用于用户未在指令中指定支付方式时下单,商店只展示已启用且配置可用的渠道。用户可以在下单时指定渠道:
购买 1 支付宝
购买 1 微信 邮箱 user@example.com
购买 1 易支付渠道名称以控制台和机器人商店实际展示为准。
🧭 支付排错顺序
- 看机器人群内错误文字;
- 看「运行日志」完整错误;
- 看支付平台商户后台是否出现订单;
- 核对 AppId/商户号/PID 是否属于同一环境;
- 核对私钥、公钥、证书是否配套;
- 核对机器时间和公网 IP 白名单;
- 创建新的 0.01 元订单重试,不要反复扫过期码。
📚 下一节:邮箱与自动发货
