POST

Create SDK transaction

Use this endpoint to create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK.

billingInformationobject{16}optional{ email, country, ... }

Optional transaction billing information, including the customer billing address and contact details. Provide it when available during transaction creation, or add it through Update SDK order before payment confirmation when the business flow requires it. When this object is submitted, its nested required fields and conditions still apply.

merchantCustIdstring

Condition:

Required for a legacy Web SDK save-card flow when subProductType=TOKEN.
Required for a DIRECT payment when the current Web SDK should offer the customer a saved-card option.

Unique customer identifier in the merchant system, used to associate the customer, saved payment methods, and transactions.

Example:customer_12345

Constraints

Range: 63characters
Rule: For a DIRECT payment, provide this field when the current Web SDK should let the customer choose whether to save the card after payment. Saving is opt-in and is not enabled by default.
Consistency: Reuse the same server-owned merchantCustId only for the same customer in subsequent payments.
Consistency: For subscriptions, use subscription.merchantCustId as the required customer identifier. If both fields are submitted, their values must match.

merchantNostring

Merchant number assigned by Onerway. See Setup for how to obtain it.

Example:replace_with_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.

merchantTxnIdstring

Unique transaction identifier generated by the merchant system for tracking, reconciliation, and duplicate prevention.

merchantTxnOriginalIdstringoptional

Original merchant order ID used to associate multiple SDK transaction creation attempts with the same original order. Before payment occurs, the merchant may create multiple transactionId values with the same merchantTxnOriginalId and different merchantTxnId; only one combination can complete payment, and subsequent creations after payment activity may be rejected as duplicate orders.

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. If both the top-level metaData and subscription.metaData are submitted, subscription.metaData is used.

orderAmountstring

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

orderCurrencystring

Three-letter ISO 4217 transaction currency. Must match orderAmount.

Example:USD

osTypestring

Condition: Required when paymentMode is not WEB.

Operating system type for app and mobile browser payments. Omit it for ordinary Web SDK payments.

Example:IOS

Allowed values

IOS: iOS device.
ANDROID: Android device.

paymentModestringoptionaldefaultWEB

Optional payment mode. Most Web SDK integrations omit this field; you do not need to distinguish desktop and mobile browsers. If you submit a value other than WEB, osType is required.

Example:WEB

Allowed values

WEB: Browser-based payment.
APP: Native mobile app payment.
WAP: Mobile browser payment.

paymentMethodOptionsobject{6}optional{ card, share }

Payment method configuration options. SDK transaction creation supports the card and share objects.

productTypestringdefaultALL

Payment method scope for SDK transaction creation. ALL is the default and covers card payments, Google Pay, Apple Pay, and any additional methods enabled for the merchant. CARD is used by the legacy SDK and is not recommended for new integrations.

Example:ALL

Allowed values

ALL: All supported payment methods. Default value for new integrations; covers card payments, Google Pay, Apple Pay, and any additional methods enabled for the merchant.
CARD: Card payment scope only. Used by the legacy SDK; not recommended for new integrations.

retailersarray<object>[3]optionalNEW{ retailerId, retailerName, ... }

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. SDK transaction creation supports DEFAULT, INNER, and NONE, but does not support EXTERNAL. 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.

shippingInformationobject{16}optional{ email, country, ... }

Optional transaction shipping information, including the customer delivery address and contact details. Provide it when available during transaction creation, or add it through Update SDK order before payment confirmation when the business flow requires it. When this object is submitted, its nested required fields and conditions still apply.

signstring

Request signature string. See Request signing for how to generate it.

subProductTypestring

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 SDK payment. Execute a one-time debit or authorization according to txnType.
TOKEN: Legacy Web SDK save-card mode. Use this value only for an older Web SDK integration whose contract explicitly requires TOKEN. The current Web SDK save-card opt-in uses DIRECT with merchantCustId instead.
SUBSCRIBE: Initial subscription transaction. Used to create a subscription contract through SDK; subscription is required, and subsequent billing, cancellation, and updates use the corresponding subscription APIs.

Constraints

Rule: For current Web SDK payments that may save the card after payment, use DIRECT and provide merchantCustId; the customer chooses whether to save the card inside the SDK.
Unsupported: Do not use BIND_CARD as txnType for this endpoint.

subscriptionobject{17}{ requestType, merchantCustId, ... }

Condition: Required when subProductType=SUBSCRIBE.

Subscription information for creating or initializing a subscription through SDK. 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.

txnOrderMsgobject{14}{ returnUrl, products, ... }

Transaction business information, including returnUrl, notifyUrl, appId, and product details. Browser, device, and cardholder IP data are collected by the Web SDK and are not submitted by the merchant in this request.

txnTypestring

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. REFUND and BIND_CARD are not used by this SDK transaction creation endpoint.

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 productType, subProductType, and the merchant's enabled configuration.

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.

dataobject{25}{ transactionId, paymentId, ... }

Business data object for the SDK transaction creation response. This synchronous response represents transaction creation (status=U). Use SDK callbacks only for client-side UX; determine the final payment result through a server-side webhook or transaction query.

No error responses are documented for this endpoint.

POST

curl -X POST 'https://sandbox-acq.onerway.com/v1/sdkTxn/doTransaction' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "merchantNo": "replace_with_merchant_no",
  "merchantTxnId": "example_sdk_one_time_001",
  "merchantTxnTime": "2026-07-15 06:28:34",
  "orderAmount": "1",
  "orderCurrency": "USD",
  "productType": "ALL",
  "sign": "replace_with_calculated_signature",
  "subProductType": "DIRECT",
  "txnOrderMsg": "{\"appId\":\"replace_with_app_id\",\"notifyUrl\":\"https://developers.onerway.com/example-notify\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"SDK One-time Product\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"1\\\"}]\",\"returnUrl\":\"https://developers.onerway.com/example-return\"}",
  "txnType": "SALE"
}'

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "example_transaction_id_one_time",
    "paymentId": "example_payment_id_one_time",
    "responseTime": "2026-07-15 06:28:35",
    "txnTime": null,
    "txnTimeZone": "+08:00",
    "orderAmount": "1.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "U",
    "paymentStatus": "U",
    "redirectUrl": "https://developers.onerway.com/example-sdk",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": null,
    "rrn": null,
    "authorizationCode": null,
    "cardInfo": null,
    "retryAdvice": null,
    "sign": "replace_with_response_signature"
  }
}

POST

Create SDK transaction

Use this endpoint to create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK.

billingInformationobject{16}optional{ email, country, ... }

merchantCustIdstring

Condition:

Required for a legacy Web SDK save-card flow when subProductType=TOKEN.
Required for a DIRECT payment when the current Web SDK should offer the customer a saved-card option.

Unique customer identifier in the merchant system, used to associate the customer, saved payment methods, and transactions.

Example:customer_12345

Constraints

Range: 63characters
Rule: For a DIRECT payment, provide this field when the current Web SDK should let the customer choose whether to save the card after payment. Saving is opt-in and is not enabled by default.
Consistency: Reuse the same server-owned merchantCustId only for the same customer in subsequent payments.
Consistency: For subscriptions, use subscription.merchantCustId as the required customer identifier. If both fields are submitted, their values must match.

merchantNostring

Merchant number assigned by Onerway. See Setup for how to obtain it.

Example:replace_with_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.

merchantTxnIdstring

Unique transaction identifier generated by the merchant system for tracking, reconciliation, and duplicate prevention.

merchantTxnOriginalIdstringoptional

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

orderAmountstring

Example:99.99

orderCurrencystring

Three-letter ISO 4217 transaction currency. Must match orderAmount.

Example:USD

osTypestring

Condition: Required when paymentMode is not WEB.

Operating system type for app and mobile browser payments. Omit it for ordinary Web SDK payments.

Example:IOS

Allowed values

IOS: iOS device.
ANDROID: Android device.

paymentModestringoptionaldefaultWEB

Optional payment mode. Most Web SDK integrations omit this field; you do not need to distinguish desktop and mobile browsers. If you submit a value other than WEB, osType is required.

Example:WEB

Allowed values

WEB: Browser-based payment.
APP: Native mobile app payment.
WAP: Mobile browser payment.

paymentMethodOptionsobject{6}optional{ card, share }

Payment method configuration options. SDK transaction creation supports the card and share objects.

productTypestringdefaultALL

Example:ALL

Allowed values

ALL: All supported payment methods. Default value for new integrations; covers card payments, Google Pay, Apple Pay, and any additional methods enabled for the merchant.
CARD: Card payment scope only. Used by the legacy SDK; not recommended for new integrations.

retailersarray<object>[3]optionalNEW{ retailerId, retailerName, ... }

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. SDK transaction creation supports DEFAULT, INNER, and NONE, but does not support EXTERNAL. 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.

shippingInformationobject{16}optional{ email, country, ... }

signstring

Request signature string. See Request signing for how to generate it.

subProductTypestring

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 SDK payment. Execute a one-time debit or authorization according to txnType.
TOKEN: Legacy Web SDK save-card mode. Use this value only for an older Web SDK integration whose contract explicitly requires TOKEN. The current Web SDK save-card opt-in uses DIRECT with merchantCustId instead.
SUBSCRIBE: Initial subscription transaction. Used to create a subscription contract through SDK; subscription is required, and subsequent billing, cancellation, and updates use the corresponding subscription APIs.

Constraints

Rule: For current Web SDK payments that may save the card after payment, use DIRECT and provide merchantCustId; the customer chooses whether to save the card inside the SDK.
Unsupported: Do not use BIND_CARD as txnType for this endpoint.

subscriptionobject{17}{ requestType, merchantCustId, ... }

Condition: Required when subProductType=SUBSCRIBE.

txnOrderMsgobject{14}{ returnUrl, products, ... }

txnTypestring

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 productType, subProductType, and the merchant's enabled configuration.

curl -X POST 'https://sandbox-acq.onerway.com/v1/sdkTxn/doTransaction' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "merchantNo": "replace_with_merchant_no",
  "merchantTxnId": "example_sdk_one_time_001",
  "merchantTxnTime": "2026-07-15 06:28:34",
  "orderAmount": "1",
  "orderCurrency": "USD",
  "productType": "ALL",
  "sign": "replace_with_calculated_signature",
  "subProductType": "DIRECT",
  "txnOrderMsg": "{\"appId\":\"replace_with_app_id\",\"notifyUrl\":\"https://developers.onerway.com/example-notify\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"SDK One-time Product\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"1\\\"}]\",\"returnUrl\":\"https://developers.onerway.com/example-return\"}",
  "txnType": "SALE"
}'

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.

dataobject{25}{ transactionId, paymentId, ... }

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "example_transaction_id_one_time",
    "paymentId": "example_payment_id_one_time",
    "responseTime": "2026-07-15 06:28:35",
    "txnTime": null,
    "txnTimeZone": "+08:00",
    "orderAmount": "1.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "U",
    "paymentStatus": "U",
    "redirectUrl": "https://developers.onerway.com/example-sdk",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": null,
    "rrn": null,
    "authorizationCode": null,
    "cardInfo": null,
    "retryAdvice": null,
    "sign": "replace_with_response_signature"
  }
}

No error responses are documented for this endpoint.

Create direct transaction

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

Create card token

Create a card token in a PCI DSS compliant integration and receive the final tokenization result through notifyUrl.

Request

Response

Request

Request example

Response

Response example