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 及以上即可。

验收方法

  1. 创建 0.01 元订单;

  2. 打开二维码或支付链接;

  3. 付款后等待插件主动查单;

  4. 检查订单变为已支付/已发货;

  5. 在易支付后台核对商户订单号和实收金额。

三、支付宝当面付

必备条件

  • 支付宝开放平台应用可用;

  • 应用已开通当面付相关能力;

  • 接口加签方式为 RSA2;

  • 应用私钥与开放平台上传的应用公钥为同一密钥对;

  • 已取得支付宝公钥。

三把“钥匙”不要混淆

  1. 应用私钥:由你自己生成,插件用它给请求签名,必须保密。

  2. 应用公钥:由你生成并上传给支付宝,通常不填到本插件的“支付宝公钥”字段。

  3. 支付宝公钥:支付宝平台提供,插件用它验证支付宝响应签名,必须填到控制台。

看到“支付宝响应验签失败:请确认填写的是支付宝公钥(不是应用公钥)”时,优先检查第 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 支付特点

微信 Native 返回的通常是 weixin:// 二维码内容,适合扫码,不一定能像 HTTPS 链接一样在普通浏览器直接打开。插件会展示二维码;其他渠道返回 HTTP/HTTPS 时会同时提供可点击支付链接。

通知与主动查单

微信 Native 要求公网 HTTPS 通知地址。插件也会主动查单,但通知地址仍应按微信平台要求正确配置。通知内容会使用 API v3 Key 解密,平台响应则使用微信支付公钥验签。

六、默认渠道和多渠道

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

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

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

七、支付排错顺序

  1. 看机器人群内错误文字;

  2. 看“运行日志”完整错误;

  3. 看支付平台商户后台是否出现订单;

  4. 核对 AppId/商户号/PID 是否属于同一环境;

  5. 核对私钥、公钥、证书是否配套;

  6. 核对机器时间和公网 IP 白名单;

  7. 创建新的 0.01 元订单重试,不要反复扫过期码。

共 11 篇 ZL-售卡插件 / 支付渠道配置 0 字 0 行 zhangxiaolin
创建 2026-09-23T09:09:37.825371355Z 更新 2026-09-29T04:17:54.347868239Z