Subscription

API Request Parameters

POST

Key Parameters for Subscription

When integrating subscription payments, you need to adjust two key parameters compared to regular Checkout:

1. subProductType: Must be set to SUBSCRIBE for all subscription transactions.

2. subscription: JSON format string containing subscription details, required for all subscription transactions.

{
    // ...
    "subProductType": "SUBSCRIBE",
    "subscription": "refer to the table below",
    // ...
}

Managed Subscription

Initial Subscription

Subscription Update

Name	Type	Length	Required	Description
requestType	String	1	Yes	Subscription request type, please refer to RequestTypeEnum
merchantCustId	String	40	Yes	Unique identifier for the user in the merchant's system, used to associate the user with subscription information. This ID will be used for subscription creation, query, and management. Please ensure its uniqueness in your system.
productName	String	256	Conditional	Subscription product name, used to distinguish different subscription services or plans. If not provided, each user can only create one subscription; if provided, the same user can subscribe to multiple different products.
frequencyType	String	1	Conditional	Subscription cycle unit: D-Day M-Month Y-Year Determines the basic time unit of the billing cycle.
frequencyPoint	String	2	Conditional	Suggested subscription cycle value.
cycleCount	int	256	Conditional	Number of cycles, supports 1-100.
expireDate	String	10	Conditional	Subscription termination date, format is yyyy-MM-dd. After this date, the managed system will no longer trigger billing.
mode	String	1	Yes	Subscription authorization mode: 1 - Authorize first, bill later (two-step process): User authorizes merchant for recurring payments, with actual billing triggered in subsequent cycles 2 - Authorize and bill immediately (one-step process, default value): User authorizes and completes initial payment simultaneously
selfExecute	String	1	Yes	Subscription billing mode: 1 - Automatic billing (recommended): The payment system automatically executes periodic billing according to the set frequency 2 - Merchant-triggered billing: The merchant system needs to actively call the API to initiate each billing
bindCard	String	300	No	Subscription credit card binding option: true - Complete subscription and bind card information to user ID false - Only complete subscription without binding card information
trialFromPlan	String	256	Conditional	Trial period billing mode: 0 - Trial period not included in subscription plan (no charge) 1 - Trial period included in subscription plan (charged)
trialDays	int	256	Conditional	Trial period days, supports range from 3-365 days. When setting a trial period, choose either this or trialEnd.
trialEnd	String	256	Conditional	Trial period end date, format is yyyy-MM-dd. When setting a trial period, choose either this or trialDays.
notificationEmail	String	256	No	Buyer's email address for subscription notifications (including successful subscription billing, subscription cancellation, and other notifications).
metaData	String	2048	No	Merchant custom information, used to store business data. Supports JSON format, returned as-is when querying subscriptions.

Code Snippets

Trial with Days Parameter

// Trial initial purchase - Billing once per day for 30 days, with a 3-day trial period included in the subscription plan, automatic billing after trial ends

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"Auto-bill 30 days-Trial 3 days(included)-Once daily\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"1\",\"trialDays\":3,\"notificationEmail\":\"abel.wang@onerway.com\"}"

Trial with End Date

// Trial initial purchase - Billing once per day for 33 days, with a 3-day trial period not included in the subscription plan, automatic billing after trial ends

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"Auto-bill 30 days-Trial 1 day(not included)-Once daily\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"0\",\"trialEnd\":\"2024-11-07\",\"notificationEmail\":\"abel.wang@onerway.com\"}"

Immediate Billing with End Date

// Non-trial initial purchase - Billing once per day until the specified expiration date (2024-12-04), no trial period, automatic billing starts immediately

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522099\",\"productName\":\"Auto-bill 30 days-No trial-Once daily-Expiry time 6\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\"}"

Sign-only Monthly Subscription

// Sign-only mode - Billing once per month, sign agreement but no immediate billing

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522100\",\"productName\":\"Sign-only-Once monthly\",\"frequencyType\":\"M\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"mode\":\"1\"}"

Subscription Upgrade with Proration

// Upgrade/Downgrade - Billing once per day for 30 days, immediate upgrade, proration amount 30

"subscription": "{\"requestType\":\"2\",\"tokenId\":\"tokenId_xxx\",\"contractId\":\"contractId_xxx\",\"productName\":\"Subscription upgrade-Immediate effect with proration\",\"proration\":\"30\",\"merchantCustId\":\"custId_xxx\"}"

Self-Managed Subscription

Initial Subscription

Recurring Subscription

Name	Type	Length	Required	Description
requestType	String	1	Yes	Subscription request type: Fixed value 0 (initial purchase).
merchantCustId	String	40	Yes	Unique identifier for the user in the merchant's system, used to associate the user with subscription information. This ID will be used for subscription creation, query, and management. Please ensure its uniqueness in your system.
productName	String	256	Conditional	Subscription product name, used to distinguish different subscription services or plans. If not provided, each user can only create one subscription; if provided, the same user can subscribe to multiple different products.
frequencyType	String	1	Yes	Subscription cycle unit: Non-managed subscription mode only supports D (day).
frequencyPoint	String	2	Yes	Suggested subscription cycle value, indicating how many days between billings.
expireDate	String	10	Yes	Subscription termination date, format is yyyy-MM-dd. After this date, the system will not allow any further subscription charges.
mode	String	1	Yes	Signing mode: 1 - Sign first, then bill (two-step process): Initial zero-amount authorization followed by merchant-initiated billing 2 - Sign and bill immediately (one-step process, default value): Authorization and initial payment combined
selfExecute	String	1	Yes	Subscription billing mode: For non-managed subscription, fixed as 2 - Merchant-triggered billing: The merchant system is responsible for calculating billing time and actively calling the API to initiate each billing

Code Snippets

Sign-Only Mode

// Self-managed subscription - Sign-only mode, no immediate billing
// For local payment methods like WeChat, DANA, GCash, or TOUCH_GO_EWALLET

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"Self-managed-Sign only\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

Immediate Billing Mode

// Self-managed subscription - Immediate billing mode, bills immediately
// Typically used for credit card payments or some local payment methods

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"Self-managed-Immediate billing\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}"

Renewal Billing Request

// Self-managed subscription - Renewal billing, using existing subscription contract to initiate a new billing cycle
// Use the contractId and tokenId received from the initial subscription webhook

"subscription": "{\"requestType\":\"1\",\"contractId\":\"contractId_xxx\",\"tokenId\":\"tokenId_xxx\",\"merchantCustId\":\"custId_xxx\"}"

Local Payment Subscription

// Example for DANA, WeChat, GCash, or TOUCH_GO_EWALLET subscription
// Zero-amount initial transaction to establish the contract

"lpmsInfo": "{\"lpmsType\":\"DANA\",\"iBan\":\"DE89370400440532013000\"}",
"productType": "LPMS",
"subProductType": "SUBSCRIBE",
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

Subscription Integration Process

The Onerway subscription process consists of three main phases as illustrated below:

1. Subscription Initiation

In this phase:

• Merchant system sends a subscription request to Checkout API with subProductType=SUBSCRIBE and subscription details
• The subscription parameter must contain frequency information, product details, and optional trial period settings
• Onerway creates both a transaction record and a subscription contract
• The initial subscription status is Unfinished (U)

2. Checkout Process

In this phase:

• Merchant redirects the customer's browser to the Onerway checkout page using the redirectUrl
• Customer selects a payment method and enters payment information
• If 3DS verification is required, the customer completes this step before the subscription is established
• The payment information is securely stored for future recurring charges (if using Managed Subscription)

3. Subscription Confirmation

In this phase:

• Synchronized notification: Customer is redirected back to the merchant's website through the returnUrl
• Asynchronous notification (webhook): Onerway sends detailed subscription result data to the notifyUrl
• Subscription email (Managed Subscription only): A confirmation email is sent to the notificationEmail with subscription details and management URL
• The webhook contains complete subscription information including transactionId, contractId, tokenId, and subscriptionStatus
• Merchant system must respond with transactionId to acknowledge receipt of the webhook
• If no successful response is received, Onerway will retry sending the webhook 3 times

For a complete description of all webhook notification fields received during subscription transactions, including subscription-specific fields like contractId, tokenId, subscriptionStatus, and scenarios, please refer to the Webhook Notification Documentation.

Payment Completion Examples

Redirect to Merchant (returnUrl)

https://www.merchant-store-website.com/?transactionId=1853980684692361216&merchantTxnId=1730858419000&merchantNo=800209&responseTime=2024-11-06%2010%3A22%3A47&txnTime=2024-11-06%2010%3A22%3A06&txnTimeZone=%2008%3A00&orderAmount=0.00&orderCurrency=USD&txnAmount=0.00&txnCurrency=USD&status=S&reason=Payment%20successful&contractId=1853980684755275776&tokenId=2a262447389a33cbab0a1221fd6a0f36fd7cab70d0abf1b0a34bae3aae67ba19

Server Notification - Managed Subscription (notifyUrl)

{
  "notifyType": "TXN",
  "transactionId": "1919772912060342272",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "ec91ee2b-7ba9-444f-8875-955fe94fadf3",
  "responseTime": "2025-05-06 23:15:33",
  "txnTime": "2025-05-06 23:15:20",
  "txnTimeZone": "+08:00",
  "orderAmount": "2.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919772912228114432", 
  "tokenId": "195f7e75785863a66d3801ae02c12e24ea16abe164303cf3e3fd10e04d5e4188", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "6e8bd132b805c6ad530857331bef43c25e4c4a544dc2e0494cfd1ad94a7f55dc",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5NzcyOTEyMjI4MTE0NDMyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUtYUlAtMzcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", 
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"currant\",\"num\":\"78\",\"price\":\"620.39\",\"type\":\"ullamco et do commodo ut\"},{\"currency\":\"USD\",\"name\":\"strawberry\",\"num\":\"63\",\"price\":\"289.61\",\"type\":\"labore cupidatat Duis elit\"},{\"currency\":\"USD\",\"name\":\"grapefruit\",\"num\":\"24\",\"price\":\"989.09\",\"type\":\"ullamco non\"}]",
  "metaData": "eventually",
  "channelRequestId": "8002091919772982323052544",
  "scenarios": "SUBSCRIPTION_INITIAL"
}

Server Notification - Self Managed Subscription (notifyUrl)

{
  "notifyType": "TXN",
  "transactionId": "1914230281599320064",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "8a4e276e-86c2-4753-b91a-0cc8881e4d0d",
  "responseTime": "2025-04-21 16:10:58",
  "txnTime": "2025-04-21 16:10:38",
  "txnTimeZone": "+08:00",
  "orderAmount": "33.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1914230281792258048", 
  "tokenId": "7a83c22d55ca1e383fefbf1537c90b065a7324aee29a36d4b39c66da377a9b57", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "432894a2c697e01e4fe86eaa4f2564fb13ea97d0b4662a45fc83d1aa076985d1",
  "paymentMethod": "VISA",
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"mandarin\",\"num\":\"47\",\"price\":\"234.19\",\"type\":\"eu dolore in\"}]",
  "metaData": "pfft",
  "channelRequestId": "8002091914230287013908481",
  "scenarios": "SUBSCRIPTION_INITIAL"
}

4. Recurring Billing Process

Managed Subscription

Self-Managed Subscription

In Managed Subscription:

• Onerway automatically handles all recurring charges according to the subscription schedule
• Each recurring payment generates a webhook notification to the merchant
• Customers can manage their subscription through the subscriptionManageUrl provided in the confirmation email
• The management portal allows customers to view subscription history, update payment methods, or cancel the subscription

Important Notes

• For Self-Managed Subscription: Merchants must use the Subscription Billing API to initiate renewal payments
• The subscription contract (contractId) and payment token (tokenId) must be saved for future renewal transactions
• Always rely on webhook notifications as the definitive source for subscription status
• Multiple webhook notifications may be received; deduplication based on transaction ID is recommended
• Transaction status S indicates success, F indicates failure; refer to TxnStatusEnum for other status codes

API Usage Examples

Onerway sends webhook notifications for all subscription events to the notifyUrl specified in the original subscription request. These notifications provide real-time updates on subscription status changes.

Webhook Scenarios

The scenarios field in webhook notifications indicates the specific subscription event that triggered the notification:

• SUBSCRIPTION_CREATED - New subscription created
• SUBSCRIPTION_TRIAL_WILL_END - Trial period is ending soon
• SUBSCRIPTION_RENEWAL - Subscription was successfully renewed
• SUBSCRIPTION_PAYMENT_FAILED - Renewal payment attempt failed
• SUBSCRIPTION_CHANGED - Subscription plan or details were updated
• SUBSCRIPTION_CANCELED - Subscription has been canceled
• SUBSCRIPTION_ENDED - Subscription has reached its natural end date

Subscription Status Reference

The subscriptionStatus field in responses and webhooks indicates the current state of the subscription:

• trialing - In trial period
• paymentdue - Payment pending
• active - Active subscription
• pastdue - Payment overdue
• paused - Temporarily suspended
• canceled - Canceled by user or merchant
• ended - Completed subscription term

Initial Subscription Requests

These examples demonstrate how to create subscription requests with and without trial periods.

Initial Subscription with Trial

{
    "billingInformation": "{\"address\":\"922 N Pearl Street\",\"city\":\"Everardoport\",\"country\":\"US\",\"email\":\"Mozell.Bode@hotmail.com\",\"firstName\":\"Brittany\",\"identityNumber\":\"51235988984\",\"lastName\":\"Blanda\",\"phone\":\"14237418013\",\"postalCode\":\"78100\",\"province\":\"CO\"}",
    "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}",
    "merchantCustId": "CustId-B2T2-16U1",
    "merchantNo": "800209",
    "merchantTxnId": "a8d5e39d-c7bb-41bf-b619-296178049b74",
    "merchantTxnTime": "2025-04-21 16:24:36",
    "orderAmount": "2",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"273 Chestnut Street\",\"city\":\"Germanview\",\"country\":\"US\",\"email\":\"Jared_Rice89@yahoo.com\",\"firstName\":\"Fermin\",\"identityNumber\":\"69178649516\",\"lastName\":\"Bernier\",\"phone\":\"19742024658\",\"postalCode\":\"12485-1655\",\"province\":\"CO\"}",
    "sign": "45ab55d0a94ba1a305a9a4d7a346b2b0eb89daa460cc02772cff23e864b368da",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"selfExecute\":\"1\",\"productName\":\"Elegant Concrete Car\",\"frequencyType\":\"D\",\"bindCard\":true,\"merchantCustId\":\"CustId-230Y-D1LZ\",\"frequencyPoint\":\"24\",\"notificationEmail\":\"Dulce_Veum87@yahoo.com\",\"metaData\":\"culpa ullamco aliqua\",\"trialFromPlan\":\"1\",\"cycleCount\":28,\"trialEnd\":\"2026-02-13\"}", 
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"1024\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"apricot\\\",\\\"num\\\":\\\"39\\\",\\\"price\\\":\\\"128.29\\\",\\\"type\\\":\\\"laborum sint magna\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"896\",\"screenWidth\":\"414\",\"timeZoneOffset\":\"-420\",\"transactionIp\":\"30.35.165.176\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "SALE"
}

Initial Subscription without Trial

{
    "billingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"Akşehir\"}",
    "merchantCustId": "1731380698000",
    "merchantNo": "800209",
    "merchantTxnId": "1731380698000",
    "merchantTxnTime": "2024-11-12 11:04:58",
    "merchantTxnTimeZone": "+08:00",
    "orderAmount": "20",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"Akşehir\"}",
    "sign": "d2f4ecc82ccb9aded60d500b603a89342ef260f2c5d04bcc82fde6949502e8ad",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"1731380698000\",\"productName\":\"Daily Auto Debit Until Nov 15 - No Trial\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-11-15\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"tokenId\":\"\",\"contractId\":\"\"}", 
    "txnOrderMsg": "{\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://www.merchant-store-notify.com\",\"products\":\"[{\\\"price\\\":\\\"20.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"Daily Auto Debit Until Nov 15 - No Trial\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"1727880846378401792\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
    "txnType": "SALE"
}

Initial Self-Managed Subscription

{
    "billingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"CO\"}",
    "merchantCustId": "1745215352000",
    "merchantNo": "800209",
    "merchantTxnId": "1745215352000",
    "merchantTxnTime": "2025-04-21 14:02:32",
    "merchantTxnTimeZone": "+08:00",
    "orderAmount": "20",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"CO\"}",
    "sign": "e5e70fc1b23a67655c03e12eb9f9cc8b059f8c4e9eb9745af4bc4966e41f3c80",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"1745215352000\",\"productName\":\"Self-managed-30days-Once daily\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2099-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}", 
    "txnOrderMsg": "{\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://www.merchant-store-website.com/\",\"products\":\"[{\\\"price\\\":\\\"20.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"Self-managed-30days-Once daily\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"1727880846378401792\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
    "txnType": "SALE"
}

Subscription Response Examples

After sending a subscription request, you will receive a response with important information for redirecting the customer to complete their payment.

Payment Redirect

If the request is successful, merchants need to extract the redirectUrl from the response parameters and redirect the user to that URL.

Response with Trial Period

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1853980684692361216",
        "merchantTxnId": "1730858419000",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null,
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=864c30107b6445459303bfae4f1514da", 
        "sign": "bd1290c1c8eb0a4cd482b82506c525999ff430c671cf7b83c8fb335a115b4347",
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxODUzOTgwNjg0NzU1Mjc1Nzc2LCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiMTczMDg1ODQxOTAwMCIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE4MzE5NDQ2OTEwMjcxNTI4OTYifQ=="
    }
}

Response without Trial Period

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1856171302189404160",
        "merchantTxnId": "1731380698000",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null, 
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=3defb10ddc42412290106d5b87705ae8&checkoutDetail=H4sIAAAAAAAAAL1WTW8cNRj%2BK9VcSTbj%2BfTsic0kESs1bZRNiwD14PF4dt147cH2ZLOKci5wBvWCFBAcWoQEB8QfQP0pDeVfYM%2FXzpYgUA89%2BvH7vvN%2BPO%2FjuXJQWU5zZ%2ByA2IshdGEQ%2BTEMXBAnnrPjLInEC8T1A%2BGMoet6bjLA0JIYx0lG2MDy7JK38XzgQzdKjJu7fX9Ga0fP9YJdAHaBdw%2BAsRuMQ%2FhPu08Ft7YfuHBch9EGXpcWmk3uHzbAZCkqruuIo84oraQkHK8N%2Bmh2YDBVZSdS5BXWnf%2Bj%2FVl6Ot23QTCSuYWnvDCFfnblUFMCCKAfeV7oeUkSRzDyYm9jaQIcT2Znh6fp5NSGL7dityATc3GC9MIgC61LNd7bKxFel2idUzQfZUxkIywkGa0oz8VKjTjRnYVnb%2Fe6z903kfbCIvRBiOMkxi6JIhwkwA%2ByCGQwQVkYotHTcj4opp3PIM3rnWFlvuuHoetDGPl%2BtFXZwXSWPnx8ePqe6oJ%2BUMDcxTDGHiSJS2IQRzmC2IsLU617d119kttVeVGcwCiIwhC%2BNa%2FH09nkPVXk5SBMiihDMMsLlPk4LyLXz8PQywtMgn%2BZVJ3g9ZMdZ0UyRbWFmMCILYTSxjqjjFE%2Bn%2BS5JEqZy9VqNdJEaZPZso3WEJhXjO04pCgI1vSCHFNeGTtn7Lv1bjyUOZHHat4ZtoGtr1wiTQV3xldOQaXqdvzVzasb2yXUIxgVf7y03Vw0Cwri2HWDxEuglQ2yRJQZFBltGK0Qn39orOQKrdtUS1MRYqnIrWsUJXFsQNQXNin16B6M7Spju9qyWeNmeBeU41p3zl%2FdkAWV1ojq9TaitCREdwXyapkR2Z1oTrg2Hg9a1AGeH4RRDOseS704QLb3jfHT8mjThw66j4bIdS0uCktadr3DwiSNsLZKCGAYgRj4rueHtj0uiDYql1ZK3ymXLUvbbr959tPrr17cfvmD777%2B8eXu7fPv3vzyzZ9fv9gF5ghuf%2F5%2B9%2FUXv95%2Be3P7%2FPe%2Fnv8WGX9JPq8MNRqWm7GTy5JK0lS2Ud7Qtoqw4vCS4Kq%2BAgYpamcjnp0cDLETQWutBRtGpmvMyITjheh7jC2UNrLcIFqck%2BZlsCJfT74djtC0oLjm3eF%2F8EZLitiRFMsThngf2YIHaK22gEOed2fTS9nSuiM8z1OzLd1Z2IXoXpEBtHlEOpDOKUdsNhj3TCNdqZ4JkuSmz1g%2FkqzzUq2FM6ufN6XQvC9eiUpikhoqcGILxwuCz0Wlm0esYUbPHwCTwA1A5Nbz1ZXk9Vd6xcoFVqNBw%2FZqUTDbwgbZGF5yZahpUq914EGvF0bKlmYz0u2N6zI6NiNjfYsLSlieCl7QebXdW1PtnKgtLWnnTFZpV93bXxzEObKRVf0I805qZP6RYDZXCzTcNk02V5%2BY0wViFWlolVNVMrSuL%2ByrMAhglv1dPC8u3sGrF9563f6v%2F5Nmn%2B5uhrlcGN3av0OpC8QUaa4%2F7t6NFjPDn3KrtMy2uYczQ4F2eFas6mM3EvsQTpcDhmZIkSiwr1q%2F24JtFv2CklX7y7cB0pp0%2B5pvgQ2vevT6%2Bm%2FzXE6DfQoAAA%3D%3D", 
        "sign": "10fc4e19ead644c8d36207388cc370e698613a58cef7933ac9def18469b40af5", 
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxODU2MTcxMzAyMzUyOTgyMDE2LCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiMTczMTM4MDY5ODAwMCIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ=="
    }
}

Response with Self-Managed Subscription

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1914198045307043842",
        "merchantTxnId": "1745215352000",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null,
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=e3257f9fa9f34fdc8a0d683fc6e2897e&checkoutDetail=H4sIAAAAAAAAAMVW247bNhD9lUCvXXslWdbFT%2FVqN%2BgC2WQRJy3aIg8UObLZ0KRKUvYaQb4lz%2F2OIv%2FVIXWxnO5DkZcCiwV05kLOzJlDfwpI09yzYBVEWZzleZgn6SLLkzDKiji4Cvag6Y5I%2B1oFqzwM47CYYGQPGLiuQEw83z3JPl%2ByjKPlYhmHYXhpf8d9YBzGy1mYzOLoRZSswni1iP%2Ft95uSzveHMF%2F5NBbhU%2BOgzfrVXQes96qV1mecD05lqzVIekL0%2FeYWMdNWj1qxltoh%2Fv3Npnx7f%2BOSUKKZg%2B9ljYX%2B%2FingWEKU5Is0jtOsyNMkXS7zLD57YoKf7zdrjG0uspbrt%2B40obbqkdgdIjtrG7O6vtZKYl0MDqoxjJPtvBKqmlOlYX7kkqmjmUuw1%2BoAGv83oInlSs6OUM0Mq56uh5NfYerrLKohITSvIaWwoFlSJXEEWV7HVZ6yOJ83cjupqx9Vf2NsRdkbTLCSrRCfry5KXsZxUWRpnsbflPyw3ry7e9vX%2BL8Untd1GIWLlBAGFJYFxKxmUYHsreo6yrPnC7%2B49zPlf7gK8DjDrXMWihKxU8aib8WF4HK7ZkyDQe%2FgeDzOLRiL99%2F353SkcXmuAqhroJYf4IHL1rr8i9Dz8Y1moB%2FMdnDsE7tYvfcFB6tPQc21Gfbq65evX1xDyYhQUv%2F9l2v8rluKKMvCMCniIneLA3vCBaIE93F%2BJHL7I3rpIzn1V22wIiJKxVxomhZZhiAZC1s3dv4iz9z6ULdOuludbs4HLqkf8htn5tbZ1h%2B%2FfoEd166jVgPYoTTZ7ivQwxdnIC1GvO7RIIoXyTLNct9dbXe3xHW9c%2F6jeXnuwAC9IlPksx%2BgoZo3Q9eowusSap3uIBWSqMjDZLmM0mxZhEl81pSyNfZZceqp3Pd5A6Ke7YkkW2CzRcjIyczeYANeMOzwCd01%2FNkiBzrm43zhqeEaukJQhIpiFkb45zqDqe6egLadCZHaB6My9XtzO8UeFfdCFp2pV56ogLWkOzW2lDqo7DSvQ6z6CJ3sOgXtRuwOk8rymlPPr7uOH32A5kS81Gr%2FKIi8AG%2Bx2gvgTrLhG9uke65%2BAzz4MwdqS%2BYWbPhWjvqDRk%2Bgs0T3ZeGItjDNtAdLsKvkHMa3XBKxmRBgY4ltRxnD0TAcBbXv9Vir6T2CjX9ejMG5jjbVagolnizBLQ%2FdAf2oWts9Ih1XRkYtwixMFnkSewrYVkt%2Fyih0TFEznyzdtRcIJI6Y3AaZKg2SFa%2FuNeH1qB0NOe1xV8rL7Rtu5PoixsnUHAQrlaz5tr0cCVa7BXOhK%2F1awrEcqvv2xEmely6z8Y%2BgHGRHs5%2BUcHd1QEd%2FbDKafsWvAxEtdMxj3DSCnLzBPSmTBLj%2B3xN5OHxH1CjCfiP%2Fa%2FyHbuWebwYad6hkN8%2Bodk2Egc78y%2FCG9BgO%2F1461RWuzSNcIQX64Tn58p%2FDSNz7eb%2BfMLQiBtLEvX3jnihx1oIDh2P%2Fk%2BsMlJ50N1ZegB2vRtQviyda5%2BM%2F1uzA6aC0%2FwDvkAvNHQoAAA%3D%3D", 
        "sign": "4b81b903d060b0773e734acb1b960b2886c9cc9330085817c447ac6b894e9cc5",
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": null
    }
}

Implementation Best Practices

1. Subscription Configuration:

   • Always use subProductType: 'SUBSCRIBE' for subscription operations
   • Choose selfExecute: 1 for managed or selfExecute: 2 for self-managed subscriptions
   • For recurring card payments, consider enabling bindCard: true for separate card tokenization

2. Data Storage:

   • Securely store both contractId and tokenId from successful subscription responses
   • For self-managed subscriptions, maintain your own billing schedule system
   • Save the subscriptionManageUrl to provide customers access to subscription management

3. Webhook Handling:

   • Process all subscription webhook notifications to track subscription status changes
   • When using bindCard: true, handle both binding and subscription webhooks
   • Implement idempotent webhook processing to handle potential duplicate notifications
   • Verify webhook signatures to ensure authentic notifications

4. 3DS Authentication Handling:

   • Properly implement 3DS redirect flow for initial subscription transactions
   • Store the transactionId before redirecting customers to the 3DS verification URL
   • Configure a valid returnUrl in your request to handle customer return after 3DS verification
   • Design your return page to handle both successful and failed 3DS verifications
   • Wait for webhook notifications to confirm the final transaction status

5. User Experience Considerations:

   • For Self-Managed Subscriptions:
     • develop a custom subscription management interface
     • Implement a custom email notification system for upcoming charges
     • Provide clear messaging about subscription terms and billing cycles
     • Design intuitive interfaces for customers to update payment methods or cancel subscriptions

6. Trial Periods:

   • Configure trials using either trialFromPlan or trialEnd parameters
   • Monitor trial expiration through webhook notifications
   • For managed subscriptions, the transition from trial to paid is automatic

7. Subscription Management:

   • For managed subscriptions, use the Subscription Billing API for plan updates
   • For self-managed subscriptions, track billing cycles and use the Subscription Billing API for renewals
   • Implement proper error handling and retry logic for failed renewal attempts