Subscriptions

Set up recurring billing to collect payments automatically on a schedule—perfect for SaaS, memberships, and content subscriptions.

What is Subscription

Subscription is a payment service that continuously collects payments from users. Unlike one-time payments, subscriptions support automatically charging users at set intervals, suitable for business scenarios that require ongoing service provision.

Subscription vs One-time Payment

Comparison Dimension	One-time Payment	Subscription Payment
Billing Frequency	One-time	Periodic (daily/monthly/yearly)
User Authorization	Requires user confirmation each time	Automatic billing after initial authorization
Applicable Scenarios	Product purchase, one-time services	Memberships, content subscriptions, ongoing services
Revenue Predictability	Low	High (stable recurring revenue)

Value of Subscriptions

For Merchants:

Build stable recurring revenue
Reduce user churn, increase customer lifetime value (LTV)
Simplify billing process, reduce operational costs

For Users:

No need for repeated payment operations, more convenient experience
Continuous service enjoyment, avoid service interruptions

Core Capabilities

Automatic Billing

The core of subscription is automatic billing capability, supporting two modes:

Mode	Description	Applicable Scenarios
Managed Subscription	Onerway automatically bills according to the cycle, merchants only need to handle billing result notifications	Merchants wanting to simplify operations
Self-managed Subscription	Merchants control billing timing themselves, manually trigger billing requests	Merchants needing flexible control over billing logic

Flexible Billing Cycles

Supports multiple billing cycle configurations:

By Day (D) — e.g., bill every 7 days
By Month (M) — e.g., bill monthly (managed subscription only)
By Year (Y) — e.g., bill annually (managed subscription only)

Self-managed subscriptions only support daily (D) billing.

Subscription Lifecycle Management

Manage each user's subscription status through Subscription Contract (contractId):

Create Subscription — User completes initial purchase/signing
Recurring Billing — Automatic/manual renewal according to set cycle
Upgrade/Downgrade — Change subscription plan, system calculates price difference (managed subscription only)
Pause/Resume — Temporarily pause billing (via management page)
Cancel Subscription — Terminate subscription relationship

Subscription Status Description:

Status	Description
trialing	In trial period
active	Subscription active
paymentdue	Payment due
pastdue	Payment overdue
paused	Paused
canceled	Canceled
ended	Ended (expired)

Trial Period Support

Supports setting trial periods for subscriptions:

Set by number of days (e.g., 7-day trial)
Set by end date
Configurable whether trial period counts toward subscription cycle

Billing Result Notifications

Notify merchants of billing results asynchronously via Webhook. Merchants need to:

Verify notification signature
Update local subscription status
Handle billing failures

Customer Subscription Management

Supports sending subscription-related email notifications to customers. Customers can view and manage their subscription services via email, including:

View subscription details
Manage payment methods
Cancel subscription

Core Concepts

Initial Purchase and Renewal

Concept	Description	requestType
Initial Purchase	User's first subscription, creates subscription contract, completes first payment or signs only	`0`
Renewal	Subsequent recurring billing (managed subscription executes automatically, self-managed subscription initiated by merchant)	`1`
Upgrade/Downgrade	Change subscription plan, requires price difference amount (managed subscription only)	`2`

Subscription Contract and Payment Token

Subscription Contract (contractId) — Represents the subscription relationship between user and merchant, uniquely identifies a subscription
Payment Token (tokenId) — User-authorized payment method credential, used for subsequent automatic billing

Merchants should properly save contractId and tokenId for subsequent renewals and subscription management.

Subscription Product Name

If not providing productName: Each customer can only create one subscription
If providing productName: Same customer can subscribe to multiple different products

Subscription Validity Configuration

Managed subscriptions require setting subscription validity, choose one:

Parameter	Description	Example
cycleCount	Number of billing cycles (1-99)	12 times
expireDate	Subscription end date	2025-12-31

Billing Modes

Mode	mode Value	Description
Sign Only	`1`	User authorizes but no immediate billing, suitable for scenarios starting with trial period
Sign and Bill	`2`	User authorizes and completes first billing simultaneously (default)

Subscription Cycle

Subscription cycle determines the time interval for automatic billing, consisting of two parameters:

Parameter	Description	Options
frequencyType	Cycle type	D (day), M (month), Y (year)
frequencyPoint	Cycle interval value	Number, e.g., 1, 7, 30

Cycle Examples:

frequencyType	frequencyPoint	Meaning
D	1	Bill once per day
D	7	Bill every 7 days
M	1	Bill monthly
Y	1	Bill annually

Cycle Restrictions:

Subscription Type	Supported Cycle Types
Managed Subscription	D (day), M (month), Y (year)
Self-managed Subscription	D (day) only

Billing Time Points:

Managed Subscription — Onerway automatically initiates billing according to set cycle
Self-managed Subscription — Merchant controls billing timing, frequencyPoint serves only as suggested interval

Subscription Updates (Upgrade/Downgrade)

Subscription updates allow customers to change subscription plans during the subscription period (e.g., upgrade from basic to premium).

Only managed subscriptions support upgrade/downgrade functionality.

Update Parameters:

Parameter	Description	Options
requestType	Request type	`2` (indicates upgrade/downgrade)
changeMode	Effective method	`1` immediate effect, `2` effective next billing cycle
proration	Price difference amount	Upgrade requires additional payment, downgrade requires refund handling

Effective Method Description:

changeMode	Description	Applicable Scenarios
`1`	Immediate effect	Customer wants to use new plan benefits immediately
`2`	Effective next billing cycle	Continue using original plan for current cycle, switch next cycle

Price Difference Handling:

Upgrade — When effective immediately (changeMode=1), calculate price difference based on remaining days and collect
Downgrade — When effective immediately (changeMode=1), merchant needs to call refund API to handle price difference refund

Object Relationships

Applicable Scenarios

Recommended Scenarios

Scenario	Examples
SaaS Software Services	Monthly/annual software usage fees
Membership Subscriptions	E-commerce memberships, VIP privileges
Content Subscriptions	Streaming, knowledge payment, news subscriptions
Recurring Services	Insurance renewals, gym memberships, online education
Scheduled Purchases	Regular delivery of daily necessities, food

Not Applicable Scenarios

One-time large transactions
Variable amount pay-per-use (e.g., usage-based billing)
Payment scenarios requiring user confirmation each time

How to Integrate Subscriptions

Prerequisites

Completed merchant registration, obtained merchant number (merchantNo)
Obtained signing key
Distinguished Sandbox (testing) and Production environments
Familiar with checkout payment interface general parameters and signing rules

Integration Method Selection

Integration Method	Description	Development Cost
Managed Subscription	Platform bills automatically, simple integration	Low
Self-managed Subscription	Merchant controls billing, high flexibility	Medium

Integration Process Overview

Preparation — Obtain merchant number, signing key, configure callback URL
Create Initial Purchase Request — Call checkout interface, pass subProductType=SUBSCRIBE and subscription configuration
User Completes Payment/Signing — Redirect to checkout, user completes authorization
Obtain Subscription Credentials — Get contractId, tokenId from sync return/async notification
Handle Subsequent Billing
- Managed Subscription: Wait for platform automatic billing notification
- Self-managed Subscription: Merchant initiates billing request per cycle
Subscription Management — Handle upgrade/downgrade, cancellation operations

Appendix

Glossary

Term	Description
contractId	Subscription contract ID, uniquely identifies a subscription
tokenId	Payment token, used for subsequent billing
selfExecute	Managed mode: 1=managed subscription, 2=self-managed subscription
requestType	Request type: 0=initial purchase, 1=renewal, 2=upgrade/downgrade
mode	Billing mode: 1=sign only, 2=sign and bill
frequencyType	Cycle type: D=day, M=month, Y=year
frequencyPoint	Cycle interval value

Supported Payment Methods

Subscriptions support the following payment methods:

Type	Payment Methods	Description
Card Payment	Visa, Mastercard, etc.	Supports managed and self-managed subscriptions
Local Payment	DANA, WeChat, GCash, Touch'n Go	Self-managed subscription only, requires zero-amount signing first

Local payment method subscriptions need to use sign-only mode (mode=1), establishing the contract through a zero-amount initial transaction.

Apple Pay

Accept Apple Pay payments worldwide with Onerway.

Strong Customer Authentication (SCA)

A European regulatory requirement introduced by PSD2 to reduce fraud and make online and contactless offline payments more secure