> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 微信 H5 支付接入指南

> 教你如何在 superun 中一步步接入微信 H5 支付,包括註冊商戶號,獲取支付憑證,配置環境變數等完整流程.

## 概述

微信支付是中國領先的移動支付平台.本指南將帶你一步步完成微信 H5 支付的接入,包括註冊商戶號、獲取支付憑證、開通權限和配置到 superun 系統的完整流程.

<Note>
  **請注意**
  微信支付接入需要用戶自行完成商戶號註冊和憑證獲取,superun 提供配置環境變數的指引.測試時請使用微信支付的測試環境.
</Note>

***

## 一、註冊商戶號

1. 打開瀏覽器訪問: `https://pay.weixin.qq.com`
2. 點擊頁面右上角 "成為商家"
3. 選擇註冊類型（企業/個體戶）
4. 按指引填寫:
   * 營業執照照片
   * 法人身份證正反面
   * 結算銀行賬戶信息
   * 聯繫人信息
5. 提交後等待審核（通常 1-3 個工作日）
6. 審核通過後,登錄即可看到你的**商戶號**

***

## 二、獲取支付憑證

### 2.1 獲取商戶號 (MCH\_ID)

1. 打開: `https://pay.weixin.qq.com`
2. 使用管理員微信掃碼登錄
3. 點擊頂部菜單 "賬戶中心"
4. 點擊左側 "商戶信息"
5. 在頁面中找到 "微信支付商戶號",即為你的商戶號（10位數字）

### 2.2 關聯 AppID 並獲取

1. 打開: `https://pay.weixin.qq.com`
2. 點擊頂部菜單 "產品中心"
3. 點擊左側 "AppID賬號管理"
4. 若未關聯,點擊 "關聯AppID":
   * 輸入你的公眾號/小程序 AppID
   * 前往對應公眾號/小程序後台確認授權
5. 關聯成功後,在列表中複製你的 AppID（以 `wx` 開頭）

### 2.3 設置 APIv3 密鑰

1. 打開: `https://pay.weixin.qq.com`
2. 點擊頂部菜單 "賬戶中心"
3. 點擊左側 "API安全"
4. 找到 "APIv3密鑰" 區域,點擊 "設置"
5. 使用管理員微信掃碼驗證身份
6. 輸入一個 **32位字符串** 作為密鑰（可包含大小寫字母和數字）
   * 示例: `Abc123DefGhi456Jkl789Mno012Pqr3`
7. 點擊確認,**立即保存這個密鑰**（頁面關閉後無法再次查看）

### 2.4 申請並下載 API 證書

1. 打開: `https://pay.weixin.qq.com`
2. 點擊頂部菜單 "賬戶中心"
3. 點擊左側 "API安全"
4. 找到 "商戶API證書" 區域,點擊 "申請證書"
5. 選擇 "使用CA簽發證書"
6. 使用管理員微信掃碼驗證
7. 按提示完成證書申請
8. 申請成功後,點擊 "下載證書"
9. 下載得到 `cert.zip` 壓縮包

### 2.5 提取證書文件內容

解壓 `cert.zip`,得到以下文件:

```
├── apiclient_key.pem      ← 私鑰（需要提取）
├── apiclient_cert.pem     ← 公鑰證書
└── apiclient_cert.p12     ← PKCS12格式
```

**提取私鑰 (PRIVATE\_KEY)**:

1. 找到 `apiclient_key.pem` 文件
2. **Windows**:右鍵 → 打開方式 → 記事本
3. **Mac**:右鍵 → 打開方式 → 文本編輯
4. 看到內容如下:

```
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC7...
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
-----END PRIVATE KEY-----
```

5. 按 `Ctrl+A`（Mac: `Cmd+A`）全選
6. 按 `Ctrl+C`（Mac: `Cmd+C`）複製
7. 粘貼到配置框中（**包括 BEGIN 和 END 那兩行**）

### 2.6 獲取證書序列號

**方式 A - 網頁提取**:

1. 打開: `https://pay.weixin.qq.com`
2. 點擊頂部菜單 "賬戶中心"
3. 點擊左側 "API安全"
4. 找到 "API證書" 區域
5. 在證書列表中,找到 "證書序列號" 列
6. 複製該序列號（約40位,如 `4B23C5D6E7F8A9B0C1D2E3F4A5B6C7D8E9F0A1B2`）

**方式 B - 命令行提取**:

```bash theme={null}
openssl x509 -in apiclient_cert.pem -noout -serial
```

輸出: `serial=4B23C5D6E7F8A9B0C1D2E3F4...`（複製等號後面的部分）

***

## 三、開通 H5 支付權限

1. 打開: `https://pay.weixin.qq.com`
2. 點擊頂部菜單 "產品中心"
3. 在產品列表中找到 "H5支付"
4. 點擊 "申請開通"
5. 填寫申請信息:
   * **H5支付域名**:你的網站域名（如 `www.example.com`）
   * **網站名稱**:你的網站名稱
   * **網站備案號**:ICP備案號
6. 點擊 "提交申請"
7. 等待審核（通常 1-3 個工作日）
8. 審核通過後,狀態變為 "已開通"

***

## 四、配置憑證到 superun

在 superun 平台配置以下 5 個環境變數:

在 **研發 → 技能庫 → 微信支付** 中設定以下環境變數:

| 變數名                     | 填入內容    | 來源                     |
| ----------------------- | ------- | ---------------------- |
| `WECHAT_MCH_ID`         | 商戶號     | 賬戶中心 → 商戶信息            |
| `WECHAT_APP_ID`         | AppID   | 產品中心 → AppID賬號管理       |
| `WECHAT_API_V3_KEY`     | APIv3密鑰 | 賬戶中心 → API安全 → APIv3密鑰 |
| `WECHAT_PRIVATE_KEY`    | 私鑰文件內容  | `apiclient_key.pem` 文件 |
| `WECHAT_CERT_SERIAL_NO` | 證書序列號   | 賬戶中心 → API安全 → API證書   |

<Warning>
  **重要提示**

  * **切勿在聊天中粘貼您的微信支付密鑰和私鑰.** 請在 **研發 → 技能庫 → 微信支付** 中透過環境變數進行設定.
  * 私鑰文件內容需要包含 `-----BEGIN PRIVATE KEY-----` 和 `-----END PRIVATE KEY-----` 這兩行.
  * 證書序列號需要與私鑰匹配,否則會出現 `SIGN_ERROR` 錯誤.
</Warning>

***

## 五、支付流程

```
用戶                    前端                     後端                    微信
 │                      │                        │                       │
 │── 選擇套餐,點擊購買 ──▶│                        │                       │
 │                      │── 調用 create-order ───▶│                       │
 │                      │                        │── 調用統一下單接口 ────▶│
 │                      │                        │◀── 返回 h5_url ────────│
 │                      │◀── 返回支付鏈接 ─────────│                       │
 │◀── 跳轉到微信支付頁面 ──│                        │                       │
 │                      │                        │                       │
 │────────────────── 用戶完成支付 ─────────────────────────────────────────▶│
 │                      │                        │◀── 支付結果回調 ────────│
 │                      │                        │── 更新訂單,激活會員 ──│
 │◀───────────────── 返回應用,顯示會員狀態 ─────────│                       │
```

### 使用聊天驅動流程

配置好環境變數後,您可以在聊天中描述需求:

* "添加微信支付功能,支持 H5 支付"
* "為我的產品頁面設置微信支付結賬"
* "創建訂閱功能,使用微信支付"

superun 會自動生成支付組件、數據庫表和支付邏輯.

***

## 六、常見錯誤

<AccordionGroup>
  <Accordion title="SIGN_ERROR 證書序列號有誤">
    序列號與私鑰不匹配.在 API安全 頁面確認序列號是否正確,確保 `WECHAT_CERT_SERIAL_NO` 與 `WECHAT_PRIVATE_KEY` 匹配.
  </Accordion>

  <Accordion title="NO_AUTH 產品權限未開通">
    H5支付未開通.前往產品中心申請開通 H5支付,等待審核通過.
  </Accordion>

  <Accordion title="PARAM_ERROR 域名不符">
    H5域名未配置.在 H5支付設置中添加正確的支付域名,確保與實際使用的域名一致.
  </Accordion>

  <Accordion title="其他錯誤">
    如果遇到其他錯誤,請檢查:

    * 環境變數是否正確配置
    * 商戶號、AppID 是否正確
    * APIv3 密鑰是否正確
    * 私鑰文件內容是否完整（包含 BEGIN 和 END 行）
    * 證書序列號是否正確
  </Accordion>
</AccordionGroup>

***

## 調試和故障排除

### 檢查配置

1. **瀏覽器控制台**:查看網絡請求和錯誤信息
2. **superun 雲計算 日誌**:檢查後端日誌中的錯誤信息
3. **微信支付商戶平台**:在商戶平台查看交易記錄和錯誤日誌

### 測試建議

1. 先在**測試環境**中測試支付功能
2. 使用微信支付的測試工具進行驗證
3. 確認所有環境變數都已正確配置
4. 檢查 H5 支付域名是否已正確配置

***

## 付費後解鎖內容（付費牆）

很多應用需要實現「用戶支付後才能查看報告/結果/內容」的場景。以下是推薦的實現方式：

### 實現思路

微信支付完成後，服務端透過**支付回調通知**確認支付狀態，再授權用戶訪問付費內容：

1. 用戶點擊「支付」→ 調起微信支付
2. 用戶完成支付 → 微信向你配置的 `notify_url` 發送支付結果通知
3. 服務端接收通知 → 驗簽成功後，在資料庫中將該用戶/訂單標記為「已支付」
4. 前端輪詢或接收推送 → 偵測到已支付狀態後，展示付費內容

### 告知 AI 的提示詞範例

```
我的應用需要實現：用戶完成微信支付後，才能查看測評結果報告。
請幫我實現：
1. 支付成功回調後，在資料庫 orders 表中將對應訂單的 status 標記為 paid
2. 結果報告頁面載入時，先查詢目前用戶的訂單狀態
3. 如果 status=paid，顯示完整報告內容
4. 如果未支付，顯示「請先完成支付」提示，並附帶支付按鈕
```

### 注意事項

* **以回調通知為準**：微信支付的前端跳轉（`return_url`）不可靠，應以後端收到 `notify_url` 回調為準
* **資料庫記錄支付狀態**：在 orders 表中新增 `payment_status` 欄位持久化支付結果
* **冪等處理**：同一筆訂單可能收到多次回調通知，確保重複處理不導致資料錯誤

***

<Card title="superun 網站" icon="globe" href="https://superun.com/web" horizontal>
  了解更多產品功能和示例.
</Card>