mirror of
https://gitee.com/wanwujie/sub2api
synced 2026-05-05 05:30:44 +08:00
Merge pull request #1576 from touwaeriol/feat/payment-docs
docs(payment): add built-in payment configuration guide and settings links
This commit is contained in:
Wesley Liddick
2
.gitignore
vendored
2
.gitignore
vendored
@@ -127,6 +127,8 @@ deploy/docker-compose.override.yml
|
|||||||
.gocache/
|
.gocache/
|
||||||
vite.config.js
|
vite.config.js
|
||||||
docs/*
|
docs/*
|
||||||
|
!docs/PAYMENT.md
|
||||||
|
!docs/PAYMENT_CN.md
|
||||||
.serena/
|
.serena/
|
||||||
.codex/
|
.codex/
|
||||||
frontend/coverage/
|
frontend/coverage/
|
||||||
|
|||||||
@@ -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
|
- **Smart Scheduling** - Intelligent account selection with sticky sessions
|
||||||
- **Concurrency Control** - Per-user and per-account concurrency limits
|
- **Concurrency Control** - Per-user and per-account concurrency limits
|
||||||
- **Rate Limiting** - Configurable request and token rate 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
|
- **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
|
## ❤️ Sponsors
|
||||||
|
|
||||||
@@ -88,7 +89,7 @@ Community projects that extend or integrate with Sub2API:
|
|||||||
|
|
||||||
| Project | Description | Features |
|
| 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 |
|
| [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
|
## Tech Stack
|
||||||
|
|||||||
@@ -41,8 +41,9 @@ Sub2API 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅的
|
|||||||
- **智能调度** - 智能账号选择，支持粘性会话
|
- **智能调度** - 智能账号选择，支持粘性会话
|
||||||
- **并发控制** - 用户级和账号级并发限制
|
- **并发控制** - 用户级和账号级并发限制
|
||||||
- **速率限制** - 可配置的请求和 Token 速率限制
|
- **速率限制** - 可配置的请求和 Token 速率限制
|
||||||
|
- **内置支付系统** - 支持 EasyPay 易支付、支付宝官方、微信官方、Stripe，用户自助充值，无需独立部署支付服务（[配置指南](docs/PAYMENT_CN.md)）
|
||||||
- **管理后台** - Web 界面进行监控和管理
|
- **管理后台** - 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 构建 |
|
| [sub2api-mobile](https://github.com/ckken/sub2api-mobile) | 移动端管理控制台 | 跨平台应用（iOS/Android/Web），支持用户管理、账号管理、监控看板、多后端切换；基于 Expo + React Native 构建 |
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
|
|||||||
@@ -42,8 +42,9 @@ Sub2API は、AI 製品のサブスクリプションから API クォータを
|
|||||||
- **スマートスケジューリング** - スティッキーセッション付きのインテリジェントなアカウント選択
|
- **スマートスケジューリング** - スティッキーセッション付きのインテリジェントなアカウント選択
|
||||||
- **同時実行制御** - ユーザーごと・アカウントごとの同時実行数制限
|
- **同時実行制御** - ユーザーごと・アカウントごとの同時実行数制限
|
||||||
- **レート制限** - 設定可能なリクエスト数およびトークンレート制限
|
- **レート制限** - 設定可能なリクエスト数およびトークンレート制限
|
||||||
|
- **内蔵決済システム** - EasyPay、Alipay、WeChat Pay、Stripe に対応。ユーザーのセルフサービスチャージが可能で、別途決済サービスのデプロイは不要（[設定ガイド](docs/PAYMENT.md)）
|
||||||
- **管理ダッシュボード** - 監視・管理のための Web インターフェース
|
- **管理ダッシュボード** - 監視・管理のための 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 で構築 |
|
| [sub2api-mobile](https://github.com/ckken/sub2api-mobile) | モバイル管理コンソール | ユーザー管理、アカウント管理、監視ダッシュボード、マルチバックエンド切り替えが可能なクロスプラットフォームアプリ（iOS/Android/Web）。Expo + React Native で構築 |
|
||||||
|
|
||||||
## 技術スタック
|
## 技術スタック
|
||||||
|
|||||||
273
docs/PAYMENT.md
Normal file
273
docs/PAYMENT.md
Normal file
@@ -0,0 +1,273 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
> **EasyPay Recommendation**: [ZPay](https://z-pay.cn/?uid=23808) (`https://z-pay.cn/?uid=23808`) is recommended as an EasyPay provider (link contains the referral code of [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) original author [@touwaeriol](https://github.com/touwaeriol) — feel free to remove it). ZPay supports **individual users** (no business license required) with up to 10,000 CNY daily transactions; business-licensed accounts have no limit. Please evaluate the security, reliability, and compliance of any third-party payment provider on your own — this project does not endorse or guarantee any of them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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**.
|
||||||
|
|
||||||
|
> **Callback URLs are auto-generated**: When adding a provider, the Notify URL and Return URL are automatically constructed from your site domain. You only need to confirm the domain is correct.
|
||||||
|
|
||||||
|
### 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 |
|
||||||
|
| **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 |
|
||||||
|
|
||||||
|
### 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 |
|
||||||
|
| **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 | No |
|
||||||
|
| **Certificate Serial Number** | Merchant certificate serial number | No |
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
When adding a provider, the system auto-generates callback URLs from your site domain:
|
||||||
|
|
||||||
|
| Provider | Callback Path |
|
||||||
|
|----------|-------------|
|
||||||
|
| **EasyPay** | `https://your-domain.com/api/v1/payment/webhook/easypay` |
|
||||||
|
| **Alipay (Direct)** | `https://your-domain.com/api/v1/payment/webhook/alipay` |
|
||||||
|
| **WeChat Pay (Direct)** | `https://your-domain.com/api/v1/payment/webhook/wxpay` |
|
||||||
|
| **Stripe** | `https://your-domain.com/api/v1/payment/webhook/stripe` |
|
||||||
|
|
||||||
|
> Replace `your-domain.com` with your actual domain. For EasyPay / Alipay / WeChat Pay, the callback URL is auto-filled when adding the provider — no manual configuration needed.
|
||||||
|
|
||||||
|
### 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.
|
||||||
273
docs/PAYMENT_CN.md
Normal file
273
docs/PAYMENT_CN.md
Normal file
@@ -0,0 +1,273 @@
|
|||||||
|
# 支付系统配置指南
|
||||||
|
|
||||||
|
Sub2API 内置支付系统，支持用户自助充值，无需部署独立的支付服务。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
- [支持的支付方式](#支持的支付方式)
|
||||||
|
- [快速开始](#快速开始)
|
||||||
|
- [系统设置](#系统设置)
|
||||||
|
- [服务商配置](#服务商配置)
|
||||||
|
- [服务商实例管理](#服务商实例管理)
|
||||||
|
- [Webhook 配置](#webhook-配置)
|
||||||
|
- [支付流程](#支付流程)
|
||||||
|
- [从 Sub2ApiPay 迁移](#从-sub2apipay-迁移)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 支持的支付方式
|
||||||
|
|
||||||
|
| 服务商 | 支付方式 | 说明 |
|
||||||
|
|--------|---------|------|
|
||||||
|
| **EasyPay（易支付）** | 支付宝、微信支付 | 兼容易支付协议的第三方聚合支付 |
|
||||||
|
| **支付宝官方** | 支付宝 PC 页面支付、H5 手机网站支付 | 直接对接支付宝开放平台，自动根据终端切换 |
|
||||||
|
| **微信官方** | Native 扫码支付、H5 支付 | 直接对接微信支付 APIv3，移动端优先 H5 |
|
||||||
|
| **Stripe** | 银行卡、支付宝、微信支付、Link 等 | 国际支付，支持多币种 |
|
||||||
|
|
||||||
|
> 支付宝官方 / 微信官方与 EasyPay 可以共存。官方渠道直接对接 API，资金直达商户账户，手续费更低；EasyPay 通过第三方平台聚合，接入门槛更低。
|
||||||
|
|
||||||
|
> **EasyPay 推荐**：个人推荐 [ZPay](https://z-pay.cn/?uid=23808)（`https://z-pay.cn/?uid=23808`）作为 EasyPay 服务商（链接含 [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) 原作者 [@touwaeriol](https://github.com/touwaeriol) 的邀请码，介意可去掉）。ZPay 支持**个人用户**（无营业执照）每日 1 万元以内交易；拥有营业执照则无限额。支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
1. 进入管理后台 → **设置** → **支付设置** 标签页
|
||||||
|
2. 开启 **启用支付**
|
||||||
|
3. 配置基本参数（金额范围、超时时间等）
|
||||||
|
4. 在 **服务商管理** 中添加至少一个服务商实例
|
||||||
|
5. 用户即可在前端页面进行充值
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 系统设置
|
||||||
|
|
||||||
|
在管理后台 **设置 → 支付设置** 中配置以下参数：
|
||||||
|
|
||||||
|
### 基本设置
|
||||||
|
|
||||||
|
| 设置项 | 说明 | 默认值 |
|
||||||
|
|--------|------|--------|
|
||||||
|
| **启用支付** | 启用或禁用支付系统 | 关闭 |
|
||||||
|
| **商品名前缀** | 支付页面显示的商品名前缀 | - |
|
||||||
|
| **商品名后缀** | 商品名后缀（如"元"） | - |
|
||||||
|
| **最低金额** | 单笔最低充值金额 | 1 |
|
||||||
|
| **最高金额** | 单笔最高充值金额（留空表示不限制） | - |
|
||||||
|
| **每日限额** | 每用户每日累计充值上限（留空表示不限制） | - |
|
||||||
|
| **订单超时时间** | 订单超时分钟数，至少 1 分钟 | 5 |
|
||||||
|
| **最大待支付订单数** | 同一用户最大并行待支付订单数 | 3 |
|
||||||
|
| **负载均衡策略** | 多服务商实例时的选择策略 | 最少金额 |
|
||||||
|
|
||||||
|
### 负载均衡策略
|
||||||
|
|
||||||
|
| 策略 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| **轮询（round-robin）** | 按顺序轮流分配到各服务商实例 |
|
||||||
|
| **最少金额（least-amount）** | 优先分配到当日累计金额最少的实例 |
|
||||||
|
|
||||||
|
### 取消频率限制
|
||||||
|
|
||||||
|
防止用户频繁创建并取消订单：
|
||||||
|
|
||||||
|
| 设置项 | 说明 |
|
||||||
|
|--------|------|
|
||||||
|
| **启用限制** | 开关 |
|
||||||
|
| **窗口模式** | 滚动窗口 / 固定窗口 |
|
||||||
|
| **时间窗口** | 窗口长度 |
|
||||||
|
| **窗口单位** | 分钟 / 小时 |
|
||||||
|
| **最大次数** | 窗口内允许的最大取消次数 |
|
||||||
|
|
||||||
|
### 帮助信息
|
||||||
|
|
||||||
|
| 设置项 | 说明 |
|
||||||
|
|--------|------|
|
||||||
|
| **帮助图片** | 充值页面显示的客服二维码等图片（支持上传） |
|
||||||
|
| **帮助文本** | 充值页面显示的说明文字 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 服务商配置
|
||||||
|
|
||||||
|
每种服务商需要不同的凭证和参数。在 **服务商管理 → 添加服务商** 中选择类型后填写。
|
||||||
|
|
||||||
|
> **回调地址自动生成**：添加服务商时，异步回调地址（Notify URL）和同步跳转地址（Return URL）由系统根据你的站点域名自动拼接，无需手动填写。管理员只需确认域名正确即可。
|
||||||
|
|
||||||
|
### EasyPay（易支付）
|
||||||
|
|
||||||
|
兼容任何 EasyPay 协议的支付服务商。
|
||||||
|
|
||||||
|
| 参数 | 说明 | 必填 |
|
||||||
|
|------|------|------|
|
||||||
|
| **商户 ID（PID）** | EasyPay 商户 ID | 是 |
|
||||||
|
| **商户密钥（PKey）** | EasyPay 商户密钥 | 是 |
|
||||||
|
| **API 地址** | EasyPay API 基础地址 | 是 |
|
||||||
|
| **支付宝通道 ID** | 指定支付宝通道（可选） | 否 |
|
||||||
|
| **微信通道 ID** | 指定微信通道（可选） | 否 |
|
||||||
|
|
||||||
|
### 支付宝官方
|
||||||
|
|
||||||
|
直接对接支付宝开放平台，支持 PC 页面支付和 H5 手机网站支付。
|
||||||
|
|
||||||
|
| 参数 | 说明 | 必填 |
|
||||||
|
|------|------|------|
|
||||||
|
| **AppID** | 支付宝应用 AppID | 是 |
|
||||||
|
| **应用私钥** | RSA2 应用私钥 | 是 |
|
||||||
|
| **支付宝公钥** | 支付宝公钥 | 是 |
|
||||||
|
|
||||||
|
### 微信官方
|
||||||
|
|
||||||
|
直接对接微信支付 APIv3，支持 Native 扫码支付和 H5 支付。
|
||||||
|
|
||||||
|
| 参数 | 说明 | 必填 |
|
||||||
|
|------|------|------|
|
||||||
|
| **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 跳转
|
||||||
|
├─ 支付宝官方 → 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 一段时间以便查询历史记录。
|
||||||
@@ -4444,10 +4444,12 @@ export default {
|
|||||||
payment: {
|
payment: {
|
||||||
title: 'Payment Settings',
|
title: 'Payment Settings',
|
||||||
description: 'Configure payment system options',
|
description: 'Configure payment system options',
|
||||||
|
configGuide: 'Configuration Guide',
|
||||||
enabled: 'Enable Payment',
|
enabled: 'Enable Payment',
|
||||||
enabledHint: 'Enable or disable the payment system',
|
enabledHint: 'Enable or disable the payment system',
|
||||||
enabledPaymentTypes: 'Enabled Providers',
|
enabledPaymentTypes: 'Enabled Providers',
|
||||||
enabledPaymentTypesHint: 'Disabling a provider will also disable its instances',
|
enabledPaymentTypesHint: 'Disabling a provider will also disable its instances.',
|
||||||
|
findProvider: 'Looking for a suitable EasyPay provider?',
|
||||||
minAmount: 'Minimum Amount',
|
minAmount: 'Minimum Amount',
|
||||||
maxAmount: 'Maximum Amount',
|
maxAmount: 'Maximum Amount',
|
||||||
dailyLimit: 'Daily Limit',
|
dailyLimit: 'Daily Limit',
|
||||||
|
|||||||
@@ -4608,10 +4608,12 @@ export default {
|
|||||||
payment: {
|
payment: {
|
||||||
title: '支付设置',
|
title: '支付设置',
|
||||||
description: '配置支付系统选项',
|
description: '配置支付系统选项',
|
||||||
|
configGuide: '支付配置指南',
|
||||||
enabled: '启用支付',
|
enabled: '启用支付',
|
||||||
enabledHint: '启用或禁用支付系统',
|
enabledHint: '启用或禁用支付系统',
|
||||||
enabledPaymentTypes: '启用的服务商',
|
enabledPaymentTypes: '启用的服务商',
|
||||||
enabledPaymentTypesHint: '禁用服务商将同时禁用对应的实例',
|
enabledPaymentTypesHint: '禁用服务商将同时禁用对应的实例。',
|
||||||
|
findProvider: '正在寻找合适的 EasyPay 服务商？',
|
||||||
minAmount: '最低金额',
|
minAmount: '最低金额',
|
||||||
maxAmount: '最高金额',
|
maxAmount: '最高金额',
|
||||||
dailyLimit: '每日限额',
|
dailyLimit: '每日限额',
|
||||||
|
|||||||
@@ -2121,7 +2121,13 @@
|
|||||||
<div class="card">
|
<div class="card">
|
||||||
<div class="border-b border-gray-100 px-6 py-4 dark:border-dark-700">
|
<div class="border-b border-gray-100 px-6 py-4 dark:border-dark-700">
|
||||||
<h2 class="text-lg font-semibold text-gray-900 dark:text-white">{{ t('admin.settings.payment.title') }}</h2>
|
<h2 class="text-lg font-semibold text-gray-900 dark:text-white">{{ t('admin.settings.payment.title') }}</h2>
|
||||||
<p class="mt-1 text-sm text-gray-500 dark:text-gray-400">{{ t('admin.settings.payment.description') }}</p>
|
<p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
|
||||||
|
{{ t('admin.settings.payment.description') }}
|
||||||
|
<a :href="locale === 'zh' ? 'https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT_CN.md' : 'https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT.md'" target="_blank" rel="noopener noreferrer" class="ml-2 inline-flex items-center text-primary-600 hover:text-primary-700 dark:text-primary-400 dark:hover:text-primary-300">
|
||||||
|
<svg class="mr-0.5 h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" /></svg>
|
||||||
|
{{ t('admin.settings.payment.configGuide') }}
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="space-y-4 p-6">
|
<div class="space-y-4 p-6">
|
||||||
<!-- Enable toggle -->
|
<!-- Enable toggle -->
|
||||||
@@ -2196,6 +2202,13 @@
|
|||||||
]"
|
]"
|
||||||
>{{ pt.label }}</button>
|
>{{ pt.label }}</button>
|
||||||
</div>
|
</div>
|
||||||
|
<p class="mt-2 text-xs text-gray-400 dark:text-gray-500">
|
||||||
|
{{ t('admin.settings.payment.enabledPaymentTypesHint') }}
|
||||||
|
<a :href="locale === 'zh' ? 'https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT_CN.md#%E6%94%AF%E6%8C%81%E7%9A%84%E6%94%AF%E4%BB%98%E6%96%B9%E5%BC%8F' : 'https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT.md#supported-payment-methods'" target="_blank" rel="noopener noreferrer" class="ml-1 text-primary-500 hover:text-primary-600 dark:text-primary-400 dark:hover:text-primary-300">
|
||||||
|
{{ t('admin.settings.payment.findProvider') }}
|
||||||
|
<svg class="mb-0.5 ml-0.5 inline h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" /></svg>
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
<!-- Row 5: Help image + text -->
|
<!-- Row 5: Help image + text -->
|
||||||
<div class="grid grid-cols-2 gap-3">
|
<div class="grid grid-cols-2 gap-3">
|
||||||
@@ -2536,7 +2549,7 @@ import {
|
|||||||
parseRegistrationEmailSuffixWhitelistInput
|
parseRegistrationEmailSuffixWhitelistInput
|
||||||
} from '@/utils/registrationEmailPolicy'
|
} from '@/utils/registrationEmailPolicy'
|
||||||
|
|
||||||
const { t } = useI18n()
|
const { t, locale } = useI18n()
|
||||||
const appStore = useAppStore()
|
const appStore = useAppStore()
|
||||||
const adminSettingsStore = useAdminSettingsStore()
|
const adminSettingsStore = useAdminSettingsStore()
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user