> ## 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>