# 支付系统配置指南

Sub2API 内置支付系统，支持用户自助充值，无需部署独立的支付服务。

---

## 目录

- [支持的支付方式](#支持的支付方式)
- [快速开始](#快速开始)
- [系统设置](#系统设置)
- [服务商配置](#服务商配置)
- [服务商实例管理](#服务商实例管理)
- [Webhook 配置](#webhook-配置)
- [支付流程](#支付流程)
- [从 Sub2ApiPay 迁移](#从-sub2apipay-迁移)

---

## 支持的支付方式

| 服务商 | 支付方式 | 说明 |
|--------|---------|------|
| **EasyPay（易支付）** | 支付宝、微信支付 | 兼容易支付协议的第三方聚合支付 |
| **支付宝官方** | 桌面二维码扫码、移动端支付宝跳转 | 直接对接支付宝开放平台，桌面端返回二维码，移动端返回 WAP/唤起链接 |
| **微信官方** | Native 扫码、H5、公众号/JSAPI 支付 | 直接对接微信支付 APIv3，按终端环境自动分流 |
| **Stripe** | 银行卡、支付宝、微信支付、Link 等 | 国际支付，支持多币种 |

> 支付宝官方 / 微信官方与易支付可以同时作为后台服务商实例存在，但前台始终只展示 `支付宝`、`微信支付` 两个可见按钮。管理员需要分别为这两个按钮选择唯一支付来源：官方或易支付。官方渠道直接对接 API，资金直达商户账户，手续费更低；易支付通过第三方平台聚合，接入门槛更低。

> **易支付服务商推荐**：以下两家均为兼容易支付协议的第三方聚合支付，按资金通道与结算方式选择：
>
> - **国内渠道 / 人民币结算** — [ZPay](https://z-pay.cn/?uid=23808)（`https://z-pay.cn/?uid=23808`）：支付宝 / 微信官方 API 直连，手续费 **1.6%**；资金直达商家账户，**T+1 自动到账**。支持**个人用户**（无营业执照）每日 1 万元以内交易；拥有营业执照则无限额。链接含 [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) 原作者 [@touwaeriol](https://github.com/touwaeriol) 的邀请码，介意可去掉。
> - **国际渠道 / USDT 或美元结算** — [启润支付](https://kyren.top/?code=SUB2API)（`https://kyren.top/?code=SUB2API`）：为 AI 项目提供低门槛国际收款通道，支持国际版微信支付与支付宝，本地货币支付、美元结算。手续费：微信 2%、支付宝 2.5%；提现 0.1%（最低 40 美元、最高 150 美元），以 **USDT 或美元**到账。无资质审核、注册即用，使用门槛最低；提现门槛略高，适合**不使用国内支付渠道、无法接受 Stripe 高达 6%+ 手续费、流水较大，且拥有美元或 USDT 渠道可接收提现资金**的用户。启润支付开户费 200 美元，通过本链接注册（含 Sub2Api 作者 [@Wei-Shaw](https://github.com/Wei-Shaw) 邀请码）可**免开户费**，介意可去掉。
>
> 支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。

---

## 快速开始

1. 进入管理后台 → **设置** → **支付设置** 标签页
2. 开启 **启用支付**
3. 配置基本参数（金额范围、超时时间等）
4. 在 **服务商管理** 中添加至少一个服务商实例
5. 用户即可在前端页面进行充值

---

## 系统设置

在管理后台 **设置 → 支付设置** 中配置以下参数：

### 基本设置

| 设置项 | 说明 | 默认值 |
|--------|------|--------|
| **启用支付** | 启用或禁用支付系统 | 关闭 |
| **商品名前缀** | 支付页面显示的商品名前缀 | - |
| **商品名后缀** | 商品名后缀（如"元"） | - |
| **最低金额** | 单笔最低充值金额 | 1 |
| **最高金额** | 单笔最高充值金额（留空表示不限制） | - |
| **每日限额** | 每用户每日累计充值上限（留空表示不限制） | - |
| **订单超时时间** | 订单超时分钟数，至少 1 分钟 | 30 |
| **最大待支付订单数** | 同一用户最大并行待支付订单数 | 3 |
| **负载均衡策略** | 多服务商实例时的选择策略 | 轮询 |

### 前台可见支付方式路由

当前版本对用户统一展示支付方式，不区分官方渠道还是易支付：

- **支付宝**：后台启用后，需要额外指定该按钮路由到 `支付宝官方` 或 `易支付支付宝`
- **微信支付**：后台启用后，需要额外指定该按钮路由到 `微信官方` 或 `易支付微信`
- 同一个可见支付方式在同一时刻只能路由到一个来源
- 支付来源未选择时，即使对应按钮被开启，前台也不会暴露该支付方式

### 负载均衡策略

| 策略 | 说明 |
|------|------|
| **轮询（round-robin）** | 按顺序轮流分配到各服务商实例 |
| **最少金额（least-amount）** | 优先分配到当日累计金额最少的实例 |

### 取消频率限制

防止用户频繁创建并取消订单：

| 设置项 | 说明 |
|--------|------|
| **启用限制** | 开关 |
| **窗口模式** | 滚动窗口 / 固定窗口 |
| **时间窗口** | 窗口长度 |
| **窗口单位** | 分钟 / 小时 |
| **最大次数** | 窗口内允许的最大取消次数 |

### 帮助信息

| 设置项 | 说明 |
|--------|------|
| **帮助图片** | 充值页面显示的客服二维码等图片（支持上传） |
| **帮助文本** | 充值页面显示的说明文字 |

---

## 服务商配置

每种服务商需要不同的凭证和参数。在 **服务商管理 → 添加服务商** 中选择类型后填写。

> **回调地址自动生成**：添加服务商时，异步回调地址（Notify URL）和同步跳转地址（Return URL）由系统根据你的站点域名自动拼接，无需手动填写。管理员只需确认域名正确即可。

### EasyPay（易支付）

兼容任何 EasyPay 协议的支付服务商。

| 参数 | 说明 | 必填 |
|------|------|------|
| **商户 ID（PID）** | EasyPay 商户 ID | 是 |
| **商户密钥（PKey）** | EasyPay 商户密钥 | 是 |
| **API 地址** | EasyPay API 基础地址 | 是 |
| **支付宝通道 ID** | 指定支付宝通道（可选） | 否 |
| **微信通道 ID** | 指定微信通道（可选） | 否 |

### 支付宝官方

直接对接支付宝开放平台。移动端走支付宝手机网站支付跳转；桌面端优先使用当面付返回扫码串，若商户未开通当面付则回退到电脑网站支付，并将收银台链接同时返回给前端用于渲染二维码或直接打开支付页。

| 参数 | 说明 | 必填 |
|------|------|------|
| **AppID** | 支付宝应用 AppID | 是 |
| **应用私钥** | RSA2 应用私钥 | 是 |
| **支付宝公钥** | 支付宝公钥 | 是 |

### 微信官方

直接对接微信支付 APIv3，支持 Native 扫码支付、H5 支付，以及在微信环境内的公众号/JSAPI 支付。

| 参数 | 说明 | 必填 |
|------|------|------|
| **AppID** | 微信支付 AppID | 是 |
| **商户号（MchID）** | 微信支付商户号 | 是 |
| **商户 API 私钥** | 商户 API 私钥（PEM 格式） | 是 |
| **APIv3 密钥** | 32 位 APIv3 密钥 | 是 |
| **微信支付公钥** | 微信支付公钥（PEM 格式） | 是 |
| **微信支付公钥 ID** | 微信支付公钥 ID | 是 |
| **商户证书序列号** | 商户证书序列号 | 是 |

### Stripe

国际支付平台，支持多种支付方式和币种。

| 参数 | 说明 | 必填 |
|------|------|------|
| **Secret Key** | Stripe 密钥（`sk_live_...` 或 `sk_test_...`） | 是 |
| **Publishable Key** | Stripe 可公开密钥（`pk_live_...` 或 `pk_test_...`） | 是 |
| **Webhook Secret** | Stripe Webhook 签名密钥（`whsec_...`） | 是 |

---

## 服务商实例管理

同一种服务商可以创建**多个实例**，实现负载均衡和风控：

- **多实例负载均衡** — 按轮询或最少金额策略分流订单
- **独立限额** — 每个实例可独立配置单笔最小/最大金额和每日限额
- **独立启停** — 可单独启用/禁用某个实例，不影响其他实例
- **退款控制** — 每个实例可单独开启或关闭退款功能
- **支付方式** — 每个实例可选择支持的支付方式子集
- **排序** — 拖拽调整实例顺序

### 实例限额配置

每个实例支持以下限额：

| 限额项 | 说明 |
|--------|------|
| **单笔最小金额** | 该实例接受的最小订单金额 |
| **单笔最大金额** | 该实例接受的最大订单金额 |
| **每日限额** | 该实例每日累计交易上限 |

> 负载均衡时，系统会自动跳过超出限额的实例。

---

## Webhook 配置

支付回调是支付系统的核心环节，必须正确配置：

### 回调地址格式

添加服务商时，系统会自动根据站点域名拼接回调地址，格式如下：

| 服务商 | 回调路径 |
|--------|---------|
| **EasyPay** | `https://your-domain.com/api/v1/payment/webhook/easypay` |
| **支付宝官方** | `https://your-domain.com/api/v1/payment/webhook/alipay` |
| **微信官方** | `https://your-domain.com/api/v1/payment/webhook/wxpay` |
| **Stripe** | `https://your-domain.com/api/v1/payment/webhook/stripe` |

> 将 `your-domain.com` 替换为你的实际域名。EasyPay / 支付宝 / 微信的回调地址在添加服务商时自动填入，无需手动配置。

### Stripe Webhook 设置

1. 登录 [Stripe Dashboard](https://dashboard.stripe.com/)
2. 进入 **Developers → Webhooks**
3. 添加端点，填写回调地址
4. 订阅事件：`payment_intent.succeeded`、`payment_intent.payment_failed`
5. 将生成的 Webhook Secret（`whsec_...`）填入服务商配置

### 注意事项

- 回调地址必须是 **HTTPS**（Stripe 强制要求，其他服务商强烈推荐）
- 确保服务器防火墙允许支付平台的回调请求
- 系统会自动进行签名验证，防止伪造回调
- 支付成功后自动完成余额充值，无需人工干预

---

## 支付流程

```
用户选择充值金额和支付方式
       │
       ▼
  创建订单 (PENDING)
  ├─ 校验金额范围、待支付订单数、每日限额
  ├─ 负载均衡选择服务商实例
  └─ 调用服务商获取支付信息
       │
       ▼
  用户完成支付
  ├─ EasyPay    → 扫码 / H5 跳转
  ├─ 支付宝官方  → 桌面扫码单（当面付优先，电脑网站支付回退）/ 移动端支付宝跳转
  ├─ 微信官方    → 桌面 Native 扫码 / 非微信 H5 / 微信内 JSAPI
  └─ Stripe     → Payment Element（银行卡/支付宝/微信等）
       │
       ▼
  支付回调验签 → 订单 PAID
       │
       ▼
  自动充值到用户余额 → 订单 COMPLETED
```

### 订单状态说明

| 状态 | 说明 |
|------|------|
| `PENDING` | 待支付，等待用户完成支付 |
| `PAID` | 已支付，等待充值到账 |
| `COMPLETED` | 已完成，余额已到账 |
| `EXPIRED` | 已过期，超时未支付 |
| `CANCELLED` | 已取消，用户主动取消 |
| `FAILED` | 充值失败，可管理员重试 |
| `REFUND_REQUESTED` | 已申请退款 |
| `REFUNDING` | 退款处理中 |
| `REFUNDED` | 已退款 |

### 超时与兜底

- 订单超时后，后台任务会先查询上游支付状态再标记过期
- 如果用户实际已支付但回调延迟，系统会通过查询补单
- 后台任务每 60 秒执行一次超时检查

---

## 从 Sub2ApiPay 迁移

如果你之前使用 [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) 作为外部支付系统，现在可以迁移到内置支付：

### 主要差异

| 对比项 | Sub2ApiPay | 内置支付 |
|--------|-----------|---------|
| 部署方式 | 独立服务（Next.js + PostgreSQL） | 内置于 Sub2API，无需额外部署 |
| 支付方式 | EasyPay、支付宝、微信、Stripe | 相同 |
| 配置方式 | 环境变量 + 独立管理后台 | Sub2API 管理后台内统一配置 |
| 充值对接 | 通过 Admin API 回调 | 内部直接处理，更可靠 |
| 订阅套餐 | 支持 | 暂不支持（计划中） |
| 订单管理 | 独立管理界面 | 集成在 Sub2API 管理后台 |

### 迁移步骤

1. 在 Sub2API 管理后台启用支付并配置服务商（使用相同的支付凭证）
2. 更新 Webhook 回调地址为 Sub2API 的回调地址
3. 确认新订单通过内置支付正常处理
4. 停用 Sub2ApiPay 服务

> **注意**：Sub2ApiPay 中的历史订单数据不会自动迁移。建议保留 Sub2ApiPay 一段时间以便查询历史记录。
