微信支付

微信支付配置指南

TDuckX 商品支付及红包功能基于微信支付实现，使用前请先完成微信支付商户号申请及相关配置。

使用前准备

请确保已完成以下准备工作：

  • 已申请微信支付商户号
  • 已认证微信公众号（服务号）
  • 服务号与商户号已完成关联绑定

微信支付必须关联服务号后才能正常发起支付。

配置入口

进入：系统配置 → 微信支付

图片

基础收款配置

服务号系统AppID

填写已认证服务号的 AppID。

获取路径：微信公众平台 → 设置 → 基本设置

请注意：服务号需与商户号完成关联绑定。登录微信支付后台，产品中心，找到AppID账号管理，将服务号和微信商户号进行关联。

微信支付商户号（MCH ID）

填写微信支付商户号。获取路径：微信支付商户平台 → 账户中心

商户密钥 (API Key)

填写微信支付 API 密钥（V2）。

获取路径：微信支付商户平台 → 账户中心 → API安全 → API密钥

图片

注意：

  • 微信官方不会保存密钥明文
  • 如遗失需重新设置
  • 修改后需同步更新 TDuckX 配置

支付回调地址

填写格式：https://你的域名/tduck-api/form/ext/goods/pay/notify

示例：https://example.com/tduck-api/form/ext/goods/pay/notify

⚠️要求：必须使用 HTTPS，并且服务器需具备公网访问能力

高级资金出账配置

如需使用「提交表单后自动发放微信红包」功能，请完成以下配置。没有则忽略，不用配置

开通商家红包（⚠️微信已下架，已开通的不影响）

进入：微信支付商户平台 → 产品中心 → 商家红包；申请开通红包能力。

⚠️请注意，此能力微信红包接口已下架，新商户建议使用商家转账到零钱模式。旧用户可保留红包模式。

商家红包开通

配置服务器公网 IP

进入：微信支付商户平台 → API安全。将 TDuckX 服务端所在服务器公网 IP 添加至可信 IP 白名单。

可信IP配置

转账模式（✅ 新开通的商户号支持）

登录微信支付后台：产品中心-我的产品-商户转账

  • 申请转账场景 新增场景-现金营销 id 1000 这个 一定要申请这个！

  • 然后完成接口 IP 设置，也就是你服务器的 IP地址

图片

API V3 密钥 (apiV3Key)

接下来需要获取参数配置到系统，在账户中心-API安全，找到解密回调，点击获取 Apiv3 密钥

API V3 密钥 (apiV3Key) 填入到配置界面

图片

公钥 ID (publicKeyId)

账户中心-API安全，找到验证微信支付身份，微信支付公钥，点击配置

图片

获取支付公钥，包含pub_key.pem文件和一个公钥 ID。

图片

配置上述的内容到系统。

⚠️请注意：微信公钥证书的文件名是pub_key.pem 不要上传错了！

图片

多商户号收款配置

从TDuckX3.9版本开始，表单收款支持设置多商户号收款，在微信支付配置中找到：其他收款账号列表-添加商户号。

图片

新增商户号

点击添加收款账号，填入商户号名称、AppID、商户号、商户密钥即可完成配置。

图片

在表单中使用多商户号

选择具有收款的功能组件，例如：计算金额、商品组件，右侧属性栏中可以选用已经配置好的商户号进行收款；请注意，一个表单仅支持配置同一套收款商户号。

图片

常见问题

配置后支付不生效？

请确认：

  • 后端服务已重启
  • AppID 配置正确
  • 服务号与商户号已关联
  • API 密钥填写正确
  • 回调地址可公网访问

提示“缺少 AppId 参数”？

通常是以下原因导致：

  • 服务号 AppID 配置错误
  • 服务号与商户号未关联
  • 微信配置未生效

建议优先查看服务端日志进行排查。