Checkout

API Request Parameters

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:

{
    "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
    "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
billingInformation	String	/	Yes	Yes	Billing information in JSON string format. See TransactionAddress
cardInfo	String	/	No	Yes	Card payment information in JSON string format. If holderName is provided in advance, customers can skip entering cardholder name at checkout. See TxnCardInfoCheckout
lpmsInfo	String	/	Conditional	Yes	Local payment method information in JSON string format. See LpmsInfo
merchantCustId	String	50	Conditional	Yes	Unique customer identifier in merchant system.
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	ALL - display all available payment methods in the checkout page. CARD - credit card payments only. For more details, see ProductTypeEnum .
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 information in JSON string format. See Subscription.
txnOrderMsg	String	/	Yes	Yes	Transaction business information in JSON string format. See TxnOrderMsg
txnType	String	16	Yes	Yes	Transaction type. See TxnTypeEnum

TransactionAddress

Name	Type	Length	Required	Signature	Description
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

Name	Type	Length	Required	Description
holderName	String	48	No	Cardholder name

LpmsInfo

Name	Type	Length	Required	Signature	Description
lpmsType	String	64	Yes	No	Local payment method type. Please refer to LpmsTypeEnum for all supported payment methods. Each LPMS type has different integration requirements and processing timeframes.
bankName	String	128	Conditional	No	Bank name. When lpmsType is EFT, please refer to EFTBankNameEnum for supported banks and their exact identifiers. When lpmsType is Przelewy24, please refer to Przelewy24BankNameEnum for valid Polish bank options.
walletAccountId	String	/	Conditional	No	Wallet/local account identifier. Required in these scenarios: 1. When productType is LPMS and lpmsType is ATM_CARD, provide the local bank account number (without spaces or special characters). 2. When productType is PAYMENT_CODE, provide the wallet payment code (typically 18-24 digits).
walletAccountName	String	/	Conditional	No	Wallet/local account name. Required when productType is LPMS and lpmsType is ATM_CARD, provide the local bank account holder name as it appears on official documents. Name mismatches are a common cause of transaction failure.
iBan	String	64	Conditional	No	International Bank Account Number (IBAN). Required for transfers in regions that use IBAN for bank identification, particularly in Europe and the Middle East. IBAN validation is strict and format errors will cause immediate transaction rejection.
prepaidNumber	String	/	Conditional	No	Prepaid card or voucher number. Required for certain Japanese payment methods like BitCash (16 digits), Net_Cash (16 digits), and WebMoney (19 digits). Submit the number exactly as it appears on the card/voucher, including any hyphens if present.

MpiInfo

Name	Type	Length	Required	Signature	Description
eci	String	2	Yes	No	Electronic Commerce Indicator (ECI).
cavv	String	128	Yes	No	Cardholder Authentication Verification Value (CAVV).
xid	String	128	No	No	3D-Secure v1 transaction identifier.
dsTransID	String	128	No	No	3D-Secure v2 transaction identifier.

TxnOrderMsg

Name	Type	Length	Required	Signature	Description
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

Name	Type	Length	Required	Description
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

General case

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\"

With discount

\"[{\\\"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\\\"}]\"

With shipping fee

\"[{\\\"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\\\"}]\"

With discount and shipping fee

\"[{\\\"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

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

Name	Type	Description
transactionId	String	Transaction order number created by Onerway
merchantTxnId	String	Merchant's payment order number
merchantNo	String	Merchant number assigned 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
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
txnTimeZone	String	Transaction time zone
status	String	Transaction processing result Refer to TxnStatusEnum
reason	String	Reason for transaction failure
redirectUrl	String	Checkout page URL
sign	String	Signature string Refer to the Signature interface
contractId	String	Subscription contract number Returned after successful initial subscription, used in Subscription Repurchase
tokenId	String	Subscription payment token Returned after successful initial subscription, used in Subscription Repurchase
eci	String	Electronic Commerce Indicator
periodValue	String	Installment payment number of periods
lpmsType	String	Local payment method Refer to object LpmsInfo
qrCode	String	QR code value
subscriptionManageUrl	String	Subscription management URL
subscriptionsManageUrl	String	Subscription list management URL

Checkout Integration Process

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

1. Payment Initiation

In this phase:

• Merchant system sends a payment request to with transaction details including merchantNo, orderAmount, and txnOrderMsg parameters
• txnOrderMsg must contain returnUrl (for synchronous notification) and notifyUrl (for webhook notification)
• Onerway creates a transaction record and returns a redirectUrl to the hosted checkout page
• The initial transaction 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 standard payment is used, the process completes directly
• If 3D Secure (3DS) verification is required (for enhanced security with credit card payments), the customer is redirected to complete verification before proceeding

3. Payment Result Notification

In this phase:

• Synchronized notification:

  • Customer is redirected back to the merchant's website through the returnUrl provided in the initial request, with transaction result parameters appended to the URL
  • The synchronized notification provides essential result parameters including transactionId, status

• Asynchronous notification (webhook):

  • Simultaneously, Onerway sends detailed payment result data to the notifyUrl via HTTP POST
  • The webhook contains complete transaction information including transactionId, status, paymentMethod, and signature for verification
  • Webhook data is more comprehensive than the synchronized notification and should be used as the source of truth

• Webhook acknowledgment:

  • 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 at 30-minute intervals
  • Implement idempotent processing to handle potential duplicate notifications

Payment Completion Examples

Synchronized Return (returnUrl)

https://docs.onerway.com/?transactionId=1913122304280625152&merchantTxnId=e868e769-afe5-41f7-9882-04835122e0b3&merchantNo=800209&responseTime=2025-04-18%2014:51:33&txnTime=2025-04-18%2014:47:56&txnTimeZone=+08:00&orderAmount=3.00&orderCurrency=USD&status=F&reason=Unknown%20decline

Webhook (notifyUrl)

{
    "notifyType": "TXN",
    "transactionId": "1913122304280625152", 
    "txnType": "SALE",
    "merchantNo": "800209",
    "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
    "responseTime": "2025-04-18 14:51:33",
    "txnTime": "2025-04-18 14:47:56",
    "txnTimeZone": "+08:00",
    "orderAmount": "3.00",
    "orderCurrency": "USD",
    "status": "F", 
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"70002\",\"respMsg\":\"Unknown decline\"}",
    "sign": "ff999833f72c5a5875af7fa797020cfb83f9ca1f7408b2a4c85c039f835e6c62",
    "paymentMethod": "VISA", 
    "channelRequestId": "8002091913123207012028416"
}

Important Notes

• Always rely on webhook notifications as the definitive source for transaction status
• Synchronized return (via returnUrl) is primarily for user experience and should not be the sole basis for order processing
• Multiple webhook notifications may be received for a single transaction; 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

Request

{
    "billingInformation": "{\"address\":\"71969 Cormier Mountain\",\"city\":\"Yakima\",\"country\":\"US\",\"email\":\"Watson91@gmail.com\",\"firstName\":\"Lyric\",\"identityNumber\":\"16491844146\",\"lastName\":\"Morissette\",\"phone\":\"14848980027\",\"postalCode\":\"83406\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-1F6O-9KB6",
    "merchantNo": "800209",
    "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
    "merchantTxnTime": "2025-04-18 14:47:42",
    "orderAmount": "3",
    "orderCurrency": "USD",
    "productType": "CARD", // varies with the checkout type
    "shippingInformation": "{\"address\":\"791 The Grange\",\"city\":\"North Mya\",\"country\":\"US\",\"email\":\"Ellsworth.Pollich56@gmail.com\",\"firstName\":\"Melissa\",\"identityNumber\":\"40577724690\",\"lastName\":\"Yost-Wyman\",\"phone\":\"18769881007\",\"postalCode\":\"36102\",\"province\":\"CO\"}",
    "sign": "51a9b65b46e65cae3e4901213a4f978782b2a9984bdc9210588df6bd6f7d5fd4",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"32\",\"contentLength\":\"4096\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"dried apricot\\\",\\\"num\\\":\\\"60\\\",\\\"price\\\":\\\"891.19\\\",\\\"type\\\":\\\"anim veniam Lorem dolor\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"rockmelon\\\",\\\"num\\\":\\\"34\\\",\\\"price\\\":\\\"520.09\\\",\\\"type\\\":\\\"ipsum et minim\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"apricot\\\",\\\"num\\\":\\\"59\\\",\\\"price\\\":\\\"461.33\\\",\\\"type\\\":\\\"in consectetur veniam sunt qui\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"896\",\"screenWidth\":\"360\",\"timeZoneOffset\":\"-600\",\"transactionIp\":\"74.7.247.123\",\"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"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1913122304280625152",
        "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "3.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null,
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=fdd9116b821346379b8f1127f55d85df&checkoutDetail=H4sIAAAAAAAAAMVWTW%2FbOBD9K4XOsUNSEkXltK6SYg0kaRGnLXYXPVAkZbOVKS1J2Q2K%2FvcO9eHaXaPd7aF7MaTHmdG8mTdDf4p42y5ldBXhjGSMIZbQOGMJwllOootoq6zYcOPvm%2BiKIURQfoTxrQLHRanqI8vHj6aPpxhlKqP5jFcqnSW4ymY5Y2SGEhanmBCFyvjU7VH38QgiKVjNMHuGk6sku0rJP%2B3%2BbAzYmq6uLyIP0FMbXFeL25uoBxbbpjMeoHiO0AAVnbXKiCcAX6%2BuAXNd%2Bco2shN%2BdL9ePtwUj3AiuJUBW5oKeP%2F1KdLACEPilBCa5YwmNE1ZRr5agveb5WoBvu1JyGLxED5VN%2BvmFfcbQDbet%2B7q8tI2BvhItWtaJzVfz8u6KeeisWq%2B10Y2ezc3yl82O2Xht1WWe92Y2V6VMyfLj5fTl28h9GWGK5VwwSpFhYpFlpQJwSpjFSkZlYTNW7M%2B4jV2bswY6lCMB26o6eeLE8opIXmeUUbJN5TvFqvHm4eR4%2F9CnFUVwiimnEslVJorIiuJcxBzWVWYZeeJn%2BT9XfoJylOUxzHN4IHk9IT%2B4uY%2F0G65eGr503cYjxYknJ6yTEoUS4oUU1zGieAkFmVV4pITKTDP0%2FMs%2B%2FR%2B1NwYxWmKYsYokDxhd71cFS%2Ff3Dz8Io4sTiomkWCZIEzlSGU4o5IzQbJKZDmav2%2FPcDxK8kd9hJ%2BYYZbmsMXYN0zvbx5Wxe3r57%2BIK0oILWlGcUkYwhjBXJVUcUErqUJLz%2FfzJM0zbN9dRDAkTvtgXDeC15vGebAtdV1rs15IaZUD62i%2F38%2B9ch5y3o7fGVbdsFBVVSnh9U7dadP5ED9G%2FQp9aaWyd249GY6Bg6%2Fd9mMaXX2KKm3ddDncPlktQgH5AbprrHZOeUgTqr3pF3kUWsTycMNkgKot1zWgb7l3jcnxb%2BsAjNm2QIrXRSODH6gGUQD5gVuGc5o%2FKyAhreyzu3ANcG0Cy%2FBoh%2FU%2F9Hmnjeib%2FDIcax%2FO%2FuAf9JaHAnurlJ%2BYmm5bKju9aamMB%2Fv7EY0wTXLMkgQntK%2B39Ztr7g831Pv2xdeaTNAtP0Y%2B9y11wup2qONgZpXUFprx2tYTBOx9F5iu%2BmvROb4%2BRHVNZ4UqYL8aFQooNkp8aDo%2F3IDDPZ%2FjGK7fGDTIECUp7q9Xq3xnTf%2BVg8JlI9wc2mP3%2FCnU%2FrKXCpSsPsrGW24cFyHnXh33BxWB9LdQpuK07FNGd9C%2F2k22lVa1LBpT6XVn%2BXEBgO1auROFjR1R%2B2Ji9%2B0Xj%2BK8CJFdf4mbQX9B7b83dcg1AIH73x0UOTQf3na87sIzPErt2pr3qojCLjkKAJ3%2FGc%2Fd7ie8DuPYS%2Brf%2Br8bxvN8MeBwAyJ%2BfmZ%2BK147NRy%2FnbbJiEHzlyYMXx3KfIBLkMDYvDD%2B%2FevUkrA4l9sjhZbcKZqELTghoqmbw2TttNqP%2FyC%2FAkUvuufenICDrg7o517EQWjT5MDLQu60mCbsCy5e7SbsCgAA",  // redirects to the checkout page
        "sign": "c12a5e36e5e1fa1e0c01fea79ecfb741c3a61122509e4092b2676820088ad253",
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": null
    }
}