一、开店前需要准备什么
- 微信支付商户号：以企业/组织主体在 微信支付商户平台 完成注册与签约，并开通「Native 支付」或「JSAPI 支付」产品（未开通产品会下单失败）。
- 与该商户号关联的 AppID：来源可以是认证服务号（微信公众平台）、小程序，或开放平台网站应用（微信开放平台）；并在商户平台「产品中心 → AppID 账号管理」确认已完成关联。
- HTTPS 公网域名：支付结果回调必须是 https 且公网可达，本地或内网调试需自备内网穿透地址。
- 超级管理员权限：本页配置仅超级管理员可保存。
二、逐项参数的获取位置
| 页面字段 | 获取位置与操作 |
|---|
| APPID | 公众平台「设置与开发 → 基本配置」的开发者 ID，或开放平台对应网站应用详情；格式为 wx 开头共 18 位。需与商户号已关联。 |
| 商户号 | 商户平台登录后右上角账号菜单，或「账户中心 → 商户信息」中的商户号（8–10 位数字）。 |
| 商户证书序列号 | 商户平台「账户中心 → API 安全 → 申请 API 证书」，下载证书压缩包；序列号在申请结果页直接显示，也可对 apiclient_cert.pem 执行 openssl x509 -in apiclient_cert.pem -noout -serial 取得（去掉 serial= 前缀，字母大写）。 |
| 平台证书序列号 / 公钥 ID | 可选。商户平台「账户中心 → API 安全 → 微信支付公钥」下载公钥，页面会给出公钥 ID（形如 PUB_KEY_ID_…）；若仍使用平台证书模式，则填平台证书的序列号。 |
| 回调地址 | 固定填本站接口地址：https://platform.xi.plus/api/platform/pay/notify/wechat（按实际部署域名替换主机名），必须 https。 |
| 订单有效期 | 本系统参数，默认 120 分钟；用户下单后超过该时长未支付则订单关闭，可填 5–1440。 |
| APIv3 密钥 | 商户平台「账户中心 → API 安全 → 设置 APIv3 密钥」，32 位字母数字，设置后不可查看、只能重设；请妥善备份。 |
| APIv3 商户私钥 PEM | 网站：微信支付商户平台 pay.weixin.qq.com，登录后「账户中心 → API 安全 → API 证书」申请并下载证书压缩包，解压取其中的 apiclient_key.pem；完整粘贴 BEGIN PRIVATE KEY 到 END PRIVATE KEY（含首尾行）。详见下方「两类 PEM 文件在哪里找」。 |
| 平台证书 / 公钥 PEM | 网站：微信支付商户平台 pay.weixin.qq.com，登录后「账户中心 → API 安全 → 微信支付公钥」下载 pub_key.pem（BEGIN PUBLIC KEY）；若使用旧版平台证书，则取同页「平台证书」下载的 wechatpay_*.pem（BEGIN CERTIFICATE）。详见下方小节。 |
三、两类 PEM 文件在哪里找
1. APIv3 商户私钥 PEM（apiclient_key.pem）
下载网站：微信支付商户平台 https://pay.weixin.qq.com/，登录后进入「账户中心 → API 安全 → API 证书」。页面地址可能随改版调整，以登录后的菜单为准。
- 用具备「API 安全」权限的账号登录（普通操作员账号若无该权限，需商户超级管理员在「账户中心 → 人员管理」中开通）。
- 点「申请证书」，两种方式任选其一：
- 直接下载：按提示完成短信验证后，下载证书压缩包；
- 使用证书工具：下载 Windows「证书工具」，填入商户号、APIv3 密钥与证书序列号，由工具生成证书与私钥文件。
- 解压压缩包，通常包含 4 个文件：
apiclient_cert.pem（商户证书）、apiclient_key.pem（商户私钥）、apiclient_cert.p12、README.txt。
- 用文本编辑器打开
apiclient_key.pem，从 -----BEGIN PRIVATE KEY----- 到 -----END PRIVATE KEY----- 完整复制（保留首尾行、不要加空格），粘贴到页面的「APIv3 商户私钥 PEM」。
- 私钥只存在于你本地下载的压缩包中，商户平台不保存；丢失只能重新申请证书。重新申请会产生新的证书序列号，必须与页面「商户证书序列号」一并替换。
- 注意：这里的「私钥」是证书文件，与 32 位的 APIv3 密钥不是同一项，两者都要填写。
2. 平台证书 / 公钥 PEM（二选一，不能混用）
下载网站：同样是微信支付商户平台 https://pay.weixin.qq.com/，登录后进入「账户中心 → API 安全」，公钥在「微信支付公钥」页、旧版证书在「平台证书」页；账号需具备「API 安全」权限（无权限请联系商户超级管理员在「人员管理」中开通）。
- 推荐：微信支付公钥模式
- 商户平台「账户中心 → API 安全 → 微信支付公钥」；
- 点「申请公钥」并完成验证，下载
pub_key.pem；
- 页面会给出公钥 ID（形如
PUB_KEY_ID_011…），填入「平台证书序列号 / 公钥 ID」；
- 把
pub_key.pem 全文（-----BEGIN PUBLIC KEY----- 到 -----END PUBLIC KEY-----）粘贴到「平台证书 / 公钥 PEM」。
- 旧版：平台证书模式
- 商户平台「账户中心 → API 安全 → 平台证书」，点「下载证书」或使用平台证书下载工具；
- 也可在私钥与 APIv3 密钥配好后，调用 APIv3 接口
GET /v3/certificates 获取；
- 得到
wechatpay_<序列号>.pem，粘贴全文（-----BEGIN CERTIFICATE----- 到 -----END CERTIFICATE-----），并把证书序列号填入上一字段。
- 该文件用于验证微信支付回调的签名：缺失或不匹配时，钱能到账但系统不认账，套餐不会自动生效。
- 平台证书会定期轮换，过期后回调验签失败，需要重新下载更新；公钥模式相对稳定。
3. 服务器上的对应文件
页面提交后由服务端写入 server/config/payment/（目录 0700、文件 0600），也可直接替换同名文件：
| 页面字段 | 服务器文件 | 内容特征 |
|---|
| APIv3 密钥 | wechat_apiv3_key.txt | 32 位字母数字 |
| APIv3 商户私钥 PEM | wechat_private_key.pem | BEGIN PRIVATE KEY |
| 平台证书 / 公钥 PEM | wechat_platform_public_key.pem | BEGIN PUBLIC KEY 或 BEGIN CERTIFICATE |
四、推荐配置顺序
- 填写 APPID、商户号，点「保存配置」；
- 依次填入两个证书序列号、回调地址、订单有效期并保存；
- 粘贴 32 位 APIv3 密钥、商户私钥 PEM、平台公钥/证书 PEM，再次保存；
- 点「测试连接」确认配置齐备，通过后再把「启用微信支付」切到「启用」并保存；
- 在子站下单页用最小套餐做一笔真实小额支付，确认回调后套餐即时生效，再正式开放。
五、校验与安全说明
- 保存前会统一校验：AppID 格式、商户号位数、序列号十六进制、回调必须 https、订单时长范围、APIv3 恰为 32 位、私钥与公钥 PEM 可解析；任一项不合法则整批不保存。
- APIv3 密钥与两个 PEM 只写入服务器
config/payment/ 目录（目录 0700、文件 0600），不入库、不下发前端；页面始终显示掩码，输入框留空表示「保持原值」。
- 「测试连接」会用一个探测订单号调用微信「查询订单」接口，验证签名、证书与网络连通性（返回「订单不存在」即视为连接正常）；不会创建订单，也不会扣款。
- 启用前系统强制校验 7 项必需参数：AppID、商户号、商户证书序列号、回调地址、32 位 APIv3 密钥、商户私钥、平台公钥；缺任一项拒绝启用，避免用户付款后不到账。
六、常见问题
- 下单提示签名错误：多为证书序列号与私钥不匹配，或 APIv3 密钥填错；请重新下载同一套 API 证书再填。
- 付款成功但套餐未生效：回调地址不可达、平台公钥缺失或域名未使用 https；修正后在订单页对账补单。
- 退款失败：商户平台可用余额不足，或该订单已超过微信退款期限。
- 换了证书/密钥：按新证书序列号与新密钥整体替换，三项（密钥、私钥、平台公钥）需同批次更新。