The Onerway APIs are powerful and flexible if you know how to use them. This tour covers key information to help you understand the APIs more deeply:
Understanding these patterns helps you move beyond the pre-written code in Onerway tutorials. You can combine simple patterns in novel ways and plan for future growth.
Every transaction in Onerway is tracked using a unique transaction ID. Whether it's a payment, refund, or dispute, Onerway generates a transaction ID that follows the payment through its entire lifecycle.
Each checkout session has a 30-minute lifecycle, during which customers can complete their payment. After this window, the session expires and a new session must be created.
You can query transaction statusPayments API to check the current state of any transaction ID.
Onerway uses structured data objects to handle payment information. Each API request follows a clearly defined data structure to ensure accuracy, completeness, and security.
A payment request consists of multiple data objects, each responsible for transmitting specific types of information:
| Object | Purpose | Key Fields |
|---|---|---|
TxnOrderMsg | Order and merchant context | Return URL, notification URL, product list, customer platform, browser fingerprint data |
Products | Line items for the order | Product name, price, quantity, currency, type (physical/virtual/discount/shipping) |
TransactionAddress | Customer contact and location | Email (required), name, phone, postal code, full address, country (ISO 3166-1 alpha-2) |
| Object | Purpose | Key Fields |
|---|---|---|
CardInfo | Card payment credentials | Cardholder name, card number, expiration month/year, CVV security code |
TokenInfo | Saved payment methods | Token identifier for repeat payments without re-entering card details |
LpmsInfo | Local payment configuration | Payment method type (e.g., WeChat, Alipay), regional wallet settings |
| Object | Purpose | Key Fields |
|---|---|---|
mpiInfo | 3D Secure authentication | ECI (Electronic Commerce Indicator), CAVV, XID (v1) or dsTransID (v2) |
Subscription | Recurring billing setup | Billing cycle (frequency type/point), trial period (days/end date), expiration, notification email |
cardInfo is passed as a stringified JSON object, not a native object.Example structure:
{
"merchantNo": "800209",
"merchantTxnId": "txn-12345",
"orderAmount": "99.99",
"orderCurrency": "USD",
"productType": "CARD",
"subProductType": "DIRECT",
"txnType": "SALE",
"txnOrderMsg": "{\"returnUrl\":\"https://example.com/return\",\"notifyUrl\":\"https://example.com/webhook\",\"products\":\"[{...}]\"}",
"cardInfo": "{\"holderName\":\"John Doe\",\"cardNumber\":\"4111111111111111\",\"month\":\"12\",\"year\":\"25\",\"cvv\":\"123\"}",
"billingInformation": "{\"email\":\"customer@example.com\",\"country\":\"US\",...}",
"shippingInformation": "{\"email\":\"customer@example.com\",\"country\":\"US\",...}"
}
Regardless of how you integrate Onerway—through direct API calls, SDK integration, or hosted checkout—you need to organize and transmit information according to these predefined structures.
Onerway offers multiple integration options to meet different business needs. Each option balances user experience, development complexity, and brand presentation differently.
Redirect customers to an Onerway-hosted payment page. This option minimizes frontend development work and gets you up and running quickly.
How it works:
Best for: Businesses that want the fastest time to market with minimal development effort.
The following table compares the three integration options to help you choose the best fit for your business:
| Feature | Hosted Checkout | Embedded Checkout | Direct API |
|---|---|---|---|
| Setup complexity | Low | Medium | High |
| PCI compliance | Onerway handles | Onerway handles | You handle |
| UI customization | Limited | Moderate | Full control |
| Branding | Shows Onerway | Minimal Onerway | No Onerway branding |
| User experience | Redirect required | On-page | Fully customized |
| Time to integrate | Fastest | Moderate | Longest |
Each option has trade-offs between development time, customization, and compliance requirements. Choose based on your technical resources and business needs.