返回
支付 Stripe 订阅系统

Stripe 订阅核心概念与流程详解

基于 Stripe 官方文档，详细讲解订阅集成的核心概念、完整业务流程和关键要点，包括订阅生命周期、Webhook 处理、状态管理等核心内容。

Stripe 订阅核心概念与流程详解

基于 Stripe 官方文档，详细讲解订阅集成的核心概念、完整业务流程和关键要点。

一、订阅集成的核心概念

1.1 订阅的本质

订阅（Subscription）是一种周期性支付模式，与一次性支付的关键区别在于：

  • 一次性支付：客户支付一次，获得产品访问权限，无需存储客户信息
  • 订阅支付：客户需要周期性支付（如每月、每年），必须存储客户信息和支付方式，以便自动扣款

1.2 订阅的核心组件

Product（产品）

  • 代表你销售的商品或服务
  • 可以是一个服务层级（如基础版、专业版）
  • 一个产品可以有多个价格（Price）

Price（价格）

  • 定义产品的定价规则
  • 可以是固定价格（Flat Rate）或基于使用量（Usage-Based）
  • 包含计费周期（每月、每年等）
  • 每个价格有唯一 ID（如 price_G0FvDp6vZvdwRZ）

Customer（客户）

  • 存储客户的基本信息和支付方式
  • 一个客户可以有多个订阅
  • 支付方式可以复用，无需每次重新输入

Subscription（订阅）

  • 将客户与产品/价格关联起来
  • 管理订阅的生命周期（创建、更新、取消）
  • 自动生成发票和扣款

Invoice（发票）

  • 记录每个计费周期的账单
  • 订阅创建时自动生成第一张发票
  • 每个计费周期结束时自动生成新发票
  • 状态包括：open（待支付）、paid（已支付）、void（已作废）、draft（草稿）

Checkout Session（结账会话）

  • 用于收集客户支付信息的会话
  • 支持多种支付方式（信用卡、借记卡、数字钱包等）
  • 支付完成后返回客户到你的网站

Customer Portal（客户门户）

  • 让客户自主管理订阅的界面
  • 可以更新支付方式、查看发票、取消订阅等
  • 由 Stripe 托管，无需自己开发

1.3 订阅的生命周期状态

订阅从创建到结束会经历多个状态：

  1. trialing（试用中）：客户处于免费试用期，尚未扣款
  2. incomplete（未完成）：订阅已创建，但首次支付尚未完成
  3. active（活跃）：订阅正常，定期自动扣款
  4. past_due（逾期）：最新发票支付失败，但订阅仍在尝试收款
  5. canceled（已取消）：订阅已取消，不再生成新发票
  6. unpaid（未支付）：最新发票未支付，已停止自动收款尝试
  7. paused（已暂停）：试用结束但无支付方式，暂停生成发票

二、订阅集成的完整流程

阶段 1：准备阶段 - 创建产品目录

目标：在 Stripe 中建立你的产品定价体系

步骤：

  1. 创建产品（Product）

    • 定义产品名称和描述
    • 例如：基础版服务、专业版服务

  2. 为每个产品创建价格（Price）

    • 设置价格金额和计费周期（每月/每年）
    • 例如：基础版 $5/月，专业版 $15/月
    • 记录价格 ID，后续会用到

  3. 配置支付方式

    • 在 Dashboard 中启用你希望接受的支付方式
    • 支持信用卡、借记卡、数字钱包等多种方式

关键点：

  • 价格 ID 是后续创建订阅的关键标识
  • 如果提供多种计费周期（月付/年付），需要为每个周期创建独立的价格

阶段 2：客户订阅 - 创建 Checkout Session

目标：让客户选择订阅计划并完成支付

流程：

  1. 前端展示订阅选项

    • 在网站上展示不同的订阅计划
    • 客户点击"订阅"按钮

  2. 后端创建 Checkout Session

    • 接收前端传递的价格 ID
    • 创建 Checkout Session，包含：
      • 价格 ID（客户选择的订阅计划）
      • 成功回调 URL（支付完成后返回的页面）
      • 取消回调 URL（客户取消支付时返回的页面）
      • 订阅模式（mode: 'subscription'）

  3. 重定向到 Stripe 支付页面

    • 返回 Checkout Session 的 URL
    • 前端重定向客户到 Stripe 托管的支付页面

  4. 客户完成支付

    • 在 Stripe 页面输入支付信息
    • 完成支付验证（如 3D Secure）
    • Stripe 处理支付并创建订阅

关键点：

  • Checkout Session 是一次性的，支付完成后即失效
  • 成功回调 URL 可以包含会话 ID，用于查询订阅详情
  • 支持灵活计费模式（Flexible Billing Mode），提供更准确的订阅行为

阶段 3：订阅激活 - 处理 Webhook 事件

目标：监听 Stripe 事件，激活订阅并授予产品访问权限

关键事件：

checkout.session.completed

  • 触发时机：客户成功完成 Checkout Session 支付
  • 含义：订阅已创建，首次支付成功
  • 处理逻辑：
    • 从事件中获取 customer.id 和 subscription.id
    • 将客户和订阅信息保存到数据库
    • 授予客户产品访问权限（Provision）
    • 可以使用 Entitlements API 管理功能访问

invoice.paid

  • 触发时机：每个计费周期支付成功时
  • 含义：订阅继续有效，客户已支付本期费用
  • 处理逻辑：
    • 确认订阅状态为 active
    • 继续提供产品访问权限
    • 记录支付成功日志

invoice.payment_failed

  • 触发时机：支付失败或客户支付方式无效
  • 含义：订阅可能进入 past_due 状态
  • 处理逻辑：
    • 通知客户支付失败
    • 引导客户到客户门户更新支付方式
    • 根据业务规则决定是否限制产品访问

Webhook 处理要点：

  • 必须验证 Webhook 签名，确保事件来自 Stripe
  • 使用事件 ID 实现幂等性，避免重复处理
  • 快速响应（200 状态码），避免 Stripe 重试
  • 异步处理业务逻辑，不要阻塞 Webhook 响应

阶段 4：订阅管理 - 客户门户集成

目标：让客户自主管理订阅，减少客服压力

流程：

  1. 配置客户门户

    • 在 Dashboard 中配置客户门户功能
    • 设置允许的操作：更新支付方式、取消订阅、查看发票等
    • 配置默认重定向链接

  2. 创建门户会话

    • 后端提供接口创建客户门户会话
    • 传入客户 ID（从之前保存的订阅信息中获取）
    • 设置返回 URL（客户完成管理后返回的页面）

  3. 前端跳转

    • 在网站中添加"管理订阅"按钮
    • 点击后调用后端接口创建门户会话
    • 重定向客户到 Stripe 客户门户

  4. 客户操作

    • 客户可以在门户中：
      • 更新支付方式
      • 查看历史发票
      • 取消订阅
      • 修改订阅计划

  5. 监听变更事件

    • 继续监听 Webhook 事件，同步订阅状态变更
    • 例如：customer.subscription.updated（订阅计划变更）
    • 例如：customer.subscription.deleted（订阅取消）

关键点：

  • 客户门户由 Stripe 托管，无需自己开发 UI
  • 门户操作会触发相应的 Webhook 事件
  • 必须监听这些事件来同步本地数据库状态

三、订阅流程的关键时间点

3.1 首次支付窗口（23 小时）

  • 含义：订阅创建后，客户有约 23 小时完成首次支付
  • 状态：在此期间，订阅状态为 incomplete
  • 超时处理：23 小时内未支付，订阅变为 incomplete_expired，不会自动扣款
  • 业务影响：需要引导客户尽快完成支付，或提供重新支付机制

3.2 计费周期锚点（Billing Cycle Anchor）

  • 含义：定义每个计费周期的开始和结束时间
  • 默认行为：订阅创建时自动设置，后续周期按此时间点重复
  • 自定义：可以在创建订阅时设置特定日期作为计费周期起点
  • 业务影响：影响发票生成时间和金额计算

3.3 试用期（Trial Period）

  • 设置方式：创建订阅时设置 trial_period_days

  • 行为：

    • 试用期内不扣款，但需要收集支付方式
    • 试用期结束前会通知客户（customer.subscription.trial_will_end 事件）
    • 试用期结束时自动生成发票并扣款

  • 业务影响：降低客户试用门槛，提高转化率

3.4 支付重试（Smart Retries）

  • 机制：Stripe 自动重试失败的支付
  • 策略：使用智能重试算法，在合适的时间点重试
  • 自定义：可以配置重试规则和次数
  • 业务影响：提高支付成功率，减少因临时问题导致的订阅中断

四、订阅集成的关键设计决策

4.1 定价模型选择

根据业务需求选择合适的定价模型：

  • 固定费率（Flat Rate）：简单透明，适合标准 SaaS 产品
  • 按席位（Per-Seat）：根据用户数量收费，适合团队协作工具
  • 分层定价（Tiered）：根据使用量分层收费，适合 API 服务
  • 基于使用量（Usage-Based）：完全按实际使用收费，适合云服务

4.2 结账界面选择

根据技术能力和用户体验需求选择：

  • Stripe 托管页面：最简单，快速上线，适合 MVP
  • 嵌入式表单：保持品牌一致性，客户不离开网站
  • 自定义表单：完全控制 UI，需要更多开发工作
  • 定价表：展示多个订阅选项，适合多层级产品
  • 支付链接：通过链接分享，适合邮件营销场景

4.3 计费时机选择

  • 预付（Pay Up Front）：订阅创建时立即扣款，标准模式
  • 免费试用（Free Trial）：试用期结束后扣款，需要收集支付方式
  • 免费增值（Freemium）：允许客户先使用，后续再收集支付方式

4.4 支付行为配置

创建订阅时的支付行为设置：

  • default_incomplete：推荐使用，创建时状态为 incomplete，便于处理 3D Secure 等需要客户交互的场景
  • allow_incomplete：立即尝试收款，失败则变为 incomplete
  • error_if_incomplete：支付失败则创建失败，不推荐使用

五、订阅集成的关键注意事项

5.1 幂等性保证

  • 问题：Webhook 可能重复发送，网络问题可能导致重复请求

  • 解决：

    • 使用 Stripe 事件 ID 作为幂等键
    • 在处理事件前检查是否已处理过
    • 已处理的事件直接返回成功，不重复执行

5.2 状态同步

  • 问题：本地数据库状态可能与 Stripe 不一致

  • 解决：

    • 以 Stripe 状态为准，通过 Webhook 同步
    • 定期同步关键订阅状态（如每日同步）
    • 提供手动同步机制，处理异常情况

5.3 错误处理

  • 支付失败：监听 invoice.payment_failed，引导客户更新支付方式
  • 网络超时：实现重试机制，确保 Webhook 最终处理成功
  • 业务错误：区分可重试错误和不可重试错误，采用不同处理策略

5.4 金额处理

  • 单位：Stripe 金额单位为最小货币单位（如分为单位）
  • 存储：数据库中使用整数存储金额（分）
  • 显示：前端显示时转换为小数（元）
  • 计算：避免使用浮点数，使用整数或 decimal 类型

5.5 授权管理

  • 时机：订阅状态为 trialing 或 active 时授予访问权限
  • 方式：使用 Entitlements API 或根据订阅状态控制功能访问
  • 降级：past_due 状态可以降级访问或限制功能
  • 撤销：canceled 或 unpaid 状态需要撤销访问权限

5.6 测试策略

  • 测试卡号：使用 Stripe 提供的测试卡号模拟不同场景

    • 成功支付：4242 4242 4242 4242
    • 需要认证：4000 0025 0000 3155
    • 支付失败：4000 0000 0000 9995

  • Webhook 测试：使用 Stripe CLI 本地测试 Webhook

  • 事件监控：在 Dashboard 的 Events 标签页监控事件

六、订阅集成的扩展功能

6.1 免费试用

  • 在创建订阅时设置 trial_period_days
  • 监听 customer.subscription.trial_will_end 事件，提前提醒客户
  • 试用期结束自动扣款，无需额外处理

6.2 折扣和优惠券

  • 创建优惠券（Coupon）并应用到订阅
  • 支持固定金额折扣或百分比折扣
  • 可以设置使用次数限制和过期时间

6.3 订阅修改

  • 支持升级/降级订阅计划
  • 支持修改订阅数量（Per-Seat 场景）
  • 监听 customer.subscription.updated 事件同步变更

6.4 多产品订阅

  • 一个订阅可以包含多个产品
  • 每个产品独立计费周期
  • 适合提供多种服务的场景

6.5 基于使用量的计费

  • 定期上报使用量（SubscriptionItem.createUsageRecord）
  • Stripe 根据使用量自动计算账单金额
  • 监听 invoice.created 事件获取账单详情

七、订阅集成的最佳实践

7.1 事件监听优先级

必须监听的事件：

  • checkout.session.completed：订阅创建和首次支付
  • invoice.paid：每个计费周期支付成功
  • invoice.payment_failed：支付失败处理

建议监听的事件：

  • customer.subscription.updated：订阅计划变更
  • customer.subscription.deleted：订阅取消
  • customer.subscription.trial_will_end：试用期即将结束

7.2 客户体验优化

  • 快速响应：Webhook 处理要快速，避免延迟授权
  • 清晰提示：支付失败时提供明确的错误信息和解决方案
  • 便捷管理：提供客户门户入口，让客户自主管理订阅
  • 及时通知：支付成功、失败、试用期结束等关键节点及时通知客户

7.3 数据安全

  • Webhook 签名验证：必须验证所有 Webhook 请求的签名
  • 敏感信息保护：不在日志中记录完整的支付信息
  • 最小权限原则：API 密钥权限最小化，只授予必要的权限

7.4 监控和告警

  • 关键指标：订阅创建率、支付成功率、订阅取消率
  • 异常告警：支付失败率突增、Webhook 处理失败等
  • 性能监控：Webhook 处理时间、API 调用延迟

7.5 业务连续性

  • 降级策略：Stripe 服务不可用时的降级方案
  • 数据备份：定期备份订阅和客户数据
  • 恢复机制：提供手动同步和修复机制

八、总结

Stripe 订阅集成是一个完整的业务流程，涉及产品定价、客户订阅、支付处理、状态管理和客户服务等多个环节。核心要点包括：

  1. 明确业务需求：选择合适的定价模型、结账界面和计费时机
  2. 正确实现流程：创建产品、处理订阅、监听事件、管理状态
  3. 保证数据一致性：通过 Webhook 同步状态，实现幂等性
  4. 优化用户体验：快速响应、清晰提示、便捷管理
  5. 确保系统稳定：错误处理、监控告警、降级策略

通过遵循这些核心概念和最佳实践，可以构建一个稳定、可靠的订阅支付系统。