wanwu/sub2apipay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: README重构 — EasyPay前置、支付宝/微信改称官方、集成说明增加管理后台端点

Browse Source 
- GitHub About 双语描述
- "Stripe 国际信用卡" → "Stripe"
- EasyPay 放在支付服务商最前面
- "支付宝直连" → "支付宝官方"、"微信支付直连" → "微信官方"
- 集成到 Sub2API 章节重写：用户端页面 + 管理后台端点完整列表
- 管理后台集成无需带 query 参数
- "使用第三方聚合支付时" → "使用第三方平台时"
- 中英文 README 同步更新
This commit is contained in:
erio
2026-03-14 03:53:20 +08:00
parent 886389939e
commit 6d01fcb822
2 changed files with 220 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
README.en.md
View File

@@ -2,7 +2,7 @@
**Language**: [中文](./README.md) | English (current)
Sub2ApiPay is a self-hosted recharge payment gateway built for the [Sub2API](https://sub2api.com) platform. It supports Alipay, WeChat Pay (via EasyPay aggregator), and Stripe. Once a payment is confirmed, the system automatically calls the Sub2API management API to credit the user's balance — no manual intervention required.
Sub2ApiPay is a self-hosted payment gateway built for the [Sub2API](https://sub2api.com) platform. It supports four payment channels — **EasyPay** (aggregated Alipay/WeChat Pay), **Alipay** (official), **WeChat Pay** (official), and **Stripe** — with both pay-as-you-go balance top-up and subscription plans. Once a payment is confirmed, the system automatically calls the Sub2API management API to credit the user's balance or activate the subscription — no manual intervention required.
---
@@ -16,19 +16,22 @@ Sub2ApiPay is a self-hosted recharge payment gateway built for the [Sub2API](htt
- [Sub2API Integration](#sub2api-integration)
- [Admin Panel](#admin-panel)
- [Payment Flow](#payment-flow)
- [API Endpoints](#api-endpoints)
- [Development](#development)
---
## Features
- **Multiple Payment Methods** — Alipay, WeChat Pay (EasyPay), Stripe credit card
- **Four Payment Channels** — EasyPay aggregation, Alipay (official), WeChat Pay (official), Stripe
- **Dual Billing Modes** — Pay-as-you-go balance top-up + subscription plans
- **Auto Balance Credit** — Automatically calls Sub2API after payment verification, fully hands-free
- **Full Order Lifecycle** — Auto-expiry, user cancellation, admin cancellation, refunds
- **Limit Controls** — Configurable per-transaction cap and daily cumulative cap per user
- **Security** — Token auth, MD5/Webhook signature verification, timing-safe comparison, full audit log
- **Responsive UI** — PC + mobile adaptive layout, dark mode support, iframe embed support
- **Admin Panel** — Order list (pagination/filtering), order details, retry recharge, refunds
- **Limit Controls** — Per-transaction cap, daily per-user cap, daily per-channel global cap
- **Security** — Token auth, RSA2/MD5/Webhook signature verification, timing-safe comparison, full audit log
- **Responsive UI** — PC + mobile adaptive layout, dark/light theme, iframe embed support
- **Bilingual** — Automatic Chinese/English interface adaptation
- **Admin Panel** — Dashboard, order management (pagination/filtering/retry/refund), channel & subscription management
---
@@ -99,22 +102,16 @@ See [`.env.example`](./.env.example) for the full template.
**Step 1**: Declare which payment providers to load via `PAYMENT_PROVIDERS` (comma-separated):
```env
# EasyPay only
# Available: easypay, alipay, wxpay, stripe
# Example: EasyPay only
PAYMENT_PROVIDERS=easypay
# Stripe only
PAYMENT_PROVIDERS=stripe
# Both
PAYMENT_PROVIDERS=easypay,stripe
# Example: Alipay + WeChat Pay + Stripe (official channels)
PAYMENT_PROVIDERS=alipay,wxpay,stripe
```
**Step 2**: Control which channels are shown to users via `ENABLED_PAYMENT_TYPES`:
> **Alipay / WeChat Pay (official)** and **EasyPay** can coexist. Official channels connect directly to Alipay/WeChat Pay APIs with funds going straight to your merchant account and lower fees; EasyPay uses a third-party aggregation platform with a lower barrier to entry. When using EasyPay, choose providers where funds are routed through official Alipay/WeChat Pay channels rather than third-party collection.
```env
# EasyPay supports: alipay, wxpay | Stripe supports: stripe
ENABLED_PAYMENT_TYPES=alipay,wxpay
```
#### EasyPay (Alipay / WeChat Pay)
#### EasyPay (Alipay / WeChat Pay Aggregation)
Any payment provider compatible with the **EasyPay protocol** can be used, such as [ZPay](https://z-pay.cn/?uid=23808) (`https://z-pay.cn/?uid=23808`) (this link contains the author's referral code — feel free to remove it). ZPay supports **individual users** (no business license required) with a daily transaction limit of ¥10,000; users with a business license have no transaction limits.
@@ -127,7 +124,7 @@ Any payment provider compatible with the **EasyPay protocol** can be used, such
> **Disclaimer**: Please evaluate the security, reliability, and compliance of any third-party payment provider on your own. This project does not endorse or guarantee any specific provider.
>
> **⚠️ Security Warning**: When using third-party aggregated payment services, always choose providers where **funds are routed through official Alipay/WeChat Pay channels rather than third-party collection**, to avoid the risk of fund misappropriation.
> **⚠️ Security Warning**: When using third-party platforms, always choose providers where **funds are routed through official Alipay/WeChat Pay channels rather than third-party collection**, to avoid the risk of fund misappropriation.
| Variable | Description |
| --------------------- | ---------------------------------------------------------------- |
@@ -139,6 +136,33 @@ Any payment provider compatible with the **EasyPay protocol** can be used, such
| `EASY_PAY_CID_ALIPAY` | Alipay channel ID (optional) |
| `EASY_PAY_CID_WXPAY` | WeChat Pay channel ID (optional) |
#### Alipay (Official)
Direct integration with the Alipay Open Platform. Supports PC page payment (`alipay.trade.page.pay`) and mobile web payment (`alipay.trade.wap.pay`), automatically switching based on device type.
| Variable | Description |
| -------------------- | ---------------------------------------------- |
| `ALIPAY_APP_ID` | Alipay application AppID |
| `ALIPAY_PRIVATE_KEY` | Application private key (content or file path) |
| `ALIPAY_PUBLIC_KEY` | Alipay public key (content or file path) |
| `ALIPAY_NOTIFY_URL` | Async callback URL |
| `ALIPAY_RETURN_URL` | Sync redirect URL (optional) |
#### WeChat Pay (Official)
Direct integration with WeChat Pay APIv3. Supports Native QR code payment and H5 payment, with mobile devices preferring H5 and auto-fallback to QR code.
| Variable | Description |
| --------------------- | ----------------------------------------------- |
| `WXPAY_APP_ID` | WeChat Pay AppID |
| `WXPAY_MCH_ID` | Merchant ID |
| `WXPAY_PRIVATE_KEY` | Merchant API private key (content or file path) |
| `WXPAY_CERT_SERIAL` | Merchant certificate serial number |
| `WXPAY_API_V3_KEY` | APIv3 key |
| `WXPAY_PUBLIC_KEY` | WeChat Pay public key (content or file path) |
| `WXPAY_PUBLIC_KEY_ID` | WeChat Pay public key ID |
| `WXPAY_NOTIFY_URL` | Async callback URL |
#### Stripe
| Variable | Description |
@@ -153,10 +177,14 @@ Any payment provider compatible with the **EasyPay protocol** can be used, such
### Business Rules
| Variable | Description | Default |
| --------------------------- | ----------------------------------------------- | -------------------------- |
| -------------------------------- | ------------------------------------------------- | -------------------------- |
| `MIN_RECHARGE_AMOUNT` | Minimum amount per transaction (CNY) | `1` |
| `MAX_RECHARGE_AMOUNT` | Maximum amount per transaction (CNY) | `1000` |
| `MAX_DAILY_RECHARGE_AMOUNT` | Daily cumulative max per user (`0` = unlimited) | `10000` |
| `MAX_DAILY_AMOUNT_ALIPAY` | EasyPay Alipay channel daily global limit (opt.) | Provider default |
| `MAX_DAILY_AMOUNT_ALIPAY_DIRECT` | Alipay official channel daily global limit (opt.) | Provider default |
| `MAX_DAILY_AMOUNT_WXPAY` | WeChat Pay channel daily global limit (opt.) | Provider default |
| `MAX_DAILY_AMOUNT_STRIPE` | Stripe channel daily global limit (opt.) | Provider default |
| `ORDER_TIMEOUT_MINUTES` | Order expiry in minutes | `5` |
| `PRODUCT_NAME` | Product name shown on payment page | `Sub2API Balance Recharge` |
@@ -267,13 +295,16 @@ docker compose exec app npx prisma migrate deploy
## Sub2API Integration
The following page URLs can be configured in the Sub2API admin panel:
Assuming this service is deployed at `https://pay.example.com`.
| Page | URL | Description |
| ---------------- | ------------------------------------ | ------------------------------------- |
| Payment | `https://pay.example.com/pay` | User recharge entry |
| My Orders | `https://pay.example.com/pay/orders` | User views their own recharge history |
| Order Management | `https://pay.example.com/admin` | Sub2API admin only |
### User-Facing Pages
Configure the following URLs in the Sub2API admin panel under **Recharge Settings**, so users can navigate from Sub2API to the payment and order pages:
| Setting | URL | Description |
| --------- | ------------------------------------ | -------------------------------------------------- |
| Payment | `https://pay.example.com/pay` | User top-up & subscription purchase page |
| My Orders | `https://pay.example.com/pay/orders` | User views their own recharge/subscription history |
Sub2API **v0.1.88** and above will automatically append the following parameters — no manual query string needed:
@@ -282,50 +313,127 @@ Sub2API **v0.1.88** and above will automatically append the following parameters
| `user_id` | Sub2API user ID |
| `token` | User login token (required to view order history) |
| `theme` | `light` (default) or `dark` |
| `lang` | Interface language, `zh` (default) or `en` |
| `ui_mode` | `standalone` (default) or `embedded` (for iframe) |
### Admin Panel
The admin panel is authenticated via the `token` URL parameter (set to the `ADMIN_TOKEN` environment variable). When integrating with Sub2API, just configure the paths — **no query parameters needed** — Sub2API will automatically append `token` and other parameters:
| Page | URL | Description |
| ------------- | --------------------------------------------- | ------------------------------------------------------------- |
| Overview | `https://pay.example.com/admin` | Aggregated entry with card-style navigation |
| Orders | `https://pay.example.com/admin/orders` | Filter by status, paginate, view details, retry/cancel/refund |
| Dashboard | `https://pay.example.com/admin/dashboard` | Revenue stats, order trends, payment method breakdown |
| Channels | `https://pay.example.com/admin/channels` | Configure API channels & rates, sync from Sub2API |
| Subscriptions | `https://pay.example.com/admin/subscriptions` | Manage subscription plans & user subscriptions |
> **Tip**: When accessing directly (not via Sub2API), you need to manually append `?token=YOUR_ADMIN_TOKEN` to the URL. All admin pages share the same token — once you enter any page, you can navigate between modules via the sidebar.
---
## Admin Panel
Access: `https://pay.example.com/admin?token=YOUR_ADMIN_TOKEN`
| Feature | Description |
| -------------- | ----------------------------------------------------- |
| Order List | Filter by status, paginate, choose 20/50/100 per page |
| Order Detail | View all fields and audit log timeline |
| Retry Recharge | Re-trigger recharge for paid-but-failed orders |
| Cancel Order | Force-cancel pending orders |
| Refund | Issue refund and deduct Sub2API balance |
| Module | Path | Description |
| ------------- | ---------------------- | ------------------------------------------------------------- |
| Overview | `/admin` | Aggregated entry with card-style navigation |
| Orders | `/admin/orders` | Filter by status, paginate, view details, retry/cancel/refund |
| Dashboard | `/admin/dashboard` | Revenue stats, order trends, payment method breakdown |
| Channels | `/admin/channels` | Configure API channels & rates, sync from Sub2API |
| Subscriptions | `/admin/subscriptions` | Manage subscription plans & user subscriptions |
---
## Payment Flow
```
User submits recharge amount
User selects top-up / subscription plan
│
▼
Create Order (PENDING)
├─ Validate user status / pending order count / daily limit
├─ Validate user status / pending orders / daily limit / channel limit
└─ Call payment provider to get payment link
│
▼
User completes payment
├─ EasyPay → QR code / H5 redirect
├─ Alipay (official) → PC page payment / H5 mobile web payment
├─ WeChat Pay (official) → Native QR code / H5 payment
└─ Stripe → Payment Element (PaymentIntent)
│
▼
Payment callback (signature verified) → Order PAID
Payment callback (RSA2 / MD5 / Webhook signature verified) → Order PAID
│
▼
Auto-call Sub2API recharge API
├─ Success → COMPLETED, balance credited automatically
Auto-call Sub2API recharge / subscription API
├─ Success → COMPLETED, balance credited / subscription activated
└─ Failure → FAILED (admin can retry)
```
---
## API Endpoints
All API paths are prefixed with `/api`.
### Public API
User-facing endpoints, authenticated via `user_id` + `token` URL parameters.
| Method | Path | Description |
| ------ | ------------------------- | --------------------------------------------------- |
| `GET` | `/api/user` | Get current user info |
| `GET` | `/api/users/:id` | Get specific user info |
| `POST` | `/api/orders` | Create recharge / subscription order |
| `GET` | `/api/orders/:id` | Query order details |
| `POST` | `/api/orders/:id/cancel` | User cancels pending order |
| `GET` | `/api/orders/my` | List current user's orders |
| `GET` | `/api/channels` | Get channel list (for frontend display) |
| `GET` | `/api/subscription-plans` | Get available subscription plans |
| `GET` | `/api/subscriptions/my` | Query current user's subscriptions |
| `GET` | `/api/limits` | Query recharge limits & payment method availability |
### Payment Callbacks
Called asynchronously by payment providers; signature verified before triggering credit flow.
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------ |
| `GET` | `/api/easy-pay/notify` | EasyPay async callback |
| `POST` | `/api/alipay/notify` | Alipay (official) callback |
| `POST` | `/api/wxpay/notify` | WeChat Pay (official) callback |
| `POST` | `/api/stripe/webhook` | Stripe webhook callback |
### Admin API
Authenticated via `token` parameter set to `ADMIN_TOKEN`.
| Method | Path | Description |
| -------- | ----------------------------------- | ------------------------------------ |
| `GET` | `/api/admin/orders` | Order list (paginated, filterable) |
| `GET` | `/api/admin/orders/:id` | Order details (with audit log) |
| `POST` | `/api/admin/orders/:id/cancel` | Admin cancels order |
| `POST` | `/api/admin/orders/:id/retry` | Retry failed recharge / subscription |
| `POST` | `/api/admin/refund` | Issue refund |
| `GET` | `/api/admin/dashboard` | Dashboard (revenue stats, trends) |
| `GET` | `/api/admin/channels` | Channel list |
| `POST` | `/api/admin/channels` | Create channel |
| `PUT` | `/api/admin/channels/:id` | Update channel |
| `DELETE` | `/api/admin/channels/:id` | Delete channel |
| `GET` | `/api/admin/subscription-plans` | Subscription plan list |
| `POST` | `/api/admin/subscription-plans` | Create subscription plan |
| `PUT` | `/api/admin/subscription-plans/:id` | Update subscription plan |
| `DELETE` | `/api/admin/subscription-plans/:id` | Delete subscription plan |
| `GET` | `/api/admin/subscriptions` | User subscription records |
| `GET` | `/api/admin/config` | Get system configuration |
| `PUT` | `/api/admin/config` | Update system configuration |
| `GET` | `/api/admin/sub2api/groups` | Sync channel groups from Sub2API |
| `GET` | `/api/admin/sub2api/search-users` | Search Sub2API users |
---
## Development
### Requirements

111
README.md
View File

@@ -2,7 +2,7 @@
**语言 / Language**: 中文（当前）｜ [English](./README.en.md)
Sub2ApiPay 是为 [Sub2API](https://sub2api.com) 平台构建的自托管支付网关。支持**支付宝直连**、**微信支付直连**、EasyPay 易支付聚合和 Stripe 四种支付渠道，提供按量充值与套餐订阅两种计费模式，支付成功后自动调用 Sub2API 管理接口完成到账，无需人工干预。
Sub2ApiPay 是为 [Sub2API](https://sub2api.com) 平台构建的自托管支付网关。支持 **EasyPay 易支付聚合**、**支付宝官方**、**微信官方**和 **Stripe** 四种支付渠道，提供按量充值与套餐订阅两种计费模式，支付成功后自动调用 Sub2API 管理接口完成到账，无需人工干预。
---
@@ -23,7 +23,7 @@ Sub2ApiPay 是为 [Sub2API](https://sub2api.com) 平台构建的自托管支付
## 功能特性
- **四渠道支付** — 支付宝官方直连、微信支付官方直连、EasyPay 易支付聚合、Stripe 国际信用卡
- **四渠道支付** — EasyPay 易支付聚合、支付宝官方、微信官方、Stripe
- **双计费模式** — 按量余额充值 + 套餐订阅，灵活适配不同业务场景
- **自动到账** — 支付回调验签后自动调用 Sub2API 充值 / 订阅接口，全程无需人工
- **订单全生命周期** — 超时自动取消、用户主动取消、管理员取消、退款
@@ -103,40 +103,13 @@ docker compose up -d --build
```env
# 可选值: easypay, alipay, wxpay, stripe
# 示例：同时启用支付宝直连 + 微信直连 + Stripe
PAYMENT_PROVIDERS=alipay,wxpay,stripe
# 示例：仅使用易支付聚合
# 示例：仅使用 EasyPay 易支付聚合
PAYMENT_PROVIDERS=easypay
# 示例：同时启用支付宝官方 + 微信官方 + Stripe
PAYMENT_PROVIDERS=alipay,wxpay,stripe
```
> **支付宝直连 / 微信支付直连**与**EasyPay**可以共存。直连渠道直接对接官方 API，资金直达商户账户，手续费更低；EasyPay 通过第三方聚合平台代收，接入门槛更低。使用 EasyPay 时请尽量选择资金直接走支付宝/微信官方渠道，而非第三方代收的、不经过第三方中转的服务商。
#### 支付宝直连
直接对接支付宝开放平台，支持 PC 页面支付（`alipay.trade.page.pay`）和手机网站支付（`alipay.trade.wap.pay`），自动根据终端类型切换。
| 变量 | 说明 |
| -------------------- | ---------------------------- |
| `ALIPAY_APP_ID` | 支付宝应用 AppID |
| `ALIPAY_PRIVATE_KEY` | 应用私钥（内容或文件路径） |
| `ALIPAY_PUBLIC_KEY` | 支付宝公钥（内容或文件路径） |
| `ALIPAY_NOTIFY_URL` | 异步回调地址 |
| `ALIPAY_RETURN_URL` | 同步跳转地址（可选） |
#### 微信支付直连
直接对接微信支付 APIv3，支持 Native 扫码支付和 H5 支付，移动端优先尝试 H5，自动 fallback 到扫码。
| 变量 | 说明 |
| --------------------- | ------------------------------- |
| `WXPAY_APP_ID` | 微信支付 AppID |
| `WXPAY_MCH_ID` | 商户号 |
| `WXPAY_PRIVATE_KEY` | 商户 API 私钥（内容或文件路径） |
| `WXPAY_CERT_SERIAL` | 商户证书序列号 |
| `WXPAY_API_V3_KEY` | APIv3 密钥 |
| `WXPAY_PUBLIC_KEY` | 微信支付公钥（内容或文件路径） |
| `WXPAY_PUBLIC_KEY_ID` | 微信支付公钥 ID |
| `WXPAY_NOTIFY_URL` | 异步回调地址 |
> **支付宝官方 / 微信官方**与 **EasyPay** 可以共存。官方渠道直接对接支付宝/微信 API，资金直达商户账户，手续费更低；EasyPay 通过第三方聚合平台代收，接入门槛更低。使用 EasyPay 时请尽量选择资金直接走支付宝/微信官方渠道，而非第三方代收的、不经过第三方中转的服务商。
#### EasyPay（支付宝 / 微信支付聚合）
@@ -151,7 +124,7 @@ PAYMENT_PROVIDERS=easypay
> **注意**：支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。
>
> **⚠️ 安全提示**：使用第三方聚合支付时，请尽量选择**资金直接走支付宝/微信官方渠道，而非第三方代收**的服务商，避免资金被卷款跑路。
> **⚠️ 安全提示**：使用第三方平台时，请尽量选择**资金直接走支付宝/微信官方渠道，而非第三方代收**的服务商，避免资金被卷款跑路。
| 变量 | 说明 |
| --------------------- | ------------------------------------------------------------- |
@@ -163,6 +136,33 @@ PAYMENT_PROVIDERS=easypay
| `EASY_PAY_CID_ALIPAY` | 支付宝通道 ID（可选） |
| `EASY_PAY_CID_WXPAY` | 微信支付通道 ID（可选） |
#### 支付宝官方
直接对接支付宝开放平台，支持 PC 页面支付（`alipay.trade.page.pay`）和手机网站支付（`alipay.trade.wap.pay`），自动根据终端类型切换。
| 变量 | 说明 |
| -------------------- | ---------------------------- |
| `ALIPAY_APP_ID` | 支付宝应用 AppID |
| `ALIPAY_PRIVATE_KEY` | 应用私钥（内容或文件路径） |
| `ALIPAY_PUBLIC_KEY` | 支付宝公钥（内容或文件路径） |
| `ALIPAY_NOTIFY_URL` | 异步回调地址 |
| `ALIPAY_RETURN_URL` | 同步跳转地址（可选） |
#### 微信官方
直接对接微信支付 APIv3，支持 Native 扫码支付和 H5 支付，移动端优先尝试 H5，自动 fallback 到扫码。
| 变量 | 说明 |
| --------------------- | ------------------------------- |
| `WXPAY_APP_ID` | 微信支付 AppID |
| `WXPAY_MCH_ID` | 商户号 |
| `WXPAY_PRIVATE_KEY` | 商户 API 私钥（内容或文件路径） |
| `WXPAY_CERT_SERIAL` | 商户证书序列号 |
| `WXPAY_API_V3_KEY` | APIv3 密钥 |
| `WXPAY_PUBLIC_KEY` | 微信支付公钥（内容或文件路径） |
| `WXPAY_PUBLIC_KEY_ID` | 微信支付公钥 ID |
| `WXPAY_NOTIFY_URL` | 异步回调地址 |
#### Stripe
| 变量 | 说明 |
@@ -182,7 +182,7 @@ PAYMENT_PROVIDERS=easypay
| `MAX_RECHARGE_AMOUNT` | 单笔最高充值金额（元） | `1000` |
| `MAX_DAILY_RECHARGE_AMOUNT` | 每日每用户累计最高充值（元，`0` = 不限） | `10000` |
| `MAX_DAILY_AMOUNT_ALIPAY` | 易支付支付宝渠道每日全局限额（可选） | 由提供商默认 |
| `MAX_DAILY_AMOUNT_ALIPAY_DIRECT` | 支付宝直连渠道每日全局限额（可选） | 由提供商默认 |
| `MAX_DAILY_AMOUNT_ALIPAY_DIRECT` | 支付宝官方渠道每日全局限额（可选） | 由提供商默认 |
| `MAX_DAILY_AMOUNT_WXPAY` | 微信支付渠道每日全局限额（可选） | 由提供商默认 |
| `MAX_DAILY_AMOUNT_STRIPE` | Stripe 渠道每日全局限额（可选） | 由提供商默认 |
| `ORDER_TIMEOUT_MINUTES` | 订单超时分钟数 | `5` |
@@ -295,13 +295,16 @@ docker compose exec app npx prisma migrate deploy
## 集成到 Sub2API
在 Sub2API 管理后台可配置以下页面链接：
假设本服务部署在 `https://pay.example.com`。
| 页面 | 链接 | 说明 |
| -------- | ------------------------------------ | ------------------------ |
| 充值页面 | `https://pay.example.com/pay` | 用户充值入口 |
| 我的订单 | `https://pay.example.com/pay/orders` | 用户查看自己的充值记录 |
| 管理后台 | `https://pay.example.com/admin` | 管理后台入口（仅管理员） |
### 用户端页面
在 Sub2API 管理后台的**充值设置**中配置以下链接，用户即可从 Sub2API 平台跳转到充值和订单页面：
| 配置项 | URL | 说明 |
| -------- | ------------------------------------ | --------------------------- |
| 充值页面 | `https://pay.example.com/pay` | 用户充值、购买订阅套餐入口 |
| 我的订单 | `https://pay.example.com/pay/orders` | 用户查看自己的充值/订阅记录 |
Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添加：
@@ -313,6 +316,20 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添
| `lang` | 界面语言，`zh`（默认）或 `en` |
| `ui_mode` | `standalone`（默认）或 `embedded`（iframe 嵌入） |
### 管理后台
管理后台通过 URL 参数 `token` 鉴权（值为环境变量 `ADMIN_TOKEN`）。在 Sub2API 中集成时只需配置路径，**无需附加任何查询参数**——Sub2API 会自动拼接 `token` 等参数：
| 页面 | URL | 说明 |
| -------- | --------------------------------------------- | ---------------------------------------------- |
| 管理总览 | `https://pay.example.com/admin` | 聚合入口，卡片式导航到各管理模块 |
| 订单管理 | `https://pay.example.com/admin/orders` | 按状态筛选、分页浏览、订单详情、重试/取消/退款 |
| 数据概览 | `https://pay.example.com/admin/dashboard` | 收入统计、订单趋势、支付方式分布 |
| 渠道管理 | `https://pay.example.com/admin/channels` | 配置 API 渠道与倍率，支持从 Sub2API 同步 |
| 订阅管理 | `https://pay.example.com/admin/subscriptions` | 管理订阅套餐与用户订阅 |
> **提示**：若独立访问（不通过 Sub2API 跳转），需手动在 URL 后添加 `?token=YOUR_ADMIN_TOKEN`。管理后台所有页面间共享同一个 token，进入任一页面后可通过侧边导航切换。
---
## 管理后台
@@ -341,9 +358,9 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添
│
▼
用户完成支付
├─ 支付宝直连 → PC 页面支付 / H5 手机网站支付
├─ 微信直连 → Native 扫码 / H5 支付
├─ EasyPay → 扫码 / H5 跳转
├─ 支付宝官方 → PC 页面支付 / H5 手机网站支付
├─ 微信官方 → Native 扫码 / H5 支付
└─ Stripe → Payment Element (PaymentIntent)
│
▼
@@ -383,10 +400,10 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添
由支付服务商异步调用，签名验证后触发到账流程。
| 方法 | 路径 | 说明 |
| ------ | ---------------------- | ---------------------------- |
| `GET` | `/api/easy-pay/notify` | EasyPay 异步回调（GET 方式） |
| `POST` | `/api/alipay/notify` | 支付宝直连异步回调 |
| `POST` | `/api/wxpay/notify` | 微信支付直连异步回调 |
| ------ | ---------------------- | ----------------------- |
| `GET` | `/api/easy-pay/notify` | EasyPay 异步回调（GET） |
| `POST` | `/api/alipay/notify` | 支付宝官方异步回调 |
| `POST` | `/api/wxpay/notify` | 微信官方异步回调 |
| `POST` | `/api/stripe/webhook` | Stripe Webhook 回调 |
### 管理 API