Direct Payment

PCI Compliance Requirement

Direct payment 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 or SDK Payment options instead.

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	/	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
osType	String	16	Conditional	Yes	Operating system type. See OsTypeEnum
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
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	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

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
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 Payment Integration Process

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

1. Payment Initiation

In this phase:

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

2. Payment Processing

In this phase:

• Onerway processes the payment request and determines if 3DS verification is required
• If 3DS is not required, Onerway returns the payment result immediately
• If 3DS is required:
  • 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 payment result via webhook

3. Payment Result Notification

In this phase:

• 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
• 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

3DS Handling

When implementing Direct Payment, merchants must handle 3DS authentication flows properly:

3DS Authentication Flow

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

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

Standard Payment Request (No 3DS)

Request

{
    "billingInformation": "{\"address\":\"78732 Manor Way\",\"city\":\"Carlsbad\",\"country\":\"US\",\"email\":\"Patience.Tremblay@yahoo.com\",\"firstName\":\"Jammie\",\"identityNumber\":\"66040505850\",\"lastName\":\"Walter\",\"phone\":\"13804962361\",\"postalCode\":\"80787-0866\",\"province\":\"CO\"}",
    "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}", 
    "merchantCustId": "CustId-DZJ4-P0KW",
    "merchantNo": "800209",
    "merchantTxnId": "2ce8fca1-f380-4c60-85ef-68a3a0c76ece",
    "merchantTxnTime": "2025-05-06 15:15:52",
    "orderAmount": "5",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"251 Clark Street\",\"city\":\"Elmhurst\",\"country\":\"US\",\"email\":\"Lilly_OKon43@gmail.com\",\"firstName\":\"Tyrell\",\"identityNumber\":\"07830885514\",\"lastName\":\"Hettinger\",\"phone\":\"15164105025\",\"postalCode\":\"25067-9128\",\"province\":\"CO\"}",
    "sign": "0284bc8fdc89ef5429017ddae286984f81fb18aa95c6e752c35ed910c3af9f96",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"0\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"banana\\\",\\\"num\\\":\\\"89\\\",\\\"price\\\":\\\"340.29\\\",\\\"type\\\":\\\"incididunt dolore Duis nostrud officia\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"watermelon\\\",\\\"num\\\":\\\"23\\\",\\\"price\\\":\\\"611.69\\\",\\\"type\\\":\\\"commodo Duis sint\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"berry\\\",\\\"num\\\":\\\"99\\\",\\\"price\\\":\\\"592.95\\\",\\\"type\\\":\\\"fugiat exercitation proident sunt ut\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"800\",\"screenWidth\":\"2048\",\"timeZoneOffset\":\"540\",\"transactionIp\":\"110.89.6.86\",\"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": "1919652333131005952",
        "responseTime": "2025-05-06 15:16:00",
        "txnTime": "2025-05-06 15:15:56",
        "txnTimeZone": "+08:00",
        "orderAmount": "5.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "S", // Immediate success, no 3DS required
        "redirectUrl": null,
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "e9607be76267352004f0e20065361f2fcd415bbb5121f002c104bdda11f68a4d"
    }
}

Webhook (notifyUrl)

{
    "notifyType": "TXN",
    "transactionId": "1919652333131005952", 
    "txnType": "SALE",
    "merchantNo": "800209",
    "merchantTxnId": "2ce8fca1-f380-4c60-85ef-68a3a0c76ece",
    "responseTime": "2025-05-06 15:16:00",
    "txnTime": "2025-05-06 15:15:56",
    "txnTimeZone": "+08:00",
    "orderAmount": "5.00",
    "orderCurrency": "USD",
    "status": "S", 
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "ff999833f72c5a5875af7fa797020cfb83f9ca1f7408b2a4c85c039f835e6c62",
    "paymentMethod": "VISA", 
    "channelRequestId": "8002091919652333131005952"
}

3DS Payment Request

Request

{
    "billingInformation": "{\"address\":\"78732 Manor Way\",\"city\":\"Carlsbad\",\"country\":\"US\",\"email\":\"Patience.Tremblay@yahoo.com\",\"firstName\":\"Jammie\",\"identityNumber\":\"66040505850\",\"lastName\":\"Walter\",\"phone\":\"13804962361\",\"postalCode\":\"80787-0866\",\"province\":\"CO\"}",
    "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}", 
    "merchantCustId": "CustId-DZJ4-P0KW",
    "merchantNo": "800209",
    "merchantTxnId": "6ef8a9c7-8d54-4b01-9acf-3582e70d9b1e",
    "merchantTxnTime": "2025-05-06 15:14:46",
    "orderAmount": "200", // Higher amount typically triggers 3DS
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"251 Clark Street\",\"city\":\"Elmhurst\",\"country\":\"US\",\"email\":\"Lilly_OKon43@gmail.com\",\"firstName\":\"Tyrell\",\"identityNumber\":\"07830885514\",\"lastName\":\"Hettinger\",\"phone\":\"15164105025\",\"postalCode\":\"25067-9128\",\"province\":\"CO\"}",
    "sign": "0284bc8fdc89ef5429017ddae286984f81fb18aa95c6e752c35ed910c3af9f96",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"0\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"banana\\\",\\\"num\\\":\\\"89\\\",\\\"price\\\":\\\"340.29\\\",\\\"type\\\":\\\"incididunt dolore Duis nostrud officia\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"watermelon\\\",\\\"num\\\":\\\"23\\\",\\\"price\\\":\\\"611.69\\\",\\\"type\\\":\\\"commodo Duis sint\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"berry\\\",\\\"num\\\":\\\"99\\\",\\\"price\\\":\\\"592.95\\\",\\\"type\\\":\\\"fugiat exercitation proident sunt ut\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"800\",\"screenWidth\":\"2048\",\"timeZoneOffset\":\"540\",\"transactionIp\":\"110.89.6.86\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "SALE"
}

Initial Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919652057678479360",
        "responseTime": "2025-05-06 15:14:53",
        "txnTime": "2025-05-06 15:14:50",
        "txnTimeZone": "+08:00",
        "orderAmount": "200.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "R", // 3DS verification required
        "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919652062199676929", // 3DS verification URL
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": "RedirectURL", // Indicates a redirect is required
        "subscriptionManageUrl": null,
        "sign": "7bad919d6fd128782626b2582873dc68417fc67df2fc45542164613fa7f472b2"
    }
}

Webhook After 3DS Completion

{
    "notifyType": "TXN",
    "transactionId": "1919652057678479360", 
    "txnType": "SALE",
    "merchantNo": "800209",
    "merchantTxnId": "6ef8a9c7-8d54-4b01-9acf-3582e70d9b1e",
    "responseTime": "2025-05-06 15:17:42",
    "txnTime": "2025-05-06 15:14:50",
    "txnTimeZone": "+08:00",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "status": "S", // Final status after 3DS verification
    "eci": "05", // ECI value indicates 3DS authentication result
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "8a73b542c9d2e8f6b70c49a3ef1d8c7654d6fb12e0385a17fb9ea427c85b3f9d",
    "paymentMethod": "VISA",
    "channelRequestId": "8002091919652062199676929"
}

Common Error Scenarios and Solutions

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 payment 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. Transaction Tracking: Maintain a transaction log for reconciliation and troubleshooting
7. Fraud Prevention: Implement proper fraud detection mechanisms and collect device fingerprinting data
8. Idempotency: Process webhook notifications idempotently to handle potential duplicates

Merchant Integration Checklist

Before going live with Direct Payment 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
• Transaction status tracking system
• Thorough testing in sandbox environment