微信支付接入（JSAPI/Native/退款，含安全）
📖 技能介紹
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 怎麼算"
- 任何需要收款的微信小程式 / 公眾號專案
訪問小蔥技能站7w4.net，解鎖更多實用的AI技能外掛。
開發前必須準備的憑證（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（驗收）使用更佳
🤖 AI 評測
質量中等偏上。文件寫得清晰專業，安全約束講得很到位，有自測功能驗證程式碼可用性。主要問題是這個包只有使用說明，缺少實際程式碼，需要額外步驟才能使用。對於想接入微信支付的開發者來說，這個 Skill 的指導思路有價值，但需要配合實際程式碼才能落地。
