支付系统配置指南

July 22, 2026 · View on GitHub

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://merchant.kyrenpay.com/?code=SUB2API）：为 AI 项目提供低门槛国际收款通道，支持国际版微信支付与支付宝，本地货币支付、美元结算。微信 2.5%、支付宝 2.5%；多种提现方式，海外公司账户提现手续费 20 美金，USDT 提现手续费 30 美金 + 0.4% 流水，以 USDT 或美元 到账。无资质审核、注册即用，使用门槛最低；提现门槛略高，适合不使用国内支付渠道、无法接受 Stripe 高达 6%+ 手续费、流水较大，且拥有美元或 USDT 渠道可接收提现资金的用户。启润支付开户费 200 美元，通过本链接注册（含 Sub2Api 作者 @Wei-Shaw 邀请码）可免开户费，介意可去掉。

支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。

快速开始

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

系统设置

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

基本设置

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

支付宝移动端当面付唤起

支付宝移动端当面付唤起 默认关闭，仅对前台路由到 支付宝官方 的移动端订单生效。开启后，服务端调用 alipay.trade.precreate 获取动态二维码，前端立即使用支付宝 Scheme 尝试唤起 App；页面未进入后台时会自动展示动态二维码备用页，继续轮询订单状态。桌面端仍保持“当面付二维码优先，电脑网站支付回退”的既有行为。

  • 需要为该支付宝应用开通 当面付 / 扫码支付；未开通时保持关闭。
  • 管理后台开关保存为 ALIPAY_MOBILE_PRECREATE_DEEP_LINK；部署环境变量 ALIPAY_MOBILE_PRECREATE_DEEP_LINK=true 可强制开启，未设置时使用后台值。
  • 与“支付宝强制二维码支付”同时开启时，当面付唤起优先。关闭本开关即可恢复移动端手机网站支付。

前台可见支付方式路由

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

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

负载均衡策略

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

取消频率限制

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

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

帮助信息

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

服务商配置

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

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

EasyPay（易支付）

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

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

支付宝官方

直接对接支付宝开放平台。移动端默认走支付宝手机网站支付跳转；开启“支付宝移动端当面付唤起”后改为调用当面付，前端尝试打开支付宝 App，失败时显示动态二维码备用页。桌面端优先使用当面付返回扫码串，若商户未开通当面付则回退到电脑网站支付，并将收银台链接同时返回给前端用于渲染二维码或直接打开支付页。

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

微信官方

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

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

Stripe

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

参数说明必填
Secret KeyStripe 密钥（sk_live_... 或 sk_test_...）是
Publishable KeyStripe 可公开密钥（pk_live_... 或 pk_test_...）是
Webhook SecretStripe Webhook 签名密钥（whsec_...）是

服务商实例管理

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

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

实例限额配置

每个实例支持以下限额：

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

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

Webhook 配置

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

回调地址格式

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

服务商回调路径
EasyPayhttps://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
Stripehttps://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 跳转
  ├─ 支付宝官方  → 桌面扫码单（当面付优先，电脑网站支付回退）/ 移动端 WAP 或当面付唤起 + 动态二维码备用页
  ├─ 微信官方    → 桌面 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 一段时间以便查询历史记录。