微信支付接入实战：JSAPI+Native双模式配置详解与Node.js实现

微信支付的接入，其配置工作往往比编写业务代码更为繁琐。代码部分借助AI工具，例如Claude Code，可能半小时就能完成。但前期的商户认证、平台参数配置、服务绑定等环节，却可能花费一至两天的时间。这主要涉及微信公众平台与微信支付商户平台两个系统，需要配置的内容较多且相互关联。

本文将完整记录从零接入微信支付支持JSAPI（微信内支付）与Native（扫码支付）的全流程，包含必备条件、关键参数获取、平台配置以及代码实现。

前置必备条件

正式接入微信支付前，需确保满足以下条件：

• 企业资质：需企业营业执照，个人主体无法申请。
• 服务号：必须是认证过的微信服务号（订阅号不支持支付功能）。
• 备案域名：需要一个已成功备案的域名，用于支付回调与网页授权。

我们团队拥有现成的公司主体，域名 fyyd.net 也已备案。服务号认证费用为300元/年，按指引提交企业资料后，通常几个工作日内即可通过审核。

核心参数清单：两个平台，七个关键配置

微信支付涉及两个核心平台：

• 微信公众平台：用于管理公众号，获取用户标识(AppID)。
• 微信支付商户平台：用于收款、资金结算及支付能力管理。

最终，我们需要从这两个平台获取以下关键参数，并配置到环境变量中：

# 来自公众号
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=你的appsecret

# 来自商户平台
WECHAT_MCH_ID=1234567890
WECHAT_API_V3_KEY=32位随机密钥
WECHAT_SERIAL_NO=证书序列号
WECHAT_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----

# 自行定义的网站配置
WECHAT_PAY_NOTIFY_URL=https://你的域名/api/pay/notify

第一步：微信公众平台配置

登录 mp.weixin.qq.com，使用管理员微信扫码。

1. 获取 AppID 与 AppSecret

进入“设置与开发 -> 基本配置”页面。直接复制 AppID。
在同一页面，点击 AppSecret 右侧的“重置”按钮以获取密钥。请注意，AppSecret 仅显示一次，务必妥善保存。

2. 配置网页授权域名与JS接口安全域名

进入“设置 -> 公众号设置 -> 功能设置”。

• 网页授权域名：用户授权获取 openid 时使用。
• JS接口安全域名：在微信内调起支付界面时使用。

将你的备案域名（例如 event.fyyd.net，无需 https:// 前缀）填入这两个字段。配置时需下载验证文件并放置于网站根目录。若使用 Vercel 等平台部署，可将其置于 public 目录下。

第二步：微信支付商户平台配置

登录 pay.weixin.qq.com，使用管理员微信扫码。

1. 获取商户号(MCH_ID)

进入“账户中心 -> 商户信息”，复制10位数字的商户号。

2. 设置 APIv3 密钥

进入“账户中心 -> API安全 -> APIv3密钥”。
设置一个32位的随机字符串作为密钥。务必注意这是 APIv3密钥，与旧版的 API密钥 不同。

3. 申请并配置API证书

这是配置中的关键步骤，用于保证通信安全。

1. 进入“账户中心 -> API安全 -> API证书”，点击“申请证书”。
2. 下载并运行“微信支付商户平台证书工具”。
   • 踩坑提示：若工具双击无反应，可能是环境兼容性问题，需根据系统版本查找解决方案。
3. 按照工具指引，在商户平台完成证书申请流程。
4. 审核通过后，下载证书文件包。其中 apiclient_key.pem 文件包含了我们需要的私钥内容。

证书文件包
├── apiclient_cert.p12     # PKCS#12格式证书 (不常用)
├── apiclient_cert.pem     # 证书文件 (公钥)
└── apiclient_key.pem      # 私钥文件 ⭐ 核心！

4. 获取证书序列号

在“API证书”管理页面，从证书列表中复制40位的“证书序列号”。

第三步：关联公众号与商户号

此步骤使你的服务号具备调用已配置商户号支付的能力。

1. 在商户平台操作：进入“产品中心 -> AppID账号管理 -> 关联AppID”，输入公众号的 AppID 并提交。
2. 在公众平台操作：进入“微信支付 -> 商户号管理”，找到待确认的关联申请，点击“确认关联”。

双方均操作完成后，关联才生效。

第四步：开通支付产品与配置

支付产品需要单独申请开通。

进入“商户平台 -> 产品中心 -> 产品大全”，找到所需支付产品并申请：

支付产品	适用场景	审核时长
Native支付	PC网站扫码支付	秒过
JSAPI支付	微信公众号内支付	秒过
H5支付	手机浏览器支付	1-3个工作日

特别配置：JSAPI支付授权目录
开通JSAPI支付后，需配置支付授权目录：进入“产品中心 -> 开发配置 -> JSAPI支付”。
添加你的支付页面所在目录，例如 https://event.fyyd.net/ (注意末尾斜杠)。配置后约有10分钟生效延迟。

第五步：后端代码实现（Node.js示例）

当所有配置完成后，即可进行代码开发。以下是一个基于 Node.js 和 Express 框架的核心流程概述。

支付流程概览

• Native支付流程：

  1. 后端调用微信支付统一下单接口，获取二维码链接(code_url)。
  2. 前端根据code_url生成二维码展示。
  3. 用户使用微信扫码并支付。
  4. 前端轮询或后端通过回调通知，更新订单状态。

• JSAPI支付流程：

  1. 通过微信网页授权，获取用户的openid。
  2. 后端调用统一下单接口，传入openid，获取支付参数。
  3. 前端使用参数调起微信支付界面。
  4. 用户确认支付，前端接收支付结果。

关键代码注意事项

1. 环境变量处理：私钥(WECHAT_PRIVATE_KEY)为多行文本，在Vercel等平台配置时，需注意换行符。建议通过命令行添加或代码中处理：

   # 使用命令行添加
   printf '%s' "$(cat apiclient_key.pem)" | vercel env add WECHAT_PRIVATE_KEY production

   或在代码中转换：

   const privateKey = process.env.WECHAT_PRIVATE_KEY?.replace(/\\n/g, '\n');

2. 支付回调处理：支付成功后，微信会异步调用你设置的WECHAT_PAY_NOTIFY_URL。

   • 回调地址必须是HTTPS且公网可访问。
   • 回调数据使用APIv3密钥进行AES-GCM加密，需解密后处理业务逻辑。
   • 处理成功后，必须返回指定的成功响应XML，否则微信会重复回调。

3. 签名与验签：与微信支付服务器的所有交互均需使用商户私钥进行签名，并验证微信返回的签名，这是保障网络通信安全的重要环节。

测试与上线

建议使用小额资金（如0.01元）测试完整流程：

1. 创建测试订单。
2. 分别尝试Native扫码支付和JSAPI微信内支付。
3. 确认订单状态是否正确更新。
4. 在商户平台“交易中心”核实资金流水。

扩展：退款处理

对于小规模活动，可直接在商户平台 -> 交易中心 -> 退款管理中手动操作退款。
若退款频率较高，可考虑将退款功能集成到自有的管理后台中，通过调用微信支付退款API实现，提升效率。

总结

接入微信支付的核心在于仔细完成公众平台与商户平台的各项配置，并准确获取七个关键参数。整个流程虽显繁琐，但按步骤逐一核对即可顺利完成。代码实现层面，利用成熟的SDK或AI辅助编程可以极大提升开发效率。本文以实战为导向，为你梳理了从配置到上线的完整路径，希望能帮助你在下一次接入时更加从容。