跳到主要内容

订阅系统概述

EFundFlow 订阅系统允许您为客户创建和管理定期付款。订阅系统支持灵活的计费周期、自动重试失败的付款，以及全面的订阅生命周期管理。

核心概念​

Token（支付令牌）​

支付令牌是安全存储客户支付信息的方式，包含客户信息和支付方式详情。Token用于简化订阅创建流程，确保支付信息的安全性。

Customer（客户）​

客户是订阅系统的核心实体，包含客户的基本信息和账单详情。每个客户可以拥有多个订阅和支付方式。

Plan（计划）​

计划定义了订阅的价格、计费周期和其他配置。计划可以被多个订阅使用，便于统一管理定价策略。

Payment Method（支付方式）​

支付方式是客户用于支付订阅费用的方法，如信用卡、银行账户等。支付方式与客户关联并可重复使用。

Subscription（订阅）​

订阅将客户、计划和支付方式关联起来，定义了定期付款的具体实例。每个订阅都有独立的生命周期管理。

订阅状态​

  • failed - 支付失败，需要重新处理
  • active - 活跃订阅，正常计费
  • paused - 已暂停，不会产生新的计费
  • cancelled - 已取消，无法恢复
  • past_due - 逾期未付，等待重试

工作流程​

方式一：商户自主管理订阅计划（推荐）​

如果您需要自己管理订阅计划，可以配合使用以下两个接口：

  1. 创建Token - 安全存储客户信息和支付方式
  2. Token支付 - 使用Token进行一次性支付，不创建订阅计划
  3. 自主管理 - 商户在自己的系统中管理订阅逻辑、计费周期等
  4. 灵活控制 - 完全控制订阅的生命周期和业务规则

适用场景：商户有自己的订阅管理系统，需要灵活控制订阅逻辑和计费规则。

方式二：支付机构管理订阅计划​

如果您希望支付机构管理订阅计划，可以使用以下方式：

  1. 创建订阅 - 直接使用create-subscription接口
  2. 传递计划 - 通过plan对象传递完整的订阅计划信息
  3. 自动管理 - 支付机构自动处理订阅生命周期、计费、重试等
  4. 简化集成 - 商户无需管理复杂的订阅逻辑

适用场景：商户希望简化集成，将订阅管理交给支付机构处理。

方式三：使用Token创建订阅（传统方式）​

  1. 创建Token - 安全存储客户信息和支付方式
  2. 创建订阅 - 使用Token中的客户ID、计划ID和支付方式ID创建订阅
  3. 管理订阅 - 修改计划、暂停或取消订阅
  4. 处理付款 - 系统自动处理定期付款

API 端点概览​

商户自主管理订阅计划​

操作方法端点说明
创建TokenPOST/v4/tokens安全存储客户信息和支付方式
Token支付POST/v4/tokens/{token_id}/payment使用Token进行一次性支付

支付机构管理订阅计划​

操作方法端点说明
创建订阅POST/v4/subscriptions直接创建订阅，传递完整计划信息
获取订阅GET/v4/subscriptions/{id}获取订阅详情
列出订阅GET/v4/subscriptions列出所有订阅
修改订阅POST/v4/subscriptions/{id}修改订阅信息
暂停/恢复/取消订阅POST/v4/subscriptions/{id}/status统一的状态管理接口

安全性​

  • 支付信息通过Token进行安全处理，不存储原始卡片数据
  • 支持 PCI DSS 合规性
  • 使用 HTTPS 和 API 密钥进行身份验证
  • 支持幂等性密钥防止重复请求
  • Token具有24小时有效期，确保安全性
  • 支持 Webhook 进行实时状态更新

支持的支付方式​

  • 信用卡/借记卡（Visa、Mastercard、American Express 等）
  • 数字钱包
  • 银行转账（根据地区而定）

最佳实践​

选择订阅管理方式​

商户自主管理订阅计划​

  • 优势：完全控制订阅逻辑、灵活的计费规则、自定义业务流程
  • 适用：有技术团队、需要复杂订阅逻辑、希望深度定制
  • 建议：使用create-token + token-payment组合，在自己的系统中管理订阅状态

支付机构管理订阅计划​

  • 优势：快速集成、自动处理复杂逻辑、减少维护成本
  • 适用：快速上线、技术资源有限、标准化订阅需求
  • 建议：使用create-subscription接口，通过plan对象传递完整计划信息

Token使用​

  1. 及时使用: Token创建后应在24小时内使用
  2. 幂等性: 始终使用UUID作为幂等性密钥
  3. 错误处理: 妥善处理Token过期和无效的情况

订阅管理​

  1. 试用期: 合理设置试用期以提高转化率
  2. 按比例计费: 对升级使用按比例计费，提升客户体验
  3. 状态监控: 通过Webhook监控订阅状态变化
  4. 客户沟通: 在暂停、恢复或取消前与客户确认

数据管理​

  1. 元数据: 使用元数据存储业务相关信息
  2. 描述: 为订阅添加清晰的描述
  3. 记录变更: 记录所有重要的变更操作和原因

接下来的章节将详细介绍每个 API 端点的使用方法。

Powered by Docusaurus