03 · 支付渠道配置
一、共同安全规则
无论使用哪个渠道,插件都要经过“创建订单 → 查询/通知 → 验签 → 金额核对 → 出库”。二维码出现不代表已经接入成功,必须完成一次真实小额支付。
只启用已经签约并测试通过的渠道;
商户订单号应能在支付平台后台查到;
渠道返回“成功”但签名不可信时,插件不会发货;
实付金额必须与插件订单金额一致;
不要通过聊天发送商户 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 支付特点
微信 Native 返回的通常是 weixin:// 二维码内容,适合扫码,不一定能像 HTTPS 链接一样在普通浏览器直接打开。插件会展示二维码;其他渠道返回 HTTP/HTTPS 时会同时提供可点击支付链接。
通知与主动查单
微信 Native 要求公网 HTTPS 通知地址。插件也会主动查单,但通知地址仍应按微信平台要求正确配置。通知内容会使用 API v3 Key 解密,平台响应则使用微信支付公钥验签。
六、默认渠道和多渠道
“默认渠道”用于用户未在指令中指定支付方式时下单。商店只展示已启用且配置可用的渠道。用户可以发送:
渠道名称以控制台和机器人商店实际展示为准。
七、支付排错顺序
看机器人群内错误文字;
看“运行日志”完整错误;
看支付平台商户后台是否出现订单;
核对 AppId/商户号/PID 是否属于同一环境;
核对私钥、公钥、证书是否配套;
核对机器时间和公网 IP 白名单;
创建新的 0.01 元订单重试,不要反复扫过期码。