English

简体中文

English

简体中文

Theme

Direct Subscription ​

PCI Compliance Requirement

Direct subscription integration requires PCI DSS compliance as it involves handling sensitive card data directly. Merchants must:

  1. Maintain a valid PCI DSS certification
  2. Securely collect and transmit cardholder data
  3. Never store sensitive authentication data (e.g., CVV codes)
  4. Implement proper encryption and security measures

If you do not have PCI certification, please use the Checkout Subscription or SDK Subscription options instead.

API Request Parameters ​

Key Parameters for Subscription

When integrating subscription payments, you need to set these key parameters:

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

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

POST

Note

  • All JSON fields must be stringified before submission
  • Nested objects must be serialized to JSON string format
  • JSON fields must not contain unescaped special characters
  • Arrays in JSON should be properly formatted
  • Example of JSON string field:
json
{
    "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
    "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}
ParameterTypeLengthRequiredSignedDescription

billingInformation

String

/

Yes

Yes

Billing information in JSON string format. See

TransactionAddress

cardInfo

String

/

Conditional

Yes

Card payment information in JSON string format. See

TxnCardInfo

merchantNo

String

20

Yes

Yes

Merchant number assigned by Onerway, obtained from Onerway dashboard

merchantTxnId

String

64

Yes

Yes

Unique transaction identifier for each customer payment. Must be unique for each transaction request.

merchantTxnOriginalId

String

128

No

Yes

Master transaction ID generated by merchant. IDs can be duplicate but only one transaction with the same ID can succeed

merchantTxnTime

String

/

No

Yes

Transaction timestamp (Format: yyyy-MM-dd HH:mm:ss)

merchantTxnTimeZone

String

64

No

Yes

Transaction timezone

mpiInfo

String

/

Conditional

Yes

3DS verification result information in JSON string format. See

MpiInfo

orderAmount

String

19

Yes

Yes

Order amount in units of currency with max 2 decimal places

orderCurrency

String

8

Yes

Yes

Order currency code. See ISO 4217

productType

String

16

Yes

Yes

See

ProductTypeEnum

risk3dsStrategy

String

16

Conditional

Yes

3DS risk control strategy. See

Risk3dsStrategyEnum

shippingInformation

String

/

Yes

Yes

Shipping information in JSON string format. See

TransactionAddress

sign

String

/

Yes

No

Digital signature string for request verification. Please refer to Signature for signature generation method.

subProductType

String

16

Yes

Yes

See

SubProductTypeEnum

subscription

String

/

Conditional

Yes

Subscription configuration in JSON format including frequency, billing cycle, and subscription type (managed / self-managed).


txnOrderMsg

String

/

Yes

Yes

Transaction business information in JSON string format. See

TxnOrderMsg

txnType

String

16

Yes

Yes

Transaction type. See

TxnTypeEnum

TransactionAddress ​

NameTypeLengthRequiredSignatureDescription

firstName

String

64

No

No

First name


lastName

String

64

No

No

Last name


jpFirstName

String

64

No

No

(Japanese Katakana) First name


jpLastName

String

64

No

No

(Japanese Katakana) Last name


phone

String

32

No

No

Phone number



email

String

256

Yes

No

Email address



postalCode

String

32

No

No

Postal code



address

String

256

No

No

Address


country

String

64

Yes

No

Country. Please refer to ISO_3166.



province

String

64

Conditional

No

Province/State. Required when country is US or CA. Please refer to ISO_3166.



city

String

64

No

No

City


street

String

64

No

No

Street


number

String

64

No

No

House/Building number


identityNumber

String

64

No

No

ID number


birthDate

String

64

No

No

Birth date, format is yyyy-MM-dd



TxnCardInfo ​

NameTypeLengthRequiredDescription

holderName

String

48

Yes

Cardholder name



cardNumber

String

128

Yes

Card number



month

String

64

Yes

Expiry month



year

String

64

Yes

Expiry year



cvv

String

64

Yes

Card CVV



Subscription ​

Managed Subscription
Self-Managed Subscription
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:
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.


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

Managed Subscription Features

  • Automatic Billing: Onerway system automatically processes subsequent charges according to the subscription schedule, with no need for merchants to initiate future payments
  • Customer Email Notifications: After the initial subscription succeeds, the system sends a confirmation email to customers
  • Subscription Management: Customers can manage their subscriptions through links (subscriptionManageUrl) provided in emails
  • Self-Service Portal: Customers can view subscription history, update payment methods, and manage subscription status through the management interface
  • Simplified Integration: Merchants only need to handle the initial subscription while subsequent billing and management are handled by the Onerway platform

TxnOrderMsg ​

NameTypeLengthRequiredSignatureDescription

returnUrl

String

256

Yes

No

Synchronous return address. After the customer completes payment, the Onerway hosted page will redirect back to the merchant's specified page through this address



products

String

1024

Yes

No

List of product information purchased by the customer, please refer to the Products object



transactionIp

String

64

Conditional

No

Cardholder transaction IP



appId

String

20

Yes

No

Store ID. When a merchant registers a website/application with Onerway, a unique ID is generated for that website/application. This ID can be obtained from the Onerway dashboard.



javaEnabled

Boolean

/

Conditional

No

Whether the cardholder's browser has java enabled, retrieved via: window.navigator.javaEnabled()



colorDepth

String

64

Conditional

No

Cardholder screen color depth, retrieved via: window.screen.colorDepth



screenHeight

String

64

Conditional

No

Cardholder's screen resolution, retrieved via: window.screen.height



screenWidth

String

64

Conditional

No

Cardholder's screen resolution, retrieved via: window.screen.width



timeZoneOffset

String

64

Conditional

No

Cardholder browser's time zone, retrieved via: ((new Date()).getTimezoneOffset()).toString()



accept

String

2048

Conditional

No

Cardholder browser's Accept request header



userAgent

String

2048

Conditional

No

Cardholder's browser type, retrieved via: window.navigator.userAgent



contentLength

String

64

Conditional

No

Content length of the cardholder's browser content beyond the headers



language

String

64

Conditional

No

Cardholder's browser language, retrieved via: window.navigator.language



periodValue

String

/

Conditional

No

Installment payment period.



notifyUrl

String

256

Yes

No

Notification URL. See Notifications



Products ​

NameTypeLengthRequiredDescription

name

String

256

Yes

Product name

price

String

1024

Yes

Product unit price

num

String

20

Yes

Product quantity

desc

String

1024

No

Product description

currency

String

256

Yes

Currency code following ISO 4217 standard

type

String

256

No

Product classification. See

StoreProductTypeEnum

products must be in JSON string format

Examples:

If type is discount, the discount amount should be passed as a negative number
json
\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\"
json
\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"
json
\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"}]\"
json
\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"

Note that price * num (product amount) + price * num (discount amount) - price * num (shipping fee) = orderAmount (order transaction amount)

Response ​

NameTypeDescription

respCode

String

Response code from Onerway

respMsg

String

Response message from Onerway

data

Object

Response data. Refer to object

data


data ​

NameTypeDescription

transactionId

String

Transaction order number created by Onerway

responseTime

String

Interface response time


Format: yyyy-MM-dd HH:mm:ss

txnTime

String

Transaction completion time


Format: yyyy-MM-dd HH:mm:ss

txnTimeZone

String

Transaction time zone


Format: +/-HH:mm

orderAmount

String

Order amount

orderCurrency

String

Transaction order currency


Refer to ISO 4217 currency codes

txnAmount

String

Order amount after conversion to settlement currency

txnCurrency

String

Settlement currency


Refer to ISO 4217 currency codes

status

String

Transaction processing result


Refer to

TxnStatusEnum

redirectUrl

String

Redirection URL for 3D Secure verification

contractId

String

Subscription contract number

tokenId

String

Payment token

eci

String

Electronic Commerce Indicator

periodValue

String

Installment payment number of periods

codeForm

String

Code form for specific payment methods


See

CodeFormEnum

presentContext

String

Context information for presentation layer

actionType

String

Action type for the transaction


See

ActionTypeEnum

subscriptionManageUrl

String

Subscription management URL

sign

String

Signature string


Refer to the

Signature

interface

Direct Subscription Integration Process ​

The Direct Subscription integration process consists of three main phases as illustrated below:

1. Subscription Initiation ​

In this phase:

  • Customer enters payment and subscription information on the merchant's website/application (custom UI)
  • Merchant system securely collects and transmits the data to Onerway
  • The request includes sensitive card data in the cardInfo parameter and subscription details in the subscription parameter
  • The subProductType must be set to SUBSCRIBE
  • Merchant is responsible for designing a secure, user-friendly payment and subscription form

2. Subscription Processing and 3DS Verification ​

In this phase:

  • Onerway processes the subscription request and generates a contractId and tokenId
  • Important: 3DS verification is mandatory for all initial subscription transactions
  • Onerway returns status=R with a redirectUrl to the 3DS verification page
  • Merchant must redirect the customer to complete the 3DS verification
  • After verification, Onerway sends the final subscription result via webhook

3. Subscription Result Notification ​

In this phase:

  • Onerway sends detailed subscription result data to the notifyUrl via HTTP POST
  • For managed subscriptions with card tokenization, two webhook notifications are sent:
    1. A card binding notification with txnType=BIND_CARD
    2. A subscription notification with txnType=SALE and scenarios=SUBSCRIPTION_INITIAL
  • For self-managed subscriptions, only one notification is sent
  • 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 up to 3 times

Important Notes ​

  1. Mandatory 3DS: All initial subscription transactions require 3DS verification
  2. Webhook Monitoring: For managed subscriptions, expect two separate webhook notifications
  3. Contract and Token Storage: Both the contractId and tokenId must be stored securely
  4. Status Tracking: The subscriptionStatus field indicates the current subscription state
  5. Scenario Identification: The scenarios field indicates the type of subscription event
  6. Subscription Management: For managed subscriptions, use the subscriptionManageUrl to provide customer self-service

3DS Handling ​

3DS Authentication Flow ​

When the response contains status=R and actionType=RedirectURL, merchants must redirect the customer to complete 3DS verification:

json
{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919781070732402688", 
        "status": "R", // 3DS verification required
        "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919781076595769344", // 3DS verification URL
        "actionType": "RedirectURL", // Indicates a redirect is required
        // other fields...
    }
}

Upon receiving this response:

  1. Store the transactionId for tracking
  2. Redirect the customer to the redirectUrl for 3DS authentication
  3. Wait for the webhook notification with the final transaction result
  4. The customer will return to your site via the returnUrl specified in your request

Important

The returnUrl parameter in txnOrderMsg is critical for 3DS flows:

  • It must be a valid URL on your website that can handle returning customers
  • After 3DS verification completes, the customer's browser will be redirected to this URL
  • Transaction status parameters will be appended to the URL as query parameters
  • Your return page should be prepared to handle both successful and failed 3DS
    verifications

Best Practice

Implement a transaction status tracking mechanism to handle asynchronous payment completion after 3DS verification. Your returnUrl endpoint should:

  • Extract the transaction ID and status from the URL parameters
  • Show an appropriate message to the customer
  • Update the transaction status in your system when the webhook notification is received

Example 3DS Return URL ​

When a customer completes 3DS verification, they will be redirected to your returnUrl with parameters:

https://your-return-url.com/?transactionId=1919652057678479360&status=S&...

Your return page should handle this redirect appropriately.

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

Managed Subscription with Card Tokenization ​

json
{
    "billingInformation": "{\"address\":\"771 Reilly Pass\",\"city\":\"Edina\",\"country\":\"US\",\"email\":\"Judge.Mertz93@yahoo.com\",\"firstName\":\"Estel\",\"identityNumber\":\"13435106930\",\"lastName\":\"DuBuque\",\"phone\":\"14405058069\",\"postalCode\":\"14179\",\"province\":\"CO\"}",
    "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}", 
    "merchantCustId": "CustId-PD18-UHNS",
    "merchantNo": "800209",
    "merchantTxnId": "1c003dc2-6020-46d6-8c31-9a0abd89cdbd",
    "merchantTxnTime": "2025-05-06 23:29:17",
    "orderAmount": "69",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"1487 N Broadway\",\"city\":\"Stokeston\",\"country\":\"US\",\"email\":\"Judd_Crist@yahoo.com\",\"firstName\":\"Herbert\",\"identityNumber\":\"40078203228\",\"lastName\":\"Cronin\",\"phone\":\"13112674432\",\"postalCode\":\"75490\",\"province\":\"CO\"}",
    "sign": "f5ce8a0d2baec6cca3174926ec5cce24bda551ffa84fc6a9cb1f356b68c74409",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"selfExecute\":\"1\",\"productName\":\"Handcrafted Bronze Chicken\",\"frequencyType\":\"D\",\"bindCard\":true,\"merchantCustId\":\"CustId-677A-1W11\",\"frequencyPoint\":\"1\",\"notificationEmail\":\"Camren78@gmail.com\",\"metaData\":null,\"trialFromPlan\":\"0\",\"cycleCount\":21,\"trialEnd\":\"2025-05-10\"}", 
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"16\",\"contentLength\":\"0\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"banana\\\",\\\"num\\\":\\\"24\\\",\\\"price\\\":\\\"48.39\\\",\\\"type\\\":\\\"cillum consectetur ut ea nulla\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"currant\\\",\\\"num\\\":\\\"76\\\",\\\"price\\\":\\\"539.85\\\",\\\"type\\\":\\\"enim pariatur ex\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"896\",\"screenWidth\":\"3440\",\"timeZoneOffset\":\"-840\",\"transactionIp\":\"130.195.252.108\",\"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": "1919777240238137344",
        "responseTime": "2025-05-06 23:32:21",
        "txnTime": "2025-05-06 23:32:16",
        "txnTimeZone": "+08:00",
        "orderAmount": "0.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "R", 
        "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919777246483185664", 
        "contractId": null,
        "tokenId": "",
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": "RedirectURL", 
        "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5Nzc3MjQxMTA2MzU4MjcyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLTY3N0EtMVcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", 
        "sign": "4b17e0aff893578f3690a2c5b7dd96e9e82ca63047bc778bc2961277ce0ab930"
    }
}
json
{
    "notifyType": "TXN",
    "transactionId": "1919777298035646464", // Card binding transaction ID
    "txnType": "BIND_CARD", // Transaction type is BIND_CARD
    "merchantNo": "800209",
    "responseTime": "2025-05-06 23:32:30",
    "txnTime": "2025-05-06 23:32:30",
    "txnTimeZone": "+08:00",
    "orderAmount": "0.00",
    "orderCurrency": "USD",
    "status": "S",
    "tokenId": "46273d9b5d809e7bc82d86955789f2e8afb1b90ebc038b762ccd6b86fac4244d", // Generated tokenId
    "tokenExpireTime": "2099-12-31 23:59:59",
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "780ffb270d9d2808cee7e8fcffbf9fc320caa807a0d167a9f1f37c366c425d5e",
    "paymentMethod": "VISA",
    "channelRequestId": "8002091919777300153499651"
}
json
{
    "notifyType": "TXN",
    "transactionId": "1919777240238137344", // Subscription transaction ID
    "txnType": "SALE", // Transaction type is SALE
    "merchantNo": "800209",
    "merchantTxnId": "1c003dc2-6020-46d6-8c31-9a0abd89cdbd",
    "responseTime": "2025-05-06 23:32:29",
    "txnTime": "2025-05-06 23:32:17",
    "txnTimeZone": "+08:00",
    "orderAmount": "0.00",
    "orderCurrency": "USD",
    "status": "S",
    "contractId": "1919777241106358272", // Subscription contract ID
    "tokenId": "258463e5e5b359a23b2baeed71391fb75f4f45e19ebba6f645ba469a69f6de85", // Payment token for future charges
    "cardTokenId": "46273d9b5d809e7bc82d86955789f2e8afb1b90ebc038b762ccd6b86fac4244d",
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "568609ded09551a69193af19528d229a6a0398795cbd16b9789513443e924522",
    "paymentMethod": "VISA",
    "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5Nzc3MjQxMTA2MzU4MjcyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLTY3N0EtMVcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==",
    "subscriptionStatus": "trialing", // Current subscription status
    "dataStatus": "1",
    "products": "[{\"currency\":\"USD\",\"name\":\"banana\",\"num\":\"24\",\"price\":\"48.39\",\"type\":\"cillum consectetur ut ea nulla\"},{\"currency\":\"USD\",\"name\":\"currant\",\"num\":\"76\",\"price\":\"539.85\",\"type\":\"enim pariatur ex\"}]",
    "channelRequestId": "8002091919777246483185664",
    "scenarios": "SUBSCRIPTION_INITIAL" // Indicates initial subscription
}

Self-Managed Subscription ​

json
{
    "billingInformation": "{\"address\":\"90729 Bridge Road\",\"city\":\"South Gate\",\"country\":\"US\",\"email\":\"Stevie.Friesen90@gmail.com\",\"firstName\":\"Cordell\",\"identityNumber\":\"84698217949\",\"lastName\":\"Effertz\",\"phone\":\"13652765986\",\"postalCode\":\"74374\",\"province\":\"CO\"}",
    "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}", 
    "merchantCustId": "CustId-JK6B-8850",
    "merchantNo": "800209",
    "merchantTxnId": "f13aea15-2629-4a91-8c3d-9d1460ec0b33",
    "merchantTxnTime": "2025-05-06 23:47:05",
    "orderAmount": "2",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"37792 Main\",\"city\":\"West General\",\"country\":\"US\",\"email\":\"Noble59@hotmail.com\",\"firstName\":\"Herta\",\"identityNumber\":\"94700162716\",\"lastName\":\"Lemke\",\"phone\":\"18904565556\",\"postalCode\":\"08779-3653\",\"province\":\"CO\"}",
    "sign": "466befb92770e05377f46fd5a2d34a6dd63942fa45e805347b9f3bf294189551",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"selfExecute\":\"2\",\"productName\":\"Gorgeous Plastic Salad\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"merchantCustId\":\"CustId-PL20-S700\",\"expireDate\":\"2025-11-23\",\"metaData\":\"vary\"}", 
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"16384\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"feijoa\\\",\\\"num\\\":\\\"88\\\",\\\"price\\\":\\\"968.79\\\",\\\"type\\\":\\\"consectetur adipisicing reprehenderit sint\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"avocado\\\",\\\"num\\\":\\\"52\\\",\\\"price\\\":\\\"414.89\\\",\\\"type\\\":\\\"consectetur labore\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"1800\",\"screenWidth\":\"320\",\"timeZoneOffset\":\"360\",\"transactionIp\":\"201.9.255.1\",\"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": "1919781070732402688",
        "responseTime": "2025-05-06 23:47:33",
        "txnTime": "2025-05-06 23:47:29",
        "txnTimeZone": "+08:00",
        "orderAmount": "2.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "R", 
        "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919781076595769344", 
        "contractId": null,
        "tokenId": "",
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": "RedirectURL", 
        "subscriptionManageUrl": null, // No management URL for self-managed subscriptions
        "sign": "ee7f20c3d508572c5d6fd235414b6c535fc9089d9a43aebf6ce58176a1e358f3"
    }
}
json
{
    "notifyType": "TXN",
    "transactionId": "1919781070732402688",
    "txnType": "SALE",
    "merchantNo": "800209",
    "merchantTxnId": "f13aea15-2629-4a91-8c3d-9d1460ec0b33",
    "responseTime": "2025-05-06 23:47:43",
    "txnTime": "2025-05-06 23:47:30",
    "txnTimeZone": "+08:00",
    "orderAmount": "2.00",
    "orderCurrency": "USD",
    "status": "S",
    "contractId": "1919781071080529920", // Subscription contract ID
    "tokenId": "b05d9de9836fe3e0dce5ba42078885cb90c729fe0604219a9cf24c092e71eb60", // Payment token for future charges
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "efc6bac036b2b5478cec18240c613bc1dcad03520313ed059b5a4d4626cfb816",
    "paymentMethod": "VISA",
    "subscriptionStatus": "active", // Current subscription status
    "dataStatus": "1",
    "products": "[{\"currency\":\"USD\",\"name\":\"feijoa\",\"num\":\"88\",\"price\":\"968.79\",\"type\":\"consectetur adipisicing reprehenderit sint\"},{\"currency\":\"USD\",\"name\":\"avocado\",\"num\":\"52\",\"price\":\"414.89\",\"type\":\"consectetur labore\"}]",
    "metaData": "vary",
    "channelRequestId": "8002091919781076595769344",
    "scenarios": "SUBSCRIPTION_INITIAL" // Indicates initial subscription
}

Common Error Scenarios and Solutions ​

Subsequent Subscription Processing ​

In this phase:

  • Managed Subscription:

    • Onerway system automatically processes all subsequent charges according to the subscription plan
    • Customers receive email notifications for each charge
    • Customers can view subscription history and update payment methods through the subscriptionManageUrl
    • Merchants only need to handle webhook notifications without initiating charges

  • Self-Managed Subscription:

    • Merchants must track subscription cycles and actively initiate subsequent charges
    • Merchants must securely store contractId and tokenId for future billing operations
    • Subsequent charge requests require referencing the Subscription Billing documentation
    • Merchants need to implement their own subscription management interface for customers

Implementation Best Practices ​

  1. PCI Compliance: Maintain and regularly update your PCI DSS certification
  2. Secure Transmission: Always use TLS encryption and implement proper security measures
  3. 3DS Handling: Properly handle 3DS redirects and verify the final subscription status via webhook
  4. Webhook Verification: Always verify webhook signatures to prevent tampering
  5. Error Handling: Implement robust error handling and provide clear messages to customers
  6. Store Contract and Token: Securely store the contractId and tokenId for future subscription management
  7. Subscription Tracking: Maintain a subscription log for reconciliation and customer service
  8. Idempotency: Process webhook notifications idempotently to handle potential duplicates
  9. Duplicate Webhook Handling: Implement proper deduplication for multiple webhook notifications
  10. Subscription Type Selection: Choose the appropriate subscription type based on business requirements:
    • For low maintenance costs and customer self-service capabilities, select Managed Subscription
    • For complete control over billing processes and timing, select Self-Managed Subscription
  11. User Experience: For Self-Managed Subscriptions, provide a custom subscription management interface to allow customers to manage their payment methods and subscription status
  12. Email Notifications: For Self-Managed Subscriptions, implement a custom email notification system to alert customers about upcoming charges

Merchant Integration Checklist ​

Before going live with Direct Subscription integration, ensure you have:

  • Valid PCI DSS certification
  • Secure card data collection form
  • Proper error handling mechanisms
  • 3DS redirect handling implementation
  • Webhook handling and verification
  • Subscription tracking system
  • Contract and token secure storage
  • Thorough testing in sandbox environment