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 and fixed amount (for example, membership subscriptions) | Managed Subscription |
| Usage-based billing with variable amounts | Self-Managed Subscription |
| Quick launch without maintaining billing logic | Managed Subscription |
First, create a subscription product in your payment platform and define the product name, price, and billing cycle. Make sure related tax and currency settings are configured as needed.
When creating the subscription, set subProductType to SUBSCRIBE in the Checkout API and pass the subscription parameter:
| Required Parameter | Description |
|---|---|
merchantCustId | Unique customer identifier used to associate the subscription |
frequencyType | Billing interval unit: D for days and M for months |
frequencyPoint | Billing interval value |
cycleCount or expireDate | Either the total cycle count or the expiration date |
{
"subProductType": "SUBSCRIBE",
"subscription": {
"merchantCustId": "cust_10001",
"frequencyType": "M",
"frequencyPoint": 1,
"cycleCount": 12
}
}
Use Checkout to create a hosted payment page for your subscription. The customer is redirected to Onerway's secure payment page to complete the transaction.
On the checkout page, the customer will:
Checkout features include:
After the payment is completed, Onerway redirects the customer back to your returnUrl. You still need to verify the payment result and update your system.
After payment completion, Onerway notifies the result in two ways:
| Callback Type | Trigger | Processing Recommendation |
|---|---|---|
| Synchronous callback | Customer returns to returnUrl after payment | Display the result page and do not rely on this status |
| Asynchronous notification | Onerway sends a webhook to notifyUrl | Verify the signature, deduplicate the event, and update the subscription status |
Subscription status should be based on webhook notifications. The synchronous callback is for display only.
After the first successful payment, store the following fields for renewals, cancellation, payment method updates, and support inquiries:
| Data | Purpose |
|---|---|
contractId | Subscription contract identifier used for query and management |
tokenId | Payment token used to initiate later charges |
merchantCustId | Keeps the user-to-subscription relationship |
subscriptionManageUrl | Customer self-service page for hosted subscriptions |
Set up a webhook endpoint to receive real-time notifications for subscription events:
| Event | Meaning |
|---|---|
SUBSCRIPTION_INITIAL | First subscription payment succeeded |
SUBSCRIPTION_RENEWAL | Renewal charge succeeded |
SUBSCRIPTION_CHANGED | Plan changed |
SUBSCRIPTION_CANCELED | Subscription canceled |
SUBSCRIPTION_ENDED | Subscription ended naturally |
In the managed subscription model, Onerway automatically charges before the due date and sends a SUBSCRIPTION_RENEWAL webhook. Failed charges are retried automatically, and the subscription moves to pastdue. You only need to listen to the webhook and update local status.
In the self-managed subscription model, you need to call the charge API before the due date and pass contractId, tokenId, and merchantCustId. Charge results, retry strategies, and failure handling are maintained by you.
| Status | Meaning |
|---|---|
trialing | Trial period in progress |
active | Active and waiting for the next charge |
pastdue | Payment overdue because the charge failed |
canceled | Canceled and remains active until the current cycle ends |
ended | Ended |
Customers receive a subscription email from Onerway with a management entry. In that entry, they can view the subscription details, update the payment method, or cancel the subscription.