This guide explains how to use Onerway Checkout to sell subscriptions. Through the subscription field, you will learn how to set up your subscription plans.
Integration Profile
Customization Options
Onerway offers two subscription models:
| Comparison Item | Managed Subscription | Self-Managed Subscription |
|---|---|---|
| Renewal Charge | Executed automatically by Onerway | Merchant calls API manually |
| Failed Charge Handling | Automatic retry | Handled by merchant |
| Customer Management Portal | Subscription management portal provided | Implemented by merchant |
| Billing Flexibility | Fixed amount/cycle | Fully adjustable |
How to Choose:
| Business Scenario | Recommended Model |
|---|---|
| Fixed cycle & fixed amount (e.g., membership subscription) | Managed Subscription |
| Usage-based billing with variable amounts | Self-Managed Subscription |
| Quick launch, no desire to maintain billing logic | Managed Subscription |
Configure Checkout Parameters
Subscribe to bilibili monthly pro
22.85 USD
per Monthly
Pay with card
Country
Card information
Cardholder name
By confirming your subscription, you allow to charge you for future payments in accordance with their terms. You can always cancel your subscription.
This is a demo for illustration purposes only. No real transactions will be processed.
First, create a subscription product in your payment platform, defining the product name, price, and billing cycle. Make sure to configure related tax rates and currency options.
For multiple calls with the same merchantTxnId (possibly concurrent), use database transactions or distributed locks to prevent race conditions.
When creating a subscription, set subProductType to SUBSCRIBE in the Checkout API and pass the subscription parameter:
| Required Parameter | Description |
|---|---|
merchantCustId | Unique customer identifier for associating the subscription with the user |
frequencyType | Billing interval unit: D for days, M for months |
frequencyPoint | The interval value for billing |
cycleCount or expireDate | Either the total number of billing cycles or the expiration date (mutually exclusive) |
Use Checkout to create a hosted payment page for your subscription. The customer will be redirected to Onerway's secure payment page to complete the transaction.
Customers will complete these steps on the checkout page:
Checkout features:
After the payment is completed, Onerway will redirect the customer back to your returnUrl. You need to verify the payment result and update your system accordingly.
After payment completion, Onerway notifies the result through two methods:
| Callback Type | Trigger | Processing Recommendation |
|---|---|---|
| Synchronous callback | Customer returns to returnUrl after payment | Display result page; do not rely on this status |
| Asynchronous notification | Onerway sends webhook to notifyUrl | Verify signature, deduplicate, update subscription status |
Subscription status is determined by webhook notifications. Synchronous callbacks are for display purposes only; always confirm the final status through webhooks.
| Data | Purpose |
|---|---|
contractId | Subscription contract identifier, used for querying and management |
tokenId | Payment token, used to initiate charges |
subscriptionManageUrl | Customer self-service management page (hosted subscription) |
Set up a webhook endpoint to receive real-time notifications about subscription events:
| Scenario | Trigger |
|---|---|
SUBSCRIPTION_INITIAL | First-time subscription successful |
SUBSCRIPTION_RENEWAL | Renewal charge successful |
SUBSCRIPTION_CHANGED | Plan changed |
SUBSCRIPTION_CANCELED | Subscription canceled |
SUBSCRIPTION_ENDED | Naturally expired |
Onerway automatically charges before expiration and sends a SUBSCRIPTION_RENEWAL webhook. Failed charges are automatically retried and the status becomes pastdue. Merchants only need to listen to webhooks to update local status.
Merchants need to call the API to initiate charges before expiration, passing contractId + tokenId + merchantCustId, and handle charge results and retry logic themselves.
Customers will receive subscription emails from Onerway containing a subscription management URL, enabling them to view subscription details, update payment methods, and cancel subscriptions through self-service.
| Status | Description |
|---|---|
trialing | Trial period in progress |
active | Active and scheduled for renewal |
pastdue | Past due due to failed payment |
canceled | Canceled; remains active until the end of the current billing cycle |
ended | Subscription terminated |