oadmin/sub2api
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
9d1751ec57957547b0eb5d3bdf758c2ec82a3e37
sub2api/docs/PAYMENT_CN.md
IanShaw027 f35e967516 fix payment qr fallback and admin guidance
2026-04-22 07:33:14 -07:00

12 KiB
Raw Blame History

支付系统配置指南

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

目录

支持的支付方式

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

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

易支付服务商推荐：以下两家均为兼容易支付协议的第三方聚合支付，按资金通道与结算方式选择：

  • 国内渠道 / 人民币结算 — ZPay（https://z-pay.cn/?uid=23808）：支付宝 / 微信官方 API 直连，手续费 1.6%；资金直达商家账户，T+1 自动到账。支持个人用户（无营业执照）每日 1 万元以内交易；拥有营业执照则无限额。链接含 Sub2ApiPay 原作者 @touwaeriol 的邀请码，介意可去掉。
  • 国际渠道 / USDT 或美元结算 — 启润支付（https://kyren.top/?code=SUB2API）：为 AI 项目提供低门槛国际收款通道，支持国际版微信支付与支付宝，本地货币支付、美元结算。手续费：微信 2%、支付宝 2.5%；提现 0.1%（最低 40 美元、最高 150 美元），以 USDT 或美元到账。无资质审核、注册即用，使用门槛最低；提现门槛略高，适合不使用国内支付渠道、无法接受 Stripe 高达 6%+ 手续费、流水较大，且拥有美元或 USDT 渠道可接收提现资金的用户。启润支付开户费 200 美元，通过本链接注册（含 Sub2Api 作者 @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
  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 作为外部支付系统，现在可以迁移到内置支付：

主要差异

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

迁移步骤

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

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