Onerway
POST

Create direct transaction

View as Markdown
Use this endpoint to create a server-to-server direct API transaction for card, wallet, saved-token, subscription, installment, or local payment method payments.

Request

Condition: Required except for later subscription billing or update (subscription.requestType=1 or 2).
Transaction billing information, including customer billing address and contact details.
Condition:
  • Required for direct card payments with merchant-collected card details.
  • Required for merchant-decrypted Apple Pay / Google Pay wallet payments.
  • Required for card token payments (subProductType=TOKEN); submit cardInfo.cvv together with tokenInfo.
  • Required for Onerway-decrypted Google Pay PAN_ONLY payments when you collect the CVC yourself; cardInfo must contain only cvv and be submitted together with tokenInfo.
Card payment information. Merchants that collect card details themselves, including cardInfo.cvv for card token payments, must be PCI DSS compliant. For wallet payments, submit either merchant-decrypted card data in cardInfo or the encrypted token in tokenInfo for Onerway decryption; the two are combined only when a Google Pay PAN_ONLY token needs the CVC, in which case cardInfo carries cvv only.
Constraints
Rule
For merchant-decrypted Google Pay payments, configure allowedAuthMethods according to the Onerway requirement documented under tokenInfo.
merchantCustIdstringConditional
Condition: Required for card token payments (subProductType=TOKEN) and subscription scenarios.
Unique customer identifier in the merchant system. For subscriptions, subscription.merchantCustId is the subscription customer identifier; if this top-level field is also submitted, it must match.
Example:customer_12345
merchantNostringrequired
Merchant number assigned by Onerway. See Setup for how to obtain it.
Example:800209
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. Must be a string containing valid JSON. Returned unchanged in transaction queries and asynchronous notifications; when omitted, metaData is empty there.
Condition: Required when risk3dsStrategy=EXTERNAL.
External 3DS / MPI authentication result. Direct API integrations may complete 3DS through their own MPI or 3DS Server and pass the result through unchanged.
Condition: Required when productType=LPMS.
Local payment method information containing configuration parameters for the selected local payment method.
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 not WEB.
Operating system type for mobile and app transactions.
Example:IOS
Allowed values
IOS
iOS device.
ANDROID
Android device.
paymentModestringoptionaldefaultWEB
Payment mode indicating the transaction platform or environment. Defaults to WEB.
Example:WEB
Allowed values
WEB
Desktop browser payment.
APP
Native mobile app payment.
WAP
Mobile browser payment.
Payment method configuration options. Direct API transactions support the card and share objects.
productTypestringrequired
Payment method scope. Direct API calls must explicitly choose CARD or LPMS; ALL is not supported because aggregated payment-method display is a Checkout concept.
Example:CARD
Allowed values
CARD
Card payment scope, including direct card payments with merchant-collected card details and Apple Pay / Google Pay wallet payments.
LPMS
Local payment method scope. lpmsInfo is required when this value is used.
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. Direct API supports DEFAULT, INNER, NONE, and EXTERNAL; when using EXTERNAL, submit mpiInfo with the external authentication result. Contact Onerway before specifying a non-default strategy.
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.
Condition: Required except for later subscription billing or update (subscription.requestType=1 or 2).
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. It works with productType and txnType to define the transaction model.
Example:DIRECT
Allowed values
DIRECT
Ordinary direct API payment. Execute a one-time debit, wallet payment, local payment method payment, or authorization according to productType and txnType.
TOKEN
Card token payment. Use a saved card token with the customer identifier and always submit cardInfo.cvv.
SUBSCRIBE
Subscription transaction. Supports initial subscription, later merchant-triggered billing, and managed subscription update through subscription.requestType.
Condition: Required when subProductType=SUBSCRIBE.
Subscription information. This direct API endpoint supports initial subscription (requestType=0), later merchant-triggered billing (requestType=1), and managed subscription update (requestType=2).
Condition:
  • Required for Onerway-decrypted Apple Pay / Google Pay wallet payments.
  • Required for card token payments (subProductType=TOKEN).
Token credential used to initiate the payment. For wallet payments, submit the encrypted wallet token returned by the wallet SDK for Onerway decryption. For card token payments, submit the card token returned by card tokenization or the saved payment method flow; subscription tokens are submitted through subscription.tokenId, not here.
Constraints
Rule
Onerway requires allowedAuthMethods in the Google Pay CARD payment method parameters to include both PAN_ONLY and CRYPTOGRAM_3DS. This requirement applies to both Onerway decryption and merchant decryption. For merchant decryption, submit the decrypted payment data in cardInfo.
Rule
For Google Pay, Onerway decryption corresponds to the PAYMENT_GATEWAY tokenization: set the Google Pay gateway and gatewayMerchantId parameters from the gatewayName and gatewayMerchantId returned by List available payment methods. The token is encrypted with the Onerway key and cannot be decrypted by the merchant.
Rule
For Onerway-decrypted Google Pay payments, calling Check Google Pay PAN_ONLY token before creating the transaction is optional. If you submit a PAN_ONLY token without cardInfo.cvv, the transaction response contains data.status=R and data.redirectUrl, regardless of whether you called the check endpoint. Redirect the customer to data.redirectUrl to enter the CVC on the Onerway-hosted page. If you collect the CVC yourself, submit it in cardInfo.cvv together with tokenInfo.
Condition: Required except for later subscription billing or update (subscription.requestType=1 or 2).
Transaction business information, including return URL, notification URL, store ID, products, browser data, device data, and cardholder IP data collected by the merchant.
txnTypestringrequired
Transaction operation type. It works with productType and subProductType; REFUND and BIND_CARD are not used by this direct transaction endpoint.
Example:SALE
Allowed values
SALE
Debit-style transaction. Together with subProductType=DIRECT, TOKEN, SUBSCRIBE, or INSTALLMENT, it is used for ordinary payment, token payment, subscription, or installment payment.
AUTH
Authorization-style transaction. Funds are authorized first and not captured immediately. It applies to direct card payments with merchant-collected card details and card token payments; it does not apply to LPMS, subscriptions, or installments.

Request example

curl -X POST 'https://sandbox-acq.onerway.com/v1/txn/doTransaction' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "billingInformation": "{\"firstName\":\"John\",\"lastName\":\"Doe\",\"phone\":\"4848980027\",\"phoneCountryCode\":\"1\",\"email\":\"customer@example.com\",\"postalCode\":\"94016\",\"address\":\"100 Market Street\",\"country\":\"US\",\"province\":\"CA\",\"city\":\"San Francisco\",\"street\":\"Market Street\",\"number\":\"100\"}",
  "cardInfo": "{\"holderName\":\"John Smith\",\"cardNumber\":\"{{CARD-NUMBER}}\",\"month\":\"12\",\"year\":\"2030\",\"cvv\":\"{{CVV}}\"}",
  "merchantNo": "{{MERCHANT-NO}}",
  "merchantTxnId": "txn_demo_direct_202606140001",
  "merchantTxnTime": "2026-06-14 10:30:00",
  "merchantTxnTimeZone": "+08:00",
  "metaData": "{\"orderSource\":\"direct-api-demo\"}",
  "orderAmount": "99.99",
  "orderCurrency": "USD",
  "paymentMethodOptions": "{\"card\":{\"avsEnabled\":true}}",
  "paymentMode": "WEB",
  "productType": "CARD",
  "risk3dsStrategy": "DEFAULT",
  "shippingInformation": "{\"firstName\":\"John\",\"lastName\":\"Doe\",\"phone\":\"4848980027\",\"phoneCountryCode\":\"1\",\"email\":\"customer@example.com\",\"postalCode\":\"94016\",\"address\":\"100 Market Street\",\"country\":\"US\",\"province\":\"CA\",\"city\":\"San Francisco\",\"street\":\"Market Street\",\"number\":\"100\"}",
  "sign": "{{SIGN}}",
  "subProductType": "DIRECT",
  "txnOrderMsg": "{\"returnUrl\":\"{{RETURN-URL}}\",\"products\":\"[{\\\"name\\\":\\\"Demo product\\\",\\\"price\\\":\\\"99.99\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"203.0.113.10\",\"appId\":\"{{APPID}}\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\",\"userAgent\":\"Mozilla/5.0 (Demo Browser)\",\"contentLength\":\"0\",\"language\":\"en-US\",\"notifyUrl\":\"{{WEBHOOK-ENDPOINT}}\"}",
  "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 direct transaction response. The synchronous response may be terminal or may instruct the merchant to redirect or present an action.

Response example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "2064485863093829632",
    "paymentId": "2064485863068663808",
    "responseTime": "2026-06-14 10:30:02",
    "txnTime": null,
    "txnTimeZone": null,
    "orderAmount": "99.99",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "status": "R",
    "paymentStatus": "R",
    "redirectUrl": "https://developers.onerway.com/example-direct-redirect",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL",
    "subscriptionManageUrl": null,
    "rrn": null,
    "authorizationCode": null,
    "cardInfo": null,
    "sign": "{{SIGN}}"
  }
}
No error responses are documented for this endpoint.

Create checkout payment

Create a checkout payment and obtain the redirectUrl for the Onerway-hosted payment page.

Create SDK transaction

Create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK.