From c777fe5471380b0f7d357f54fa20468a6acb0986 Mon Sep 17 00:00:00 2001 From: erio Date: Sat, 11 Apr 2026 21:10:55 +0800 Subject: [PATCH] docs: add built-in payment configuration guide and update README - Add docs/PAYMENT.md and docs/PAYMENT_CN.md with full payment setup guide - Mark Sub2ApiPay as deprecated in ecosystem tables (payment is now built-in) - Add built-in payment system to features list in all 3 READMEs --- .gitignore | 2 + README.md | 5 +- README_CN.md | 5 +- README_JA.md | 5 +- docs/PAYMENT.md | 272 ++++++++++++++++++++++++++++++++++++++++++++ docs/PAYMENT_CN.md | 274 +++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 557 insertions(+), 6 deletions(-) create mode 100644 docs/PAYMENT.md create mode 100644 docs/PAYMENT_CN.md diff --git a/.gitignore b/.gitignore index 297c1d6f..1a92ea3e 100644 --- a/.gitignore +++ b/.gitignore @@ -127,6 +127,8 @@ deploy/docker-compose.override.yml .gocache/ vite.config.js docs/* +!docs/PAYMENT.md +!docs/PAYMENT_CN.md .serena/ .codex/ frontend/coverage/ diff --git a/README.md b/README.md index 25bef473..b64a7647 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,9 @@ Sub2API is an AI API gateway platform designed to distribute and manage API quot - **Smart Scheduling** - Intelligent account selection with sticky sessions - **Concurrency Control** - Per-user and per-account concurrency limits - **Rate Limiting** - Configurable request and token rate limits +- **Built-in Payment System** - Supports EasyPay, Alipay, WeChat Pay, and Stripe for user self-service top-up, no separate payment service needed ([Configuration Guide](docs/PAYMENT.md)) - **Admin Dashboard** - Web interface for monitoring and management -- **External System Integration** - Embed external systems (e.g. payment, ticketing) via iframe to extend the admin dashboard +- **External System Integration** - Embed external systems (e.g. ticketing) via iframe to extend the admin dashboard ## ❤️ Sponsors @@ -88,7 +89,7 @@ Community projects that extend or integrate with Sub2API: | Project | Description | Features | |---------|-------------|----------| -| [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) | Self-service payment system | Self-service top-up and subscription purchase; supports YiPay protocol, WeChat Pay, Alipay, Stripe; embeddable via iframe | +| ~~[Sub2ApiPay](https://github.com/touwaeriol/sub2apipay)~~ | ~~Self-service payment system~~ | **Now Built-in** — Payment is now integrated into Sub2API, no separate deployment needed. See [Payment Configuration Guide](docs/PAYMENT.md) | | [sub2api-mobile](https://github.com/ckken/sub2api-mobile) | Mobile admin console | Cross-platform app (iOS/Android/Web) for user management, account management, monitoring dashboard, and multi-backend switching; built with Expo + React Native | ## Tech Stack diff --git a/README_CN.md b/README_CN.md index 003a9530..5b6be04c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -41,8 +41,9 @@ Sub2API 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅的 - **智能调度** - 智能账号选择，支持粘性会话 - **并发控制** - 用户级和账号级并发限制 - **速率限制** - 可配置的请求和 Token 速率限制 +- **内置支付系统** - 支持 EasyPay 易支付、支付宝官方、微信官方、Stripe，用户自助充值，无需独立部署支付服务（[配置指南](docs/PAYMENT_CN.md)） - **管理后台** - Web 界面进行监控和管理 -- **外部系统集成** - 支持通过 iframe 嵌入外部系统（如支付、工单等），扩展管理后台功能 +- **外部系统集成** - 支持通过 iframe 嵌入外部系统（如工单等），扩展管理后台功能 ## ❤️ 赞助商 @@ -87,7 +88,7 @@ Sub2API 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅的 | 项目 | 说明 | 功能 | |------|------|------| -| [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) | 自助支付系统 | 用户自助充值、自助订阅购买；兼容易支付协议、微信官方支付、支付宝官方支付、Stripe；支持 iframe 嵌入管理后台 | +| ~~[Sub2ApiPay](https://github.com/touwaeriol/sub2apipay)~~ | ~~自助支付系统~~ | **已内置** — 支付功能已集成到 Sub2API 中，无需独立部署。详见 [支付配置指南](docs/PAYMENT_CN.md) | | [sub2api-mobile](https://github.com/ckken/sub2api-mobile) | 移动端管理控制台 | 跨平台应用（iOS/Android/Web），支持用户管理、账号管理、监控看板、多后端切换；基于 Expo + React Native 构建 | ## 技术栈 diff --git a/README_JA.md b/README_JA.md index 818e944b..4e7ae765 100644 --- a/README_JA.md +++ b/README_JA.md @@ -42,8 +42,9 @@ Sub2API は、AI 製品のサブスクリプションから API クォータを - **スマートスケジューリング** - スティッキーセッション付きのインテリジェントなアカウント選択 - **同時実行制御** - ユーザーごと・アカウントごとの同時実行数制限 - **レート制限** - 設定可能なリクエスト数およびトークンレート制限 +- **内蔵決済システム** - EasyPay、Alipay、WeChat Pay、Stripe に対応。ユーザーのセルフサービスチャージが可能で、別途決済サービスのデプロイは不要（[設定ガイド](docs/PAYMENT.md)） - **管理ダッシュボード** - 監視・管理のための Web インターフェース -- **外部システム連携** - 外部システム（決済、チケット管理など）を iframe 経由で管理ダッシュボードに埋め込み可能 +- **外部システム連携** - 外部システム（チケット管理など）を iframe 経由で管理ダッシュボードに埋め込み可能 ## ❤️ スポンサー @@ -87,7 +88,7 @@ Sub2API を拡張・統合するコミュニティプロジェクト: | プロジェクト | 説明 | 機能 | |---------|-------------|----------| -| [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) | セルフサービス決済システム | セルフサービスによるチャージおよびサブスクリプション購入。YiPay プロトコル、WeChat Pay、Alipay、Stripe 対応。iframe での埋め込み可能 | +| ~~[Sub2ApiPay](https://github.com/touwaeriol/sub2apipay)~~ | ~~セルフサービス決済システム~~ | **内蔵済み** — 決済機能は Sub2API に統合されました。別途デプロイは不要です。[決済設定ガイド](docs/PAYMENT.md)をご参照ください | | [sub2api-mobile](https://github.com/ckken/sub2api-mobile) | モバイル管理コンソール | ユーザー管理、アカウント管理、監視ダッシュボード、マルチバックエンド切り替えが可能なクロスプラットフォームアプリ（iOS/Android/Web）。Expo + React Native で構築 | ## 技術スタック diff --git a/docs/PAYMENT.md b/docs/PAYMENT.md new file mode 100644 index 00000000..c0fc1fdc --- /dev/null +++ b/docs/PAYMENT.md @@ -0,0 +1,272 @@ +# Payment System Configuration Guide + +Sub2API has a built-in payment system that enables user self-service top-up without deploying a separate payment service. + +--- + +## Table of Contents + +- [Supported Payment Methods](#supported-payment-methods) +- [Quick Start](#quick-start) +- [System Settings](#system-settings) +- [Provider Configuration](#provider-configuration) +- [Provider Instance Management](#provider-instance-management) +- [Webhook Configuration](#webhook-configuration) +- [Payment Flow](#payment-flow) +- [Migrating from Sub2ApiPay](#migrating-from-sub2apipay) + +--- + +## Supported Payment Methods + +| Provider | Payment Methods | Description | +|----------|----------------|-------------| +| **EasyPay** | Alipay, WeChat Pay | Third-party aggregation via EasyPay protocol | +| **Alipay (Direct)** | PC Page Pay, H5 Mobile Pay | Direct integration with Alipay Open Platform, auto-switches by device | +| **WeChat Pay (Direct)** | Native QR Code, H5 Pay | Direct integration with WeChat Pay APIv3, mobile-first H5 | +| **Stripe** | Card, Alipay, WeChat Pay, Link, etc. | International payments, multi-currency support | + +> Alipay/WeChat Pay direct and EasyPay can coexist. Direct channels connect to payment APIs directly with lower fees; EasyPay aggregates through third-party platforms with easier setup. + +--- + +## Quick Start + +1. Go to Admin Dashboard → **Settings** → **Payment Settings** tab +2. Enable **Payment** +3. Configure basic parameters (amount range, timeout, etc.) +4. Add at least one provider instance in **Provider Management** +5. Users can now top up from the frontend + +--- + +## System Settings + +Configure the following in Admin Dashboard **Settings → Payment Settings**: + +### Basic Settings + +| Setting | Description | Default | +|---------|-------------|---------| +| **Enable Payment** | Enable or disable the payment system | Off | +| **Product Name Prefix** | Prefix shown on payment page | - | +| **Product Name Suffix** | Suffix (e.g., "Credits") | - | +| **Minimum Amount** | Minimum single top-up amount | 1 | +| **Maximum Amount** | Maximum single top-up amount (empty = unlimited) | - | +| **Daily Limit** | Per-user daily cumulative limit (empty = unlimited) | - | +| **Order Timeout** | Order timeout in minutes (minimum 1) | 5 | +| **Max Pending Orders** | Maximum concurrent pending orders per user | 3 | +| **Load Balance Strategy** | Strategy for selecting provider instances | Least Amount | + +### Load Balance Strategies + +| Strategy | Description | +|----------|-------------| +| **Round Robin** | Distribute orders to instances in rotation | +| **Least Amount** | Prefer instances with the lowest daily cumulative amount | + +### Cancel Rate Limiting + +Prevents users from repeatedly creating and canceling orders: + +| Setting | Description | +|---------|-------------| +| **Enable Limit** | Toggle | +| **Window Mode** | Sliding / Fixed window | +| **Time Window** | Window duration | +| **Window Unit** | Minutes / Hours | +| **Max Cancels** | Maximum cancellations allowed within the window | + +### Help Information + +| Setting | Description | +|---------|-------------| +| **Help Image** | Customer service QR code or help image (supports upload) | +| **Help Text** | Instructions displayed on the payment page | + +--- + +## Provider Configuration + +Each provider type requires different credentials. Select the type when adding a new provider instance in **Provider Management → Add Provider**. + +### EasyPay + +Compatible with any payment service that implements the EasyPay protocol. + +| Parameter | Description | Required | +|-----------|-------------|----------| +| **Merchant ID (PID)** | EasyPay merchant ID | Yes | +| **Merchant Key (PKey)** | EasyPay merchant secret key | Yes | +| **API Base URL** | EasyPay API base address | Yes | +| **Notify URL** | Async callback URL for payment success | Yes | +| **Return URL** | Redirect URL after payment completion | No | +| **Alipay Channel ID** | Specify Alipay channel (optional) | No | +| **WeChat Channel ID** | Specify WeChat channel (optional) | No | + +### Alipay (Direct) + +Direct integration with Alipay Open Platform. Supports PC page pay and H5 mobile pay. + +| Parameter | Description | Required | +|-----------|-------------|----------| +| **AppID** | Alipay application AppID | Yes | +| **Private Key** | RSA2 application private key | Yes | +| **Alipay Public Key** | Alipay public key | Yes | +| **Notify URL** | Async callback URL | Yes | +| **Return URL** | Redirect URL after payment | No | + +### WeChat Pay (Direct) + +Direct integration with WeChat Pay APIv3. Supports Native QR code and H5 payment. + +| Parameter | Description | Required | +|-----------|-------------|----------| +| **AppID** | WeChat Pay AppID | Yes | +| **Merchant ID (MchID)** | WeChat Pay merchant ID | Yes | +| **Merchant API Private Key** | Merchant API private key (PEM format) | Yes | +| **Certificate Serial Number** | Merchant certificate serial number | Yes | +| **APIv3 Key** | 32-byte APIv3 key | Yes | +| **WeChat Pay Public Key** | WeChat Pay public key (PEM format) | Yes | +| **WeChat Pay Public Key ID** | WeChat Pay public key ID | Yes | +| **Notify URL** | Async callback URL | Yes | + +### Stripe + +International payment platform supporting multiple payment methods and currencies. + +| Parameter | Description | Required | +|-----------|-------------|----------| +| **Secret Key** | Stripe secret key (`sk_live_...` or `sk_test_...`) | Yes | +| **Publishable Key** | Stripe publishable key (`pk_live_...` or `pk_test_...`) | Yes | +| **Webhook Secret** | Stripe Webhook signing secret (`whsec_...`) | Yes | + +--- + +## Provider Instance Management + +You can create **multiple instances** of the same provider type for load balancing and risk control: + +- **Multi-instance load balancing** — Distribute orders via round-robin or least-amount strategy +- **Independent limits** — Each instance can have its own min/max amount and daily limit +- **Independent toggle** — Enable/disable individual instances without affecting others +- **Refund control** — Enable or disable refunds per instance +- **Payment methods** — Each instance can support a subset of payment methods +- **Ordering** — Drag to reorder instances + +### Instance Limit Configuration + +Each instance supports these limits: + +| Limit | Description | +|-------|-------------| +| **Minimum Amount** | Minimum order amount accepted by this instance | +| **Maximum Amount** | Maximum order amount accepted by this instance | +| **Daily Limit** | Daily cumulative transaction limit for this instance | + +> During load balancing, instances that exceed their limits are automatically skipped. + +--- + +## Webhook Configuration + +Payment callbacks are essential for the payment system to work correctly. + +### Callback URL Format + +| Provider | Callback URL | +|----------|-------------| +| **EasyPay** | `https://your-domain.com/api/v1/payment/easypay/notify` | +| **Alipay (Direct)** | `https://your-domain.com/api/v1/payment/alipay/notify` | +| **WeChat Pay (Direct)** | `https://your-domain.com/api/v1/payment/wxpay/notify` | +| **Stripe** | `https://your-domain.com/api/v1/payment/stripe/webhook` | + +> Replace `your-domain.com` with your actual domain. + +### Stripe Webhook Setup + +1. Log in to [Stripe Dashboard](https://dashboard.stripe.com/) +2. Go to **Developers → Webhooks** +3. Add an endpoint with the callback URL +4. Subscribe to events: `payment_intent.succeeded`, `payment_intent.payment_failed` +5. Copy the generated Webhook Secret (`whsec_...`) to your provider configuration + +### Important Notes + +- Callback URLs must use **HTTPS** (required by Stripe, strongly recommended for others) +- Ensure your firewall allows callback requests from payment platforms +- The system automatically verifies callback signatures to prevent forgery +- Balance top-up is processed automatically upon successful payment — no manual intervention needed + +--- + +## Payment Flow + +``` +User selects amount and payment method + │ + ▼ + Create Order (PENDING) + ├─ Validate amount range, pending order count, daily limit + ├─ Load balance to select provider instance + └─ Call provider to get payment info + │ + ▼ + User completes payment + ├─ EasyPay → QR code / H5 redirect + ├─ Alipay → PC page pay / H5 mobile pay + ├─ WeChat Pay → Native QR / H5 pay + └─ Stripe → Payment Element (card/Alipay/WeChat/etc.) + │ + ▼ + Webhook callback verified → Order PAID + │ + ▼ + Auto top-up to user balance → Order COMPLETED +``` + +### Order Status Reference + +| Status | Description | +|--------|-------------| +| `PENDING` | Waiting for user to complete payment | +| `PAID` | Payment confirmed, awaiting balance credit | +| `COMPLETED` | Balance credited successfully | +| `EXPIRED` | Timed out without payment | +| `CANCELLED` | Cancelled by user | +| `FAILED` | Balance credit failed, admin can retry | +| `REFUND_REQUESTED` | Refund requested | +| `REFUNDING` | Refund in progress | +| `REFUNDED` | Refund completed | + +### Timeout and Fallback + +- Before marking an order as expired, the background job queries the upstream payment status first +- If the user has actually paid but the callback was delayed, the system will reconcile automatically +- The background job runs every 60 seconds to check for timed-out orders + +--- + +## Migrating from Sub2ApiPay + +If you previously used [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) as an external payment system, you can migrate to the built-in payment system: + +### Key Differences + +| Aspect | Sub2ApiPay | Built-in Payment | +|--------|-----------|-----------------| +| Deployment | Separate service (Next.js + PostgreSQL) | Built into Sub2API, no extra deployment | +| Payment Methods | EasyPay, Alipay, WeChat, Stripe | Same | +| Configuration | Environment variables + separate admin UI | Unified in Sub2API admin dashboard | +| Top-up Integration | Via Admin API callback | Internal processing, more reliable | +| Subscription Plans | Supported | Not yet (planned) | +| Order Management | Separate admin interface | Integrated in Sub2API admin dashboard | + +### Migration Steps + +1. Enable payment in Sub2API admin dashboard and configure providers (use the same payment credentials) +2. Update webhook callback URLs to Sub2API's callback endpoints +3. Verify that new orders are processed correctly via built-in payment +4. Decommission the Sub2ApiPay service + +> **Note**: Historical order data from Sub2ApiPay will not be automatically migrated. Keep Sub2ApiPay running for a while to access historical records. diff --git a/docs/PAYMENT_CN.md b/docs/PAYMENT_CN.md new file mode 100644 index 00000000..33a5ace3 --- /dev/null +++ b/docs/PAYMENT_CN.md @@ -0,0 +1,274 @@ +# 支付系统配置指南 + +Sub2API 内置支付系统，支持用户自助充值，无需部署独立的支付服务。 + +--- + +## 目录 + +- [支持的支付方式](#支持的支付方式) +- [快速开始](#快速开始) +- [系统设置](#系统设置) +- [服务商配置](#服务商配置) +- [服务商实例管理](#服务商实例管理) +- [Webhook 配置](#webhook-配置) +- [支付流程](#支付流程) +- [从 Sub2ApiPay 迁移](#从-sub2apipay-迁移) + +--- + +## 支持的支付方式 + +| 服务商 | 支付方式 | 说明 | +|--------|---------|------| +| **EasyPay（易支付）** | 支付宝、微信支付 | 兼容易支付协议的第三方聚合支付 | +| **支付宝官方** | 支付宝 PC 页面支付、H5 手机网站支付 | 直接对接支付宝开放平台，自动根据终端切换 | +| **微信官方** | Native 扫码支付、H5 支付 | 直接对接微信支付 APIv3，移动端优先 H5 | +| **Stripe** | 银行卡、支付宝、微信支付、Link 等 | 国际支付，支持多币种 | + +> 支付宝官方 / 微信官方与 EasyPay 可以共存。官方渠道直接对接 API，资金直达商户账户，手续费更低；EasyPay 通过第三方平台聚合，接入门槛更低。 + +--- + +## 快速开始 + +1. 进入管理后台 → **设置** → **支付设置** 标签页 +2. 开启 **启用支付** +3. 配置基本参数（金额范围、超时时间等） +4. 在 **服务商管理** 中添加至少一个服务商实例 +5. 用户即可在前端页面进行充值 + +--- + +## 系统设置 + +在管理后台 **设置 → 支付设置** 中配置以下参数： + +### 基本设置 + +| 设置项 | 说明 | 默认值 | +|--------|------|--------| +| **启用支付** | 启用或禁用支付系统 | 关闭 | +| **商品名前缀** | 支付页面显示的商品名前缀 | - | +| **商品名后缀** | 商品名后缀（如"元"） | - | +| **最低金额** | 单笔最低充值金额 | 1 | +| **最高金额** | 单笔最高充值金额（留空表示不限制） | - | +| **每日限额** | 每用户每日累计充值上限（留空表示不限制） | - | +| **订单超时时间** | 订单超时分钟数，至少 1 分钟 | 5 | +| **最大待支付订单数** | 同一用户最大并行待支付订单数 | 3 | +| **负载均衡策略** | 多服务商实例时的选择策略 | 最少金额 | + +### 负载均衡策略 + +| 策略 | 说明 | +|------|------| +| **轮询（round-robin）** | 按顺序轮流分配到各服务商实例 | +| **最少金额（least-amount）** | 优先分配到当日累计金额最少的实例 | + +### 取消频率限制 + +防止用户频繁创建并取消订单： + +| 设置项 | 说明 | +|--------|------| +| **启用限制** | 开关 | +| **窗口模式** | 滚动窗口 / 固定窗口 | +| **时间窗口** | 窗口长度 | +| **窗口单位** | 分钟 / 小时 | +| **最大次数** | 窗口内允许的最大取消次数 | + +### 帮助信息 + +| 设置项 | 说明 | +|--------|------| +| **帮助图片** | 充值页面显示的客服二维码等图片（支持上传） | +| **帮助文本** | 充值页面显示的说明文字 | + +--- + +## 服务商配置 + +每种服务商需要不同的凭证和参数。在 **服务商管理 → 添加服务商** 中选择类型后填写。 + +### EasyPay（易支付） + +兼容任何 EasyPay 协议的支付服务商。 + +| 参数 | 说明 | 必填 | +|------|------|------| +| **商户 ID（PID）** | EasyPay 商户 ID | 是 | +| **商户密钥（PKey）** | EasyPay 商户密钥 | 是 | +| **API 地址** | EasyPay API 基础地址 | 是 | +| **异步回调地址** | 支付成功后的回调 URL | 是 | +| **同步跳转地址** | 支付完成后的跳转 URL | 否 | +| **支付宝通道 ID** | 指定支付宝通道（可选） | 否 | +| **微信通道 ID** | 指定微信通道（可选） | 否 | + +> **EasyPay 推荐**：[ZPay](https://z-pay.cn) 支持个人用户（无营业执照）每日 1 万元以内交易。支付渠道的安全性和合规性请自行鉴别。 + +### 支付宝官方 + +直接对接支付宝开放平台，支持 PC 页面支付和 H5 手机网站支付。 + +| 参数 | 说明 | 必填 | +|------|------|------| +| **AppID** | 支付宝应用 AppID | 是 | +| **应用私钥** | RSA2 应用私钥 | 是 | +| **支付宝公钥** | 支付宝公钥 | 是 | +| **异步回调地址** | 支付成功后的回调 URL | 是 | +| **同步跳转地址** | 支付完成后的跳转 URL | 否 | + +### 微信官方 + +直接对接微信支付 APIv3，支持 Native 扫码支付和 H5 支付。 + +| 参数 | 说明 | 必填 | +|------|------|------| +| **AppID** | 微信支付 AppID | 是 | +| **商户号（MchID）** | 微信支付商户号 | 是 | +| **商户 API 私钥** | 商户 API 私钥（PEM 格式） | 是 | +| **商户证书序列号** | 商户证书序列号 | 是 | +| **APIv3 密钥** | 32 位 APIv3 密钥 | 是 | +| **微信支付公钥** | 微信支付公钥（PEM 格式） | 是 | +| **微信支付公钥 ID** | 微信支付公钥 ID | 是 | +| **异步回调地址** | 支付成功后的回调 URL | 是 | + +### 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/easypay/notify` | +| **支付宝官方** | `https://your-domain.com/api/v1/payment/alipay/notify` | +| **微信官方** | `https://your-domain.com/api/v1/payment/wxpay/notify` | +| **Stripe** | `https://your-domain.com/api/v1/payment/stripe/webhook` | + +> 将 `your-domain.com` 替换为你的实际域名。 + +### 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 跳转 + ├─ 支付宝官方 → PC 页面支付 / H5 手机网站支付 + ├─ 微信官方 → Native 扫码 / H5 支付 + └─ 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 一段时间以便查询历史记录。