Subscriptions Overview

EFundFlow subscription system allows you to create and manage recurring payments for your customers. The subscription system supports flexible billing cycles, automatic retry of failed payments, and comprehensive subscription lifecycle management.

Core Concepts

Token (Payment Token)

A payment token is a secure way to store customer payment information, including customer details and payment method information. Tokens are used to simplify the subscription creation process and ensure the security of payment information.

Customer

A customer is the core entity of the subscription system, containing basic customer information and billing details. Each customer can have multiple subscriptions and payment methods.

Plan

A plan defines the pricing, billing cycle, and other configurations for a subscription. Plans can be used by multiple subscriptions, making it easy to manage pricing strategies uniformly.

Payment Method

A payment method is the method a customer uses to pay for subscription fees, such as credit cards, bank accounts, etc. Payment methods are associated with customers and can be reused.

Subscription

A subscription links customers, plans, and payment methods together, defining a specific instance of recurring payments. Each subscription has independent lifecycle management.

Subscription Status

• failed - Payment failed, requires reprocessing
• active - Active subscription, normal billing
• paused - Paused, will not generate new billing
• cancelled - Cancelled, cannot be restored
• past_due - Overdue payment, waiting for retry

Workflow

Method 1: Merchant Self-Managed Subscription Plans (Recommended)

If you need to manage subscription plans yourself, you can use the following two interfaces together:

1. Create Token - Securely store customer information and payment methods
2. Token Payment - Use tokens for one-time payments without creating subscription plans
3. Self-Management - Merchants manage subscription logic, billing cycles, etc. in their own systems
4. Flexible Control - Complete control over subscription lifecycle and business rules

Applicable Scenarios: Merchants have their own subscription management systems and need flexible subscription logic and billing rules.

Method 2: Payment Institution Managed Subscription Plans

If you want payment institutions to manage subscription plans, you can use the following method:

1. Create Subscription - Directly use the create-subscription interface
2. Pass Plan - Pass complete subscription plan information through the plan object
3. Automatic Management - Payment institutions automatically handle subscription lifecycle, billing, retries, etc.
4. Simplified Integration - Merchants don't need to manage complex subscription logic

Applicable Scenarios: Merchants want to simplify integration and delegate subscription management to payment institutions.

Method 3: Using Tokens to Create Subscriptions (Traditional Method)

1. Create Token - Securely store customer information and payment methods
2. Create Subscription - Use customer ID, plan ID, and payment method ID from the token to create subscriptions
3. Manage Subscriptions - Modify plans, pause or cancel subscriptions
4. Process Payments - System automatically handles recurring payments

API Endpoint Overview

Merchant Self-Managed Subscription Plans

Operation	Method	Endpoint	Description
Create Token	POST	/v4/tokens	Securely store customer information and payment methods
Token Payment	POST	/v4/tokens/{token_id}/payment	Use tokens for one-time payments

Payment Institution Managed Subscription Plans

Operation	Method	Endpoint	Description
Create Subscription	POST	/v4/subscriptions	Directly create subscriptions, pass complete plan information
Get Subscription	GET	/v4/subscriptions/{id}	Get subscription details
List Subscriptions	GET	/v4/subscriptions	List all subscriptions
Update Subscription	POST	/v4/subscriptions/{id}	Modify subscription information
Pause/Resume/Cancel Subscription	POST	/v4/subscriptions/{id}/status	Unified status management interface

Security

• Payment information is securely processed through tokens without storing raw card data
• Supports PCI DSS compliance
• Uses HTTPS and API keys for authentication
• Supports idempotency keys to prevent duplicate requests
• Tokens have a 24-hour expiration period to ensure security
• Supports webhooks for real-time status updates

Supported Payment Methods

• Credit/Debit cards (Visa, Mastercard, American Express, etc.)
• Digital wallets
• Bank transfers (depending on region)

Best Practices

Choosing Subscription Management Methods

Merchant Self-Managed Subscription Plans

• Advantages: Complete control over subscription logic, flexible billing rules, customizable business processes
• Applicable: Have technical teams, need complex subscription logic, want deep customization
• Recommendation: Use create-token + token-payment combination, manage subscription status in your own system

Payment Institution Managed Subscription Plans

• Advantages: Quick integration, automatic handling of complex logic, reduced maintenance costs
• Applicable: Quick launch, limited technical resources, standardized subscription needs
• Recommendation: Use create-subscription interface, pass complete plan information through plan objects

Token Usage

1. Use Promptly: Tokens should be used within 24 hours of creation
2. Idempotency: Always use UUIDs as idempotency keys
3. Error Handling: Properly handle token expiration and invalid situations

Subscription Management

1. Trial Period: Reasonably set trial periods to improve conversion rates
2. Prorated Billing: Use prorated billing for upgrades to improve customer experience
3. Status Monitoring: Monitor subscription status changes through webhooks
4. Customer Communication: Confirm with customers before pausing, resuming, or cancelling

Data Management

1. Metadata: Use metadata to store business-related information
2. Description: Add clear descriptions for subscriptions
3. Record Changes: Record all important change operations and reasons

The following chapters will detail the usage methods of each API endpoint.