支付系统文档索引

NEXTY.DEV 的支付系统同时支持 Stripe、Creem、PayPal 三家渠道，覆盖订阅、一次性购买、积分账本、团队共享池、退款与对账。

本章按「由面到点」组织：先看懂整体，再深入各个模块。

文档结构

1. 支付系统概述

   • 一条链路看懂全貌
   • 五条设计原则
   • 数据库表与代码地图
   • 个人与团队两种计费主体
   • 三家渠道的能力差异

2. 定价配置

   • 为什么定价写在代码里
   • 订阅 / 积分包 / 团队套餐怎么写
   • 字段参考与渠道侧引用
   • 三语文案、促销码、上下架铁律

3. 支付流程

   • 从点击到积分到账的完整链路
   • 结账守卫的顺序与理由
   • 成功页与 webhook 的双保险
   • 拦截码速查

4. Webhook 处理

   • 三层结构与签名校验
   • 三家渠道的事件映射
   • 幂等性、状态归一化、错误处理
   • 重复订阅结算与丢失 webhook 的补救

5. 积分系统

   • 双桶模型与只追加账本
   • 年付订阅的月度定投
   • 把业务功能接进积分系统
   • 团队共享池、注册赠送、管理员操作

6. 订单与订阅管理

   • 订单数据结构与查询
   • 退款：为什么只调 API 不写本地状态
   • 自助门户与优惠券控制台
   • 用户端与管理端页面一览

7. 优惠券控制台

   • Stripe Coupon + Promotion Code 数据模型
   • 码创建后不可改，以及由此塑造的 UI
   • 创建表单、适用范围的翻译路径
   • 自动应用与列表扫描上限

8. 订阅变更

   • 配置 Stripe 变更入口
   • 周期内变更的积分差额算法
   • 防刷设计与跨周期重锚

快速开始

第一次接入

1. 读支付系统概述，建立整体认知
2. 按 Stripe 集成（或 PayPal 集成）在渠道侧建好产品
3. 按定价配置编辑 config/pricing.ts，或直接跑 pnpm stripe:bootstrap --write
4. 配好 webhook 地址和 CRON_SECRET（见定时任务）
5. 用测试卡跑通一笔，按支付流程末尾的清单验证

按需求查找

环境变量

完整清单见环境变量。支付相关的部分：

Stripe

STRIPE_SECRET_KEY=sk_...
STRIPE_PUBLISHABLE_KEY=pk_...
STRIPE_WEBHOOK_SECRET=whsec_...
# 可选：refund,email | refund | email | 留空
STRIPE_RADAR_EARLY_FRAUD_WARNING_TYPE=refund,email

Creem

CREEM_API_KEY=your_api_key
CREEM_WEBHOOK_SECRET=your_webhook_secret
CREEM_API_BASE_URL=https://api.creem.io/v1  # 可选

PayPal

NEXT_PUBLIC_ENABLE_PAYPAL=true
NEXT_PUBLIC_PAYPAL_CLIENT_ID=your_client_id
NEXT_PUBLIC_PAYPAL_ENVIRONMENT=sandbox  # sandbox | live
PAYPAL_CLIENT_SECRET=your_client_secret
PAYPAL_WEBHOOK_ID=your_webhook_id

定时任务

# /api/cron/credits 的鉴权密钥。启用订阅或积分功能时必须配置
CRON_SECRET=your_cron_secret

其他

NEXT_PUBLIC_DEFAULT_CURRENCY=USD
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
[email protected]

常见问题

Q: 支持哪些支付渠道？

Stripe、Creem、PayPal 三家。每个套餐由 config/pricing.ts 里的 provider 字段决定走哪家，三家可以同时启用。

Q: 怎么改定价？后台在哪？

v4.0.0 起没有后台定价管理页面了。定价写在 config/pricing.ts，改完部署即可。见定价配置。

Q: 定时任务是必须的吗？

只要卖订阅或用积分，就是必须的。年付套餐的月度定投、丢失 webhook 的对账、PayPal 挂起捕获的推进都靠它。见定时任务。

Q: 积分系统怎么工作？

两个桶：订阅积分（每次发放重置、订阅结束清零）和购买积分（永不过期），消费优先扣订阅桶。所有变动经账本，只追加不修改。见积分系统。

Q: 用户能自己管理订阅吗？

能。/dashboard/billing 的「管理订阅」按钮会按订阅的渠道跳转到对应的自助门户。PayPal 没有托管门户，跳转到 PayPal 的自动付款页。

Q: 怎么测试？

三家都用测试/沙盒模式，本地转发 webhook。详见支付流程的测试一节。