微信支付安全接入
> 来源：亲子成长记施工包 AI要怎么做.md §3.3 微信支付，已抽离项目名，成为通用接入规范。
这是什么
微信支付接入有固定的接口与一套安全铁律（回调验签、幂等、密钥保管）。本技能既给"必须实现"的清单，又能生成一套 FastAPI 支付模块骨架（路由 + 微信支付客户端 + 回调验签 + 幂等 + JSAPI 支付参数 + .env 模板），避免从零踩坑。
脚本自带 --self-test：用临时 RSA 密钥 + 随机 APIv3 密钥，验证签名/验签与回调报文 AES 加解密往返正确，证明生成的密码学逻辑可用——你不必盲信它。
何时使用
- 用户说："接入微信支付" / "小程序支付" / "微信支付回调怎么写" / "微信退款" / "paySign 怎么算"
- 任何需要收款的微信小程序 / 公众号项目
开发前必须准备的凭证（P0，否则代码跑不通）
- [ ] 微信商户号 MCH_ID（pay.weixin.qq.com 获取）
- [ ] API v3 密钥（商户平台 → 账户中心 → API 安全 → 设置 APIv3 密钥，32 位）
- [ ] 商户证书（apiclient_cert.pem + apiclient_key.pem，API 安全页下载）
- [ ] 小程序 / 公众号 AppID（与商户号绑定）
- [ ] 支付回调域名（在商户平台配置白名单）
微信支付接口规范（系统预置）
| 接口 | 说明 | 关键注意 |
|---|---|---|
JSAPI 下单 POST /v3/pay/transactions/jsapi |
小程序 / 公众号支付 | 需传 openid |
Native 下单 POST /v3/pay/transactions/native |
扫码支付 | 返回二维码 URL |
H5 下单 POST /v3/pay/transactions/h5 |
手机浏览器支付 | 需配置 H5 支付域名 |
查询订单 GET /v3/pay/transactions/out-trade-no/{out_trade_no} |
主动查询 | 回调失败时补偿 |
关单 POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close |
关单 | 超时未支付关闭 |
支付回调 POST /你的回调路径 |
异步通知 | 必须验签，以此为支付成功依据 |
申请退款 POST /v3/refund/domestic/refunds |
退款 | 需商户证书 |
必须实现的安全约束（P0，缺一不可）
- 支付结果以异步回调为准，禁止只依赖前端回调判断支付成功
- 回调接口必须验证微信签名（
Wechatpay-Signature请求头 + 平台证书） - 回调接口必须做幂等处理（同一订单收到多次回调只处理一次，用订单号唯一约束 / 已处理标记）
- 支付密钥（apiv3_key、私钥文件）只存服务器本地 /
.env，不提交 Git，不写日志 - 支付金额以服务端计算为准，不信任前端传入的金额参数
脚本用法（生成 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（验收）使用更佳
