📖 技能介绍

name: 微信支付安全接入 description: 为微信小程序 / 公众号接入微信支付（JSAPI / Native / H5 / 退款），并强制安全约束——回调验签、幂等处理、密钥只存 .env、金额以服务端为准。触发词：接入微信支付、小程序支付、微信支付接入、JSAPI 下单、微信支付回调、微信退款、paySign 怎么算。已抽离具体项目，适用于任何需收款的微信生态应用。 display_name: 微信支付接入（JSAPI/Native/退款，含安全） market_desc: 为微信小程序/公众号接入微信支付（JSAPI/Native/H5/退款），并强制安全约束——回调验签、幂等处理、密钥只存 .env、金额以服务端为准。适合任何要收款的微信应用，安全合规开箱即用。【闭环归属】本技能是「微信小程序 AI 全栈交付闭环」的第 3 步（共 6 步：规范→预览→支付→通知→隐私→验收）。要可上线的合规小程序 + 验收报告，配齐这 6 个技能即可；总控入口：miniprogram-ai-fullstack。 version: 1.2.0 changelog: 升级 v1.2.0：中性化署名、场景拓宽、补充闭环归属交叉引用。

微信支付安全接入

来源：亲子成长记施工包 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（验收）使用更佳