English

简体中文

English

简体中文

Theme

SDK Subscription ​

API Request Parameters ​

POST

Important Note

The key differences for creating subscription transactions through SDK integration:

  • Set subProductType: 'SUBSCRIBE' (instead of DIRECT or TOKEN)

  • Include the subscription parameter with subscription configuration details

Subscription Types ​

Onerway supports two subscription management modes:

Managed Subscription
Self-Managed Subscription

Managed Subscription (selfExecute: "1") is fully managed by Onerway:

  • Automatic recurring payments based on frequency settings
  • Customer notifications at key subscription events
  • Subscription management portal for end-users
  • Trial period support

Subscription Parameter Details ​

The subscription parameter is a JSON string containing the following fields:

Managed Subscription ​

Initial Subscription
Subscription Update
NameTypeLengthRequiredDescription

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. See

FrequencyTypeEnum

frequencyPoint

String

2

Conditional

Subscription cycle value for managed subscriptions.



cycleCount

int

256

Yes

Number of cycles, supports 1-99.


expireDate

String

10

Yes

Subscription termination date, format is yyyy-MM-dd. After this date, the managed system will no longer trigger billing.


mode

String

1

Conditional

Subscription authorization mode. See

SubscriptionModeEnum

selfExecute

String

1

Yes

Subscription billing mode. See

SubscriptionExecuteModeEnum

bindCard

String

300

No

Subscription credit card binding option. See

SubscriptionBindCardEnum

trialFromPlan

String

256

Conditional

Trial period billing mode. See

SubscriptionTrialModeEnum

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 ​

json
// 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\"}"
json
// 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\"}"
json
// 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\"}"
json
// 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\"}"
json
// 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
NameTypeLengthRequiredDescription

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: self-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

Subscription authorization mode. See

SubscriptionModeEnum

selfExecute

String

1

Yes

Subscription billing mode. See

SubscriptionExecuteModeEnum

Code Snippets ​

json
// 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\"}"
json
// 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\"}"
json
// 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\"}"
json
// 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\"}"

SDK Integration Process ​

The integration process for SDK subscription follows the same three phases as standard Payment Intent Creation:

  1. Subscription Intent Creation: Create a subscription intent on your server with subProductType: 'SUBSCRIBE' and subscription parameters
  2. SDK Payment Process: Initialize the SDK with the received transactionId and redirectUrl
  3. Subscription Result Notification: Process the subscription result and relevant notifications

Important Note

When using SUBSCRIBE with bindCard: true, the system creates two transactions:

  1. A card binding transaction that generates a tokenId
  2. An actual subscription transaction using the same transactionId that was used to initialize the SDK

As a result, you will receive two separate webhook notifications:

  • One for the card binding result with txnType: "BIND_CARD"
  • Another for the subscription payment result with txnType: "SALE"

API Usage Examples ​

json
{
  "billingInformation": "{\"address\":\"8016 Breitenberg Forks\",\"city\":\"West Emelie\",\"country\":\"US\",\"email\":\"Kendra61@hotmail.com\",\"firstName\":\"Jillian\",\"identityNumber\":\"97386542147\",\"lastName\":\"Moore\",\"phone\":\"16656382461\",\"postalCode\":\"42189\",\"province\":\"CO\"}",
  "merchantCustId": "CustId-T4DJ-E3JJ",
  "merchantNo": "800209",
  "merchantTxnId": "89ae7689-184b-40d3-a3a5-d6b3eb921ddb",
  "merchantTxnTime": "2025-05-05 15:42:05",
  "orderAmount": "5",
  "orderCurrency": "USD",
  "productType": "CARD",
  "shippingInformation": "{\"address\":\"540 King's Road\",\"city\":\"East Maziestad\",\"country\":\"US\",\"email\":\"Caitlyn_Graham63@hotmail.com\",\"firstName\":\"Julianne\",\"identityNumber\":\"35516907344\",\"lastName\":\"Hackett\",\"phone\":\"13290664062\",\"postalCode\":\"22307-4261\",\"province\":\"CO\"}",
  "sign": "f00aecf28e9a58c6d3c1b106a3b5ea4d33690468f851657c08089f4453c0d790",
  "subProductType": "SUBSCRIBE", // Set to SUBSCRIBE for subscription
  "subscription": "{\"requestType\":\"0\",\"selfExecute\":\"1\",\"productName\":\"Fantastic Cotton Soap\",\"frequencyType\":\"W\",\"bindCard\":true,\"merchantCustId\":\"CustId-J340-UE29\",\"frequencyPoint\":\"31\",\"notificationEmail\":\"Adam62@hotmail.com\",\"metaData\":null,\"trialFromPlan\":\"0\",\"cycleCount\":54,\"trialDays\":213}", // Subscription configuration
  "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"32\",\"contentLength\":\"16384\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"kiwi fruit\\\",\\\"num\\\":\\\"4\\\",\\\"price\\\":\\\"377.09\\\",\\\"type\\\":\\\"labore incididunt nulla in adipisicing\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"pear\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"952.38\\\",\\\"type\\\":\\\"cupidatat\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"932\",\"screenWidth\":\"320\",\"timeZoneOffset\":\"-720\",\"transactionIp\":\"71.26.248.147\",\"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"
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919296539923447808", // Use for SDK initialization
    "responseTime": "2025-05-05 15:42:08",
    "txnTime": null,
    "txnTimeZone": "+08:00",
    "orderAmount": "5.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "U",
    "redirectUrl": "https://sandbox-checkout-sdk.onerway.com", // Use for SDK initialization
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5Mjk2NTQxMDgxMDc1NzEyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUozNDAtVUUyOSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", // Subscription management URL
    "sign": "5e77e177056c26cbd53aa75f094d76f014366b25ef652e5e57c9f321c4ce793b"
  }
}

SDK Initialization ​

Specific Configuration Options for Subscription ​

While most configuration options are the same as for standard payment intent creation, these options are particularly relevant for subscription:

javascript
config: {
  subProductType: 'SUBSCRIBE', // Required for subscription
}

After creating a subscription intent via API, initialize the SDK with the transactionId and redirectUrl:

javascript
// Import the Onerway SDK script
const script = document.createElement('script')
script.src = 'https://checkout-sdk.onerway.com/v3/'
document.body.appendChild(script)

// Create SDK container
const container = document.createElement('div')
container.id = 'onerway_checkout'
document.body.appendChild(container)

// Initialize SDK once loaded
script.onload = function () {
  const pacypay = new Pacypay(transactionId, {
    container: 'onerway_checkout',
    locale: 'en',
    environment: 'sandbox',
    mode: 'CARD',
    redirectUrl: 'REDIRECT_URL_FROM_API',
    config: {
      subProductType: 'SUBSCRIBE'
      // Additional standard configuration options
    },
    onPaymentCompleted: function (result) {
      // Handle subscription completion
      const subscriptionResult = result.data

      if (result.respCode === '20000') {
        // Process successful response
        if (subscriptionResult.status === 'S') {
          // Subscription successful
          console.log('Subscription successful')
        } else if (subscriptionResult.status === 'R') {
          // 3DS verification required
          console.log('3DS verification required')
          window.location.href = subscriptionResult.redirectUrl
        }

        // For managed subscription, store or present the subscription management URL to the customer
      } else {
        console.error('Subscription failed:', result.respMsg)
      }
    },
    onError: function (error) {
      console.error('SDK error:', error)
    }
  })
}

SDK Callback Responses ​

After the customer completes the subscription form, the SDK will return a callback with the subscription result:

json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919297495302012928",
    "responseTime": "2025-05-05 15:47:10",
    "txnTime": "2025-05-05 15:45:56",
    "txnTimeZone": "+08:00",
    "orderAmount": "300.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919297799061635073",
    "contractId": null,
    "tokenId": "",
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL",
    "subscriptionManageUrl": null,
    "sign": null
  }
}

Webhook Notifications ​

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

For subscription with bindCard: true, you will receive two separate webhook notifications:

json
{
  "notifyType": "TXN",
  "transactionId": "1919297867005427712", // Card binding transaction ID
  "txnType": "BIND_CARD", // Transaction type is BIND_CARD
  "merchantNo": "800209",
  "responseTime": "2025-05-05 15:47:26",
  "txnTime": "2025-05-05 15:47:24",
  "txnTimeZone": "+08:00",
  "orderAmount": "0.00",
  "orderCurrency": "USD",
  "status": "S",
  "tokenId": "d057f8e7c1f887a78de8849b30224a95af11ce8c5e7b4b24d4abb471af77d845", // Token for future charges
  "tokenExpireTime": "2099-12-31 23:59:59",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "3aac4034f2244330f64d07dd9a9a13fdf66d04883a94191144df4ce439be67b9",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091919297871069446145"
}
json
{
  "notifyType": "TXN",
  "transactionId": "1919297867005427712",
  "txnType": "SALE", // Transaction type is SALE
  "merchantNo": "800209",
  "responseTime": "2025-05-05 15:47:26",
  "txnTime": "2025-05-05 15:47:24",
  "txnTimeZone": "+08:00",
  "orderAmount": "5.00", // Actual subscription amount
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919297867047370752", // Subscription contract ID
  "tokenId": "d057f8e7c1f887a78de8849b30224a95af11ce8c5e7b4b24d4abb471af77d845", // Token for future charges
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "3aac4034f2244330f64d07dd9a9a13fdf66d04883a94191144df4ce439be67b9",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5Mjk3ODY3MDQ3MzcwNzUyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUozNDAtVUUyOSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", // Management URL
  "subscriptionStatus": "active", // Subscription status
  "scenarios": "SUBSCRIPTION_INITIAL", // Subscription scenario
  "channelRequestId": "8002091919297871069446145"
}

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.

Subscription Lifecycle Management ​

Managed Subscription
Self-Managed Subscription

For managed subscriptions:

  • Onerway automatically handles all recurring billing based on the defined schedule
  • Use the Subscription Billing API for subscription update/downgrade
  • Customers can manage their subscription through the subscriptionManageUrl
  • Subscription lifecycle events (trials, renewals, expirations) are handled automatically
  • Webhook notifications are sent for each billing event and status change

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