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	Transaction billing information in JSON string format. See TransactionAddress for complete structure.
cardInfo	String	/	No	Yes	Card payment information in JSON string format. See TxnCardInfoCheckout for complete structure.
lpmsInfo	String	/	Conditional	Yes	Local payment method information in JSON string format. See LpmsInfo for complete structure.
merchantCustId	String	50	Conditional	Yes	Unique customer identifier in merchant system.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
merchantTxnOriginalId	String	128	No	Yes	Master transaction ID generated by merchant for grouping related transactions.
merchantTxnTime	String	/	No	Yes	Transaction timestamp when the merchant initiated the transaction.
merchantTxnTimeZone	String	64	No	Yes	Transaction timezone offset for the merchant transaction time.
mpiInfo	String	/	Conditional	Yes	3DS verification result information in JSON string format. See MpiInfo for complete structure.
orderAmount	String	19	Yes	Yes	Transaction amount in the specified currency, formatted as a decimal string.
orderCurrency	String	8	Yes	Yes	Three-letter currency code according to ISO 4217 standard for the transaction amount.
productType	String	16	Yes	Yes	Payment method category for checkout display options. See ProductTypeEnum for all available options.
risk3dsStrategy	String	16	Conditional	Yes	3DS risk control strategy for fraud prevention. See Risk3dsStrategyEnum for available options.
shippingInformation	String	/	Yes	Yes	Transaction shipping information in JSON string format. See TransactionAddress for complete structure.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
subProductType	String	16	Yes	Yes	Specific implementation method within the selected product type, defining how the payment is processed. See SubProductTypeEnum for all available options.
subscription	String	/	Conditional	Yes	Subscription information in JSON string format. See Subscription for complete details.
txnOrderMsg	String	/	Yes	Yes	Transaction business information in JSON string format. See TxnOrderMsg for complete structure.
txnType	String	16	Yes	Yes	Transaction type that defines the payment operation to be performed. See TxnTypeEnum for all available options and detailed usage scenarios.

TransactionAddress

Name	Type	Length	Required	Signature	Description
firstName	String	64	No	No	Customer first name.
lastName	String	64	No	No	Customer last name.
jpFirstName	String	64	No	No	First name in Japanese Katakana.
jpLastName	String	64	No	No	Last name in Japanese Katakana.
phone	String	32	No	No	Customer phone number in international format.
email	String	256	Yes	No	Customer email address.
postalCode	String	32	No	No	Postal/ZIP code.
address	String	256	No	No	Full address in a single field.
country	String	64	Yes	No	Country in ISO 3166-1 alpha-2 format. See ISO 3166.
province	String	64	Conditional	No	Province/State code. Required when country is US or CA. See ISO 3166.
city	String	64	No	No	City name.
street	String	64	No	No	Street name.
number	String	64	No	No	House/Building number.
identityNumber	String	64	No	No	Government-issued ID number.
birthDate	String	64	No	No	Birth date in yyyy-MM-dd format.

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.
bankName	String	128	Conditional	No	Bank name. When lpmsType is EFT, please refer to EFTBankNameEnum for supported banks. 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: When productType is LPMS and lpmsType is ATM_CARD, provide the local bank account number. When productType is PAYMENT_CODE, provide the wallet payment code.
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.
iBan	String	64	Conditional	No	International Bank Account Number (IBAN). Required for transfers in regions that use IBAN for bank identification.
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).

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 payment completion, customer is redirected to this URL
products	String	1024	Yes	No	List of product information purchased by the customer See Products for complete structure.
transactionIp	String	64	Conditional	No	Cardholder transaction IP
appId	String	20	Yes	No	Store ID. Unique identifier generated when merchant registers with Onerway. Obtained from 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 Billing API
tokenId	String	Subscription payment token Returned after successful initial subscription, used in Subscription Billing API
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
  }
}