Skip to content

支付渠道配置 ​

本篇覆盖易支付、支付宝当面付与微信支付 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 及以上即可。

验收方法:

  1. 创建 0.01 元订单;
  2. 打开二维码或支付链接;
  3. 付款后等待插件主动查单;
  4. 检查订单变为已支付/已发货;
  5. 在易支付后台核对商户订单号和实收金额。

🏦 支付宝当面付 ​

必备条件:

  • 支付宝开放平台应用可用,并已开通当面付相关能力;
  • 接口加签方式为 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。

自建公网支付通知地址的步骤:

  1. 准备一个已托管到 Cloudflare 的域名,例如 example.com;
  2. 规划支付子域名,例如 pay.example.com;
  3. 保持插件运行,在浏览器访问 http://127.0.0.1:18765/health,看到 "ok":true;
  4. 按安装包中 工具/微信回调隧道/README.md 创建 Cloudflare Tunnel;
  5. Tunnel 的源站服务填写 http://127.0.0.1:18765,不要追加 /wechat/notify;
  6. 访问 https://pay.example.com/health 验证公网连通;
  7. 插件「公网支付通知地址」最终填写 https://pay.example.com/wechat/notify;
  8. 保存并重启插件,用 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 解密,平台响应则使用微信支付公钥验签。

🔀 默认渠道与多渠道 ​

「默认渠道」用于用户未在指令中指定支付方式时下单,商店只展示已启用且配置可用的渠道。用户可以在下单时指定渠道:

text
购买 1 支付宝
购买 1 微信 邮箱 user@example.com
购买 1 易支付

渠道名称以控制台和机器人商店实际展示为准。

🧭 支付排错顺序 ​

  1. 看机器人群内错误文字;
  2. 看「运行日志」完整错误;
  3. 看支付平台商户后台是否出现订单;
  4. 核对 AppId/商户号/PID 是否属于同一环境;
  5. 核对私钥、公钥、证书是否配套;
  6. 核对机器时间和公网 IP 白名单;
  7. 创建新的 0.01 元订单重试,不要反复扫过期码。

📚 下一节:邮箱与自动发货

薇薇官机平台 · ZL 系列插件