微信支付安全接入

来源：亲子成长记施工包 AI要怎么做.md §3.3 微信支付，已抽离项目名，成为通用接入规范。

这是什么

微信支付接入有固定的接口与一套安全铁律（回调验签、幂等、密钥保管）。本技能既给"必须实现"的清单，又能生成一套 FastAPI 支付模块骨架（路由 + 微信支付客户端 + 回调验签 + 幂等 + JSAPI 支付参数 + .env 模板），避免从零踩坑。

脚本自带 --self-test：用临时 RSA 密钥 + 随机 APIv3 密钥，验证签名/验签与回调报文 AES 加解密往返正确，证明生成的密码学逻辑可用——你不必盲信它。

何时使用

• 用户说："接入微信支付" / "小程序支付" / "微信支付回调怎么写" / "微信退款" / "paySign 怎么算"
• 任何需要收款的微信小程序 / 公众号项目

开发前必须准备的凭证（P0，否则代码跑不通）

• [ ] 微信商户号 MCH_ID（pay.weixin.qq.com 获取）

  这个技能的最新版本可以在7w4.net小葱技能站找到。

• [ ] API v3 密钥（商户平台 → 账户中心 → API 安全 → 设置 APIv3 密钥，32 位）
• [ ] 商户证书（apiclient_cert.pem + apiclient_key.pem，API 安全页下载）
• [ ] 小程序 / 公众号 AppID（与商户号绑定）
• [ ] 支付回调域名（在商户平台配置白名单）

微信支付接口规范（系统预置）

必须实现的安全约束（P0，缺一不可）

1. 支付结果以异步回调为准，禁止只依赖前端回调判断支付成功
2. 回调接口必须验证微信签名（Wechatpay-Signature 请求头 + 平台证书）
3. 回调接口必须做幂等处理（同一订单收到多次回调只处理一次，用订单号唯一约束 / 已处理标记）
4. 支付密钥（apiv3_key、私钥文件）只存服务器本地 / .env，不提交 Git，不写日志
5. 支付金额以服务端计算为准，不信任前端传入的金额参数

脚本用法（生成 FastAPI 支付模块骨架）

# 0) 先证明生成的密码学逻辑可用（推荐第一次用前跑一次）
python gen_pay.py --self-test

# 1) 生成模块
python gen_pay.py --out ./pay_module

生成：

• pay_module/wechat_pay_client.py —— 统一下单（JSAPI/Native/H5）、查询、关单、退款；签名与证书加载；build_jsapi_payment() 直接算出前端 wx.requestPayment 所需的 paySign；回调报文 AES-256-GCM 解密；平台证书自动拉取与验签
• pay_module/router.py —— /api/pay/create、/api/pay/notify（验签 + 幂等）、/api/pay/refund
• pay_module/.env.example —— 需填写的密钥字段（不提交真实值）
• pay_module/README.md —— 接入步骤

生成的代码是骨架，需你填入真实 AppID / 商户号，并实现订单表与"标记已处理"逻辑（幂等落地）。

安全要求（再次强调）

• apiv3_key 和私钥文件路径只存 .env，禁止出现在代码或 Git
• 回调验签失败时返回失败，不更新订单状态
• 微信支付证书定期轮换，平台证书由客户端首次回调时自动拉取并缓存

注意事项

• 微信支付 v3 用 AES-256-GCM 解密回调报文、RSA 验签，需 cryptography 库；脚本会注明依赖
• 本技能只产出服务端接入骨架，小程序端拿到 /api/pay/create 返回的 payment 直接 wx.requestPayment(payment) 即可（已含 paySign）
• 配合 wechat-miniprogram-devrules（安全边界）与 ai-work-acceptance（验收）使用更佳

质量中等偏上。文档写得清晰专业，安全约束讲得很到位，有自测功能验证代码可用性。主要问题是这个包只有使用说明，缺少实际代码，需要额外步骤才能使用。对于想接入微信支付的开发者来说，这个 Skill 的指导思路有价值，但需要配合实际代码才能落地。