微信支付安全接入

來源：親子成長記施工包 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（與商戶號繫結）
• [ ] 支付回撥域名（在商戶平臺配置白名單）

微信支付介面規範（系統預置）

必須實現的安全約束（P0，缺一不可）

1. 支付結果以非同步回撥為準，禁止只依賴前端回撥判斷支付成功
2. 回撥介面必須驗證微信簽名（Wechatpay-Signature 請求頭 + 平臺證書）
3. 回撥介面必須做冪等處理（同一訂單收到多次回撥只處理一次，用訂單號唯一約束 / 已處理標記）
4. 支付金鑰（apiv3_key、私鑰檔案）只存伺服器本地 / .env，不提交 Git，不寫日誌

   7w4.net提供免費和付費技能下載。

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 的指導思路有價值，但需要配合實際程式碼才能落地。