Onerway
POST

Create checkout payment

View as Markdown
Use this endpoint to create a checkout payment and obtain the redirectUrl for the Onerway-hosted payment page.

Request

Transaction billing information, including customer billing address and contact details.
Card payment information. Checkout currently supports only holderName; when provided, it pre-fills the cardholder name on the hosted checkout form.
Local payment method information. When used with productType=ALL, setting lpmsType limits checkout to the specified local payment method.
merchantCustIdstringoptional
Unique customer identifier in the merchant system.
Example:customer_12345
Constraints
Rule
For non-subscription checkout, provide it when you want the hosted checkout page to offer saved-payment-method options.
Consistency
For subscription checkout, use subscription.merchantCustId as the required subscription customer identifier; if top-level merchantCustId is submitted together with subscription.merchantCustId, the two values must match.
merchantNostringrequired
Merchant number assigned by Onerway. See Setup for how to obtain it.
Example:demo_merchant_no
Constraints
Rule
In the platform model, submit the merchant number of the sub-merchant the transaction is initiated for, not the platform merchant number. The sub-merchant must already be registered with Onerway.
merchantTxnIdstringrequired
Unique transaction identifier generated by the merchant system for tracking, reconciliation, and duplicate prevention.
merchantTxnTimestringoptional
Transaction timestamp when the merchant initiated the transaction, in yyyy-MM-dd HH:mm:ss format. If omitted, Onerway records the transaction time in UTC+8.
merchantTxnTimeZonestringoptional
Timezone offset for merchantTxnTime. If omitted, Onerway records the transaction time in UTC+8.
Example:+08:00
metaDatastringoptional
Custom data for this transaction, returned unchanged in transaction queries and asynchronous notifications.
Constraints
Rule
Must be a string containing valid JSON. When omitted, metaData is empty in queries and notifications.
Consistency
If both top-level metaData and subscription.metaData are submitted, subscription.metaData takes precedence.
orderAmountstringrequired
Transaction amount in the specified currency, formatted as a decimal string. For zero-decimal currencies, the amount must represent a whole amount; an all-zero decimal part is accepted, while non-zero decimals are rejected. Format rules follow currency and amount validation.
Example:99.99
orderCurrencystringrequired
Three-letter ISO 4217 transaction currency. Must match orderAmount.
Example:USD
osTypestringConditional
Condition: Required when paymentMode is APP or WAP.
Operating system type for mobile and app-based checkout transactions. Hosted checkout recommends WEB mode and usually does not require this field.
Example:IOS
Allowed values
IOS
iOS device.
ANDROID
Android device.
paymentModestringoptionaldefaultWEB
Payment mode indicating the platform or environment for the transaction. Checkout recommends the default WEB mode.
Example:WEB
Allowed values
WEB
Desktop browser payment.
APP
Native mobile app payment.
WAP
Mobile browser payment.
Payment method configuration options. Checkout supports the card and share objects.
productTypestringrequired
Payment method display scope for the hosted checkout. It controls which payment method categories the customer can choose from; the processing model is further determined by subProductType and txnType.
Example:ALL
Allowed values
ALL
Unified Checkout. Display all payment methods available for the merchant and transaction conditions; when lpmsInfo.lpmsType is also provided, display only the specified local payment method.
CARD
Card-only checkout. Display card payment methods only; support for authorization, subscriptions, installments, or saving payment information still depends on subProductType, txnType, and the merchant's enabled configuration.
Retailer information for marketplace transactions. Submit one entry for each retailer whose products are included in this order.
Since 2026-08-10New field for marketplace retailer information.
Constraints
Rule
Applies to marketplace and platform models where products are sold by third-party retailers rather than by the merchant directly. Merchants selling only their own inventory do not need to submit it.
Consistency
When submitted, every entry in txnOrderMsg.products must carry a retailerId that matches one of the retailers listed here.
risk3dsStrategystringoptionaldefaultDEFAULT
3DS risk strategy for checkout transactions.
Example:DEFAULT
Allowed values
DEFAULT
Default strategy. Onerway decides whether to trigger 3DS based on the transaction, merchant configuration, and risk controls.
INNER
Force Onerway-managed 3DS authentication.
NONE
Do not use 3DS authentication. Availability depends on merchant configuration and risk requirements.
Constraints
Unsupported
Checkout does not support EXTERNAL.
Rule
Contact Onerway before specifying a non-default strategy.
Transaction shipping information, including customer delivery address and contact details.
signstringrequired
Request signature string. See Request signing for how to generate it.
subProductTypestringrequired
Transaction processing mode under the selected payment method scope.
Example:DIRECT
Allowed values
DIRECT
Ordinary checkout payment. Execute a one-time debit or authorization according to txnType.
SUBSCRIBE
Initial subscription transaction. Used to create a subscription contract through checkout; subscription is required, and recurring billing, cancellation, and updates use the corresponding subscription APIs.
INSTALLMENT
Installment transaction. txnOrderMsg.periodValue must use a period value returned by the installment inquiry API.
Constraints
Consistency
Works with productType and txnType to define the transaction model.
Unsupported
Checkout does not support TOKEN.
Rule
For saved-payment-method scenarios, pass merchantCustId in non-subscription checkout flows or use subscription.bindCard in hosted card subscription flows.
Condition: Required when subProductType=SUBSCRIBE.
Subscription information for creating or initializing a subscription through Checkout. This endpoint is only for the initial subscription request; subsequent billing, cancellation, and updates use the corresponding subscription APIs. Use selfExecute=1 for Onerway-managed billing, or selfExecute=2 for merchant-managed billing.
Transaction business information, including returnUrl, notifyUrl, appId, and product details. Browser, device, and cardholder IP data are collected by the hosted checkout page and are not submitted by the merchant in this request.
txnTypestringrequired
Transaction operation type. It works together with productType and subProductType to define the transaction model and is also returned in transaction queries and asynchronous notifications.
Example:SALE
Allowed values
SALE
Debit-style transaction. Together with subProductType=DIRECT, SUBSCRIBE, or INSTALLMENT, it is used for ordinary payment, initial subscription, or installment payment.
AUTH
Authorization-style transaction. Funds are authorized first and not captured immediately. It is usually used for card payment scenarios that support authorization; availability depends on the selected productType, subProductType, and the merchant's enabled configuration.

Request example

curl -X POST 'https://sandbox-acq.onerway.com/txn/payment' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "billingInformation": "{\"country\":\"US\",\"email\":\"customer@test.com\",\"province\":\"CA\"}",
  "cardInfo": "{\"holderName\":\"Test Cardholder\"}",
  "merchantCustId": "custId_1784021156",
  "merchantNo": "replace_with_merchant_no",
  "merchantTxnId": "card-4f71d2ae-4d0b-4fc2-8f2c-e450cf735baf",
  "merchantTxnTime": "2025-08-21 10:17:31",
  "orderAmount": "1",
  "orderCurrency": "USD",
  "productType": "CARD",
  "shippingInformation": "{\"country\":\"US\",\"email\":\"customer@test.com\",\"province\":\"CA\"}",
  "sign": "4ee2d1398368a3cad281e97614fc134418922400f61a34c1fc1e81eca40002ba",
  "subProductType": "DIRECT",
  "txnOrderMsg": "{\"appId\":\"replace_with_app_id\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"test product\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"1\\\",\\\"type\\\":\\\"\\\"}]\",\"returnUrl\":\"https://developers.onerway.com/example-return\",\"notifyUrl\":\"https://developers.onerway.com/example-notify\"}",
  "txnType": "SALE"
}'

Response

respCodestring
Response code; 20000 means the request was processed successfully, other values are error codes. See Response codes.
respMsgstring
Human-readable message for the response code.
Business data object for the checkout session creation response.

Response example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "2076961389037359104",
    "merchantTxnId": "card-4f71d2ae-4d0b-4fc2-8f2c-e450cf735baf",
    "merchantNo": "replace_with_merchant_no",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "1.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "txnTimeZone": null,
    "status": "U",
    "paymentId": "2076961389016387584",
    "paymentStatus": "U",
    "reason": null,
    "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=bb02fff76ddf4ea9b021e4cd738e13e3",
    "sign": "3607ed6b158396e7a16574e2d62d5abb4b0157fa1e7321714438749488eb2f12",
    "contractId": "",
    "tokenId": null,
    "eci": null,
    "transactionOrderNo": null,
    "periodValue": null,
    "lpmsType": null,
    "qrCode": null,
    "subscriptionManageUrl": null,
    "tokenization": null,
    "linkName": null,
    "itemName": null
  }
}
No error responses are documented for this endpoint.

Refunds

Request a refund, handle refund results and request rejections, and query the outcome or cancel a request before approval.

Create direct transaction

Create a direct API transaction for card, wallet, saved-token, subscription, installment, or local payment method payments.