# Create SDK transaction > Create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK. ```yaml openapi: 3.1.0 info: title: Create SDK transaction version: 1.0.0 description: Create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK. paths: /v1/sdkTxn/doTransaction: post: summary: Create SDK transaction description: Create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK. requestBody: required: true content: application/json: schema: type: object properties: billingInformation: type: string description: 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](/payments/api-reference/endpoints/sdk-update-order) before payment confirmation when the business flow requires it. When this object is submitted, its nested required fields and conditions still apply. contentMediaType: application/json contentSchema: type: object properties: firstName: type: string description: Customer first name. lastName: type: string description: Customer last name. jpFirstName: type: string description: Customer first name in Japanese Katakana. Required only for Japan payment methods and Japan-issued cards. jpLastName: type: string description: Customer last name in Japanese Katakana. Required only for Japan payment methods and Japan-issued cards. phone: type: string description: Customer phone number, local part only without country code. Pass the country code separately in `phoneCountryCode`, which combines with this field into the full number. Onerway does not strictly validate the format. phoneCountryCode: type: string description: Country dialing code of the customer phone number, digits only without `+`; combines with `phone` to form the full number. email: type: string description: Customer email address, used for transaction confirmations and dispute handling. postalCode: type: string description: Postal or ZIP code. Commonly used by AVS checks. address: type: string description: Full address in a single field. It can replace split street, house number, and city fields for general address capture, but should not be used as the only address input when AVS is required. country: type: string description: Country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. province: type: string description: Province or state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes) format. x-onerway-required: conditional x-onerway-condition: - Required when `country` is `US` or `CA`. city: type: string description: City name. Recommended when AVS or a complete billing address is required to improve address completeness, authorization rate, and risk checks. Actual validation dimensions vary by issuer and region. street: type: string description: Street name. When AVS is enabled, provide it separately with `number`, `postalCode`, and `city` as billing-address verification data instead of relying only on the full `address` field. number: type: string description: House or building number. When AVS is enabled, provide it separately with `street`, `postalCode`, and `city` as billing-address verification data. identityNumber: type: string description: Government-issued identity identifier, usually required by selected local payment methods. It may be a national ID number or a personal tax number. birthDate: type: string description: Birth date in `yyyy/MM/dd` format. required: - email - country x-onerway-format: json_string merchantCustId: type: string description: Unique customer identifier in the merchant system, used to associate the customer, saved payment methods, and transactions. x-onerway-required: conditional x-onerway-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. x-onerway-constraints: - kind: range max: 63 unit: characters - kind: rule text: 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. - kind: consistency text: Reuse the same server-owned `merchantCustId` only for the same customer in subsequent payments. - kind: consistency text: For subscriptions, use `subscription.merchantCustId` as the required customer identifier. If both fields are submitted, their values must match. merchantNo: type: string description: Merchant number assigned by Onerway. See [Setup](/payments/get-started/setup#retrieve-your-credentials) for how to obtain it. x-onerway-constraints: - kind: rule text: 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. merchantTxnId: type: string description: Unique transaction identifier generated by the merchant system for tracking, reconciliation, and duplicate prevention. merchantTxnOriginalId: type: string description: 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. merchantTxnTime: type: string description: 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. merchantTxnTimeZone: type: string description: Timezone offset for `merchantTxnTime`. If omitted, Onerway records the transaction time in UTC+8. metaData: type: string description: 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. orderAmount: type: string description: 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](/payments/get-started/currency-and-amount). orderCurrency: type: string description: Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) transaction currency. Must match `orderAmount`. osType: type: string description: Operating system type for app and mobile browser payments. Omit it for ordinary Web SDK payments. enum: - IOS - ANDROID x-enum-descriptions: IOS: iOS device. ANDROID: Android device. x-onerway-required: conditional x-onerway-condition: - Required when `paymentMode` is not `WEB`. paymentMode: type: string description: 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. enum: - WEB - APP - WAP x-enum-descriptions: WEB: Browser-based payment. APP: Native mobile app payment. WAP: Mobile browser payment. paymentMethodOptions: type: string description: Payment method configuration options. SDK transaction creation supports the `card` and `share` objects. contentMediaType: application/json contentSchema: type: object properties: card: type: object properties: avsEnabled: type: boolean description: Whether AVS (Address Verification Service) validation is enabled. Contact Onerway before enabling it. When set to `true`, the billing address is used for AVS checks and results are returned in `paymentMethodDetails.card.checks` through transaction queries and webhooks. description: Card-specific SDK payment options. share: type: object properties: profitShare: type: boolean description: Whether this transaction allows profit sharing. Enabling it is a prerequisite for sharing this transaction later. When `true` without `profitShareRate`, no amount is split automatically; you can still initiate profit sharing through the [Create or reverse profit share](/payments/api-reference/endpoints/create-or-reverse-profit-share) endpoint with the `transactionId` returned by this request. profitShareNotifyUrl: type: string description: URL for automatic profit share and reversal notifications. If omitted, no automatic profit share or reversal notification is sent. x-onerway-constraints: - kind: consistency text: A non-empty URL must use HTTPS and be submitted with `profitShare=true`; otherwise the payment request is rejected. - kind: rule text: The URL is saved only when `profitShare=true`. A `CAPTURE` transaction inherits the URL from its `AUTH` transaction. When the original payment has this URL, you can omit `urlCallback` from a subsequent profit share or reversal request. profitShareRate: type: string description: Automatic profit-sharing percentage, where `1` means 1% and `100` means 100%. Onerway allocates this portion to the platform merchant automatically once a `SALE` or `CAPTURE` succeeds; refunds and chargebacks return the allocated portion at the same percentage. x-onerway-constraints: - kind: range min: 1 max: 100 unit: percent - kind: rule text: Submit a whole number as a string. Decimals, `0`, negative values, and values above 100 are rejected. - kind: consistency text: Requires `profitShare=true`. Submitting a rate while `profitShare` is absent or `false` is rejected. description: Profit-sharing options for the transaction. In the platform model, part of the amount collected by the sub-merchant is allocated to the platform merchant. x-onerway-lifecycle: status: new since: 2026-08-10 description: en: New object for transaction profit sharing. zh: 交易分账的新增对象。 x-onerway-format: json_string productType: type: string description: 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. enum: - ALL - CARD x-enum-descriptions: 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. retailers: type: string description: Retailer information for marketplace transactions. Submit one entry for each retailer whose products are included in this order. contentMediaType: application/json contentSchema: type: array items: type: object properties: retailerId: type: string description: Unique retailer identifier defined by the merchant. Keep it unique within your marketplace or merchant system. It is not the Onerway sub-merchant number submitted in `merchantNo`; the two are separate identifier systems. x-onerway-constraints: - kind: range max: 64 unit: characters retailerName: type: string description: Retailer name. Prefer the registered legal name or the trading name the retailer operates under. x-onerway-constraints: - kind: range max: 128 unit: characters retailerCountry: type: string description: Retailer country or region in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. required: - retailerId - retailerName - retailerCountry x-onerway-constraints: - kind: rule text: 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. - kind: consistency text: When submitted, every entry in `txnOrderMsg.products` must carry a `retailerId` that matches one of the retailers listed here. x-onerway-format: json_string x-onerway-lifecycle: status: new since: 2026-08-10 description: en: New field for marketplace retailer information. zh: marketplace 零售商信息的新增字段。 risk3dsStrategy: type: string description: 3DS risk strategy. SDK transaction creation supports `DEFAULT`, `INNER`, and `NONE`, but does not support `EXTERNAL`. Contact Onerway before specifying a non-default strategy. enum: - DEFAULT - INNER - NONE x-enum-descriptions: 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. shippingInformation: type: string description: 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](/payments/api-reference/endpoints/sdk-update-order) before payment confirmation when the business flow requires it. When this object is submitted, its nested required fields and conditions still apply. contentMediaType: application/json contentSchema: type: object properties: firstName: type: string description: Customer first name. lastName: type: string description: Customer last name. jpFirstName: type: string description: Customer first name in Japanese Katakana. Required only for Japan payment methods and Japan-issued cards. jpLastName: type: string description: Customer last name in Japanese Katakana. Required only for Japan payment methods and Japan-issued cards. phone: type: string description: Customer phone number, local part only without country code. Pass the country code separately in `phoneCountryCode`, which combines with this field into the full number. Onerway does not strictly validate the format. phoneCountryCode: type: string description: Country dialing code of the customer phone number, digits only without `+`; combines with `phone` to form the full number. email: type: string description: Customer email address, used for transaction confirmations and dispute handling. postalCode: type: string description: Postal or ZIP code. Commonly used by AVS checks. address: type: string description: Full address in a single field. It can replace split street, house number, and city fields for general address capture, but should not be used as the only address input when AVS is required. country: type: string description: Country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. province: type: string description: Province or state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes) format. x-onerway-required: conditional x-onerway-condition: - Required when `country` is `US` or `CA`. city: type: string description: City name. Recommended when AVS or a complete billing address is required to improve address completeness, authorization rate, and risk checks. Actual validation dimensions vary by issuer and region. street: type: string description: Street name. When AVS is enabled, provide it separately with `number`, `postalCode`, and `city` as billing-address verification data instead of relying only on the full `address` field. number: type: string description: House or building number. When AVS is enabled, provide it separately with `street`, `postalCode`, and `city` as billing-address verification data. identityNumber: type: string description: Government-issued identity identifier, usually required by selected local payment methods. It may be a national ID number or a personal tax number. birthDate: type: string description: Birth date in `yyyy/MM/dd` format. required: - email - country x-onerway-format: json_string sign: type: string description: Request signature string. See [Request signing](/payments/get-started/request-signing) for how to generate it. subProductType: type: string description: Transaction processing mode under the selected payment method scope. It works with `productType` and `txnType` to define the transaction model. enum: - DIRECT - TOKEN - SUBSCRIBE - INSTALLMENT x-enum-descriptions: 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. INSTALLMENT: Installment transaction. `txnOrderMsg.periodValue` must use a period value returned by the installment inquiry API. x-onerway-constraints: - kind: rule text: 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. - kind: unsupported text: Do not use `BIND_CARD` as `txnType` for this endpoint. subscription: type: string description: 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. contentMediaType: application/json contentSchema: type: object properties: requestType: type: string description: Subscription request type. SDK subscription creation only supports `0` for the initial subscription request. `1` is not supported here and is used for subsequent billing APIs. enum: - "0" x-enum-descriptions: "0": Initial subscription request. merchantCustId: type: string description: Required subscription customer identifier in the merchant system, used to associate the subscription contract, payment method, and transaction records. x-onerway-constraints: - kind: range max: 63 unit: characters - kind: consistency text: Reuse the same `merchantCustId` only for the same customer in subsequent payments. - kind: consistency text: If top-level `merchantCustId` is also submitted, it must match this value; the top-level field may be omitted. selfExecute: type: string description: Subscription execution mode. enum: - "1" - "2" x-enum-descriptions: "1": Automatic billing by Onerway according to the subscription plan. "2": Merchant-triggered billing for each subscription cycle. mode: type: string description: "How the first subscription payment is collected. `1`: obtain subscription authorization only and let the merchant collect the first payment later; available only for `selfExecute=2`. `2` (default): collect the first payment once the customer has authorized; applicable to card subscriptions and local payment methods that require authorization. Defaults to `2` when omitted." enum: - "1" - "2" x-enum-descriptions: "1": Obtain subscription authorization only; the first payment is collected by the merchant later. Available only for self-managed subscriptions (`selfExecute=2`). "2": Collect the first payment once the customer has authorized; applicable to card subscriptions and local payment methods that require authorization. metaData: type: string description: Custom data for the subscription. Must be a string containing valid JSON. If both the top-level `metaData` and `subscription.metaData` are submitted, `subscription.metaData` is used. productName: type: string description: Subscription product or plan name. For managed subscriptions, displayed in emails, bills, and customer-visible portals. x-onerway-required: conditional x-onerway-condition: - Required for Onerway-managed subscriptions (`selfExecute=1`); supported for merchant-managed subscriptions (`selfExecute=2`) when the plan should identify a product. x-onerway-constraints: - kind: rule text: Use a stable, readable plan name. An internal ID is accepted, but it may reduce readability in customer-visible surfaces. - kind: consistency text: Within the same environment, `txnOrderMsg.appId`, `merchantCustId`, and `productName` identify the subscription product. The customer cannot purchase that product again before the existing subscription ends. amountOff: type: string description: Fixed amount deducted from each eligible subscription charge during the discount period. x-onerway-constraints: - kind: rule text: Formatted as a decimal string. Currency and precision follow the top-level `orderCurrency`; see [currency and amount validation](/payments/get-started/currency-and-amount). - kind: consistency text: Must be greater than `0` and less than the top-level `orderAmount`, so the actual charge remains greater than `0`. - kind: unsupported text: Not supported for renewal requests (`requestType=1`) or Onerway-managed subscriptions (`selfExecute=1`). x-onerway-lifecycle: status: new since: 2026-08-12 description: en: New field for fixed-amount discounts on initial merchant-managed subscription cycles. zh: 非托管订阅前若干期固定金额优惠的新增字段。 amountOffCycleCount: type: integer description: Number of successful subscription charges that receive the `amountOff` discount. When omitted, the discount applies only to the first successful charge. x-onerway-constraints: - kind: range min: 1 unit: cycles - kind: consistency text: Submit only together with `amountOff`. It is independent of the managed-subscription `cycleCount` field. - kind: rule text: Only successful charges consume a discount cycle. Authorization-only, failed, canceled, and pending transactions do not consume one. - kind: unsupported text: Not supported for renewal requests (`requestType=1`) or Onerway-managed subscriptions (`selfExecute=1`). x-onerway-lifecycle: status: new since: 2026-08-12 description: en: New field for extending a fixed-amount discount across multiple subscription charges. zh: 将固定金额优惠延续到多期订阅扣款的新增字段。 frequencyType: type: string description: Subscription billing frequency type. `selfExecute=1` supports `D`, `M`, and `Y`; `selfExecute=2` supports `D` only. enum: - D - M - Y x-enum-descriptions: D: Bill by day. M: Bill by month. Y: Bill by year. x-onerway-required: conditional x-onerway-condition: - Required for initial subscription requests; `selfExecute=2` supports `D` only. frequencyPoint: type: string description: Billing cycle length, in the unit specified by `frequencyType`. x-onerway-required: conditional x-onerway-condition: - Required for initial subscription requests. x-onerway-constraints: - kind: values text: "For `selfExecute=1`, allowed values are `1`, `7`, or `14` when `frequencyType=D`; `1`, `3`, or `6` when `frequencyType=M`; and only `1` when `frequencyType=Y`. For `selfExecute=2`, there is no fixed set of allowed values: submit the billing cycle length in days — for example, `30` for a monthly plan or `365` for an annual plan." - kind: rule text: "For `selfExecute=2`, this value is informational only: Onerway does not use it to schedule charges, and does not validate the timing of your charges against it. You initiate every renewal charge yourself." expireDate: type: string description: Subscription expiration date. Shares the maximum cycle count constraint with `cycleCount`; the subscription derived from `frequencyType` and `frequencyPoint` must not exceed `99` cycles. x-onerway-required: conditional x-onerway-condition: - Required when the subscription end is defined by an expiration date. cycleCount: type: integer description: Number of Onerway-managed subscription cycles. Supported range is `1-99`. Not supported for `selfExecute=2`. x-onerway-required: conditional x-onerway-condition: - Required for Onerway-managed subscriptions (`selfExecute=1`) when the plan end is defined by a fixed number of billing cycles. trialFromPlan: type: string description: Trial period billing mode for Onerway-managed subscriptions. `0` means the trial period is not charged; `1` means it is charged according to the plan. Not supported for `selfExecute=2`. enum: - "0" - "1" x-enum-descriptions: "0": Trial period is not charged. "1": Trial period is charged according to the subscription plan. trialDays: type: integer description: Trial period duration in days, counted from the subscription start. Supported range is `3-365` days. Not supported for `selfExecute=2`. x-onerway-required: conditional x-onerway-condition: - Required for Onerway-managed subscriptions (`selfExecute=1`) when a trial length is configured by days; mutually exclusive with `trialEnd`. trialEnd: type: string description: Trial period end date used to specify when the trial period ends. Not supported for `selfExecute=2`. x-onerway-required: conditional x-onerway-condition: - Required for Onerway-managed subscriptions (`selfExecute=1`) when a trial end date is configured; mutually exclusive with `trialDays`. notificationEmail: type: string description: Buyer email address used for subscription confirmation, status-change, and billing notifications. Not supported for `selfExecute=2`. bindCard: type: boolean description: Whether to save the customer's card after the initial payment of an Onerway-managed card subscription succeeds. Onerway reports the result in a separate [Saved payment method result webhook](/payments/api-reference/webhooks/payment-method-result) (`txnType=BIND_CARD`). x-onerway-constraints: - kind: rule text: When the card is saved, the [Saved payment method result webhook](/payments/api-reference/webhooks/payment-method-result) returns `status=S` and the saved payment method token in `tokenId`. Use that token for `subProductType=TOKEN` payments through [Create direct transaction](/payments/api-reference/endpoints/direct-create-transaction); this endpoint's legacy `subProductType=TOKEN` mode does not use it. Subscription charges use `contractId` and `tokenId` from the [Subscription payment webhook](/payments/api-reference/webhooks/subscription-payment), which is a different token. - kind: rule text: "Local payment method subscriptions ignore this field: Onerway always sends a Saved payment method result webhook for their subscription authorization." - kind: unsupported text: Not supported for `selfExecute=2`. required: - requestType - merchantCustId - selfExecute x-onerway-required: conditional x-onerway-condition: - Required when `subProductType=SUBSCRIBE`. x-onerway-format: json_string txnOrderMsg: type: string description: 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. contentMediaType: application/json contentSchema: type: object properties: returnUrl: type: string description: The URL your customer is redirected back to after completing payment. Add the merchant order ID or another identifier to the URL and query the transaction result after the customer returns. products: type: string description: List of products purchased by the customer. Product amount, discount, and shipping fee entries must add up to `orderAmount`. contentMediaType: application/json contentSchema: type: array items: type: object properties: name: type: string description: Product name. price: type: string description: Product unit price. num: type: string description: Product quantity. productAvatarUrl: type: string description: Product image URL. x-onerway-required: conditional x-onerway-condition: - Required for `stc pay`, `Tamara`, `Tabby`, and `MADA`. desc: type: string description: Product description. currency: type: string description: Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. type: type: string description: Product category. Omit this field for regular products. `virtual` and `physical` distinguish whether fulfillment is required; `shipping_fee` and `discount` can be used for all payment methods. enum: - virtual - physical - shipping_fee - discount x-enum-descriptions: virtual: Virtual product. physical: Physical product. shipping_fee: Shipping fee line item. discount: Discount line item. The amount must be negative. x-onerway-required: conditional x-onerway-condition: - "Required for `stc pay`, `Tamara`, `Tabby`, and `MADA`: set `virtual` or `physical` on each product line (`shipping_fee` and `discount` lines excepted)." retailerId: type: string description: Identifier of the retailer that sells this product. x-onerway-required: conditional x-onerway-condition: - Required when `retailers` is submitted. x-onerway-constraints: - kind: consistency text: The value must match one of the `retailerId` values submitted in `retailers`. x-onerway-lifecycle: status: new since: 2026-08-10 description: en: New field linking each product to its retailer. zh: 将商品关联到零售商的新增字段。 required: - name - price - num - currency x-onerway-format: json_string appId: type: string description: Store ID generated during Onerway onboarding. customerPlatform: type: string description: Merchant platform identifier. Use the website domain for web transactions or the app name for app transactions. x-onerway-required: conditional x-onerway-condition: - Required for `stc pay`, `Tamara`, `Tabby`, and `MADA`. periodValue: type: string description: Installment payment period returned by the installment consultation API. x-onerway-required: conditional x-onerway-condition: - Required when top-level `subProductType=INSTALLMENT`. notifyUrl: type: string description: Server-side notification URL for asynchronous payment result callbacks. Merchants are advised to query the transaction result after receiving the webhook notification. required: - returnUrl - products - appId - notifyUrl x-onerway-format: json_string txnType: type: string description: 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. enum: - SALE - AUTH x-enum-descriptions: 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. required: - merchantNo - merchantTxnId - orderAmount - orderCurrency - productType - sign - subProductType - txnOrderMsg - txnType examples: one-time-card: summary: One-time SDK card payment value: 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 managed-monthly-subscription: summary: Managed monthly SDK subscription value: merchantCustId: sdk_managed_monthly_001 merchantNo: replace_with_merchant_no merchantTxnId: sdk-managed-monthly-23181235-a10f-4d04-af2c-7446afc1a475 merchantTxnTime: 2026-07-15 06:28:36 orderAmount: "20" orderCurrency: USD productType: ALL sign: replace_with_calculated_signature subProductType: SUBSCRIBE subscription: '{"requestType":"0","merchantCustId":"sdk_managed_monthly_001","productName":"Managed Plan - Monthly","frequencyType":"M","frequencyPoint":"1","cycleCount":12,"mode":"2","selfExecute":"1","notificationEmail":"customer@test.com","metaData":"{\"plan\":\"pro-monthly\"}"}' txnOrderMsg: '{"appId":"replace_with_app_id","notifyUrl":"https://developers.onerway.com/example-notify","products":"[{\"currency\":\"USD\",\"name\":\"Managed Subscription Plan\",\"num\":\"1\",\"price\":\"20\"}]","returnUrl":"https://developers.onerway.com/example-return"}' txnType: SALE self-managed-daily-subscription: summary: Self-managed daily SDK subscription value: merchantCustId: example_subscription_customer merchantNo: replace_with_merchant_no merchantTxnId: example_sdk_subscription_001 merchantTxnTime: 2026-07-15 06:28:38 orderAmount: "20" orderCurrency: USD productType: ALL sign: replace_with_calculated_signature subProductType: SUBSCRIBE subscription: '{"requestType":"0","merchantCustId":"example_subscription_customer","productName":"Example Daily Plan","frequencyType":"D","frequencyPoint":"1","expireDate":"2099-01-01","selfExecute":"2","mode":"2"}' txnOrderMsg: '{"appId":"replace_with_app_id","products":"[{\"currency\":\"USD\",\"name\":\"Example Daily Plan\",\"num\":\"1\",\"price\":\"20\"}]","returnUrl":"https://developers.onerway.com/example-return","notifyUrl":"https://developers.onerway.com/example-notify"}' txnType: SALE saved-card-opt-in: summary: SDK payment with saved-card opt-in value: merchantCustId: example_saved_card_customer merchantNo: replace_with_merchant_no merchantTxnId: example_sdk_saved_card_001 merchantTxnTime: 2026-07-15 06:28:38 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 Saved Card Product\",\"num\":\"1\",\"price\":\"1\"}]","returnUrl":"https://developers.onerway.com/example-return"}' txnType: SALE pre-authorization: summary: SDK pre-authorization payment value: merchantNo: replace_with_merchant_no merchantTxnId: sdk-auth-71b84a5f-ffba-49de-8bda-dc022988ff66 merchantTxnTime: 2026-07-15 06:28:39 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 Auth Product\",\"num\":\"1\",\"price\":\"1\"}]","returnUrl":"https://developers.onerway.com/example-return"}' txnType: AUTH marketplace-retailers: summary: SDK marketplace payment with multiple retailers value: merchantNo: replace_with_merchant_no merchantTxnId: sdk-mkt-3c9e1f07-52b4-4d68-a1e5-90fb7c2d6a41 merchantTxnTime: 2026-07-15 06:28:39 orderAmount: "150.00" orderCurrency: USD productType: ALL retailers: '[{"retailerId":"RTL_100001","retailerName":"ABC Retail Limited","retailerCountry":"GB"},{"retailerId":"RTL_100002","retailerName":"XYZ Store GmbH","retailerCountry":"DE"}]' sign: replace_with_calculated_signature subProductType: DIRECT txnOrderMsg: '{"appId":"replace_with_app_id","notifyUrl":"https://developers.onerway.com/example-notify","products":"[{\"currency\":\"USD\",\"name\":\"Wireless Headphones\",\"num\":\"2\",\"price\":\"50.00\",\"retailerId\":\"RTL_100001\"},{\"currency\":\"USD\",\"name\":\"Desk Lamp\",\"num\":\"1\",\"price\":\"50.00\",\"retailerId\":\"RTL_100002\"}]","returnUrl":"https://developers.onerway.com/example-return"}' txnType: SALE automatic-profit-share: summary: Payment with automatic profit share notifications value: merchantNo: replace_with_merchant_no merchantTxnId: example_automatic_profit_share_payment merchantTxnTime: 2026-09-17 10:00:00 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 paymentMethodOptions: '{"share":{"profitShare":true,"profitShareRate":"10","profitShareNotifyUrl":"https://developers.onerway.com/example-profit-callback"}}' responses: "200": description: One-time SDK card transaction created content: application/json: schema: type: object properties: respCode: type: string description: Response code; `20000` means the request was processed successfully, other values are error codes. See [Response codes](/payments/api-reference/response-codes). respMsg: type: string description: Human-readable message for the response code. data: type: object properties: transactionId: type: string description: Transaction number generated by Onerway for tracking and querying. The current Web SDK initializes with `paymentId` and does not consume `transactionId` directly. paymentId: type: string description: Payment intent ID used to initialize the current Web SDK. The same payment intent may include multiple transaction attempts. responseTime: type: - string - "null" description: API response time in `yyyy-MM-dd HH:mm:ss` format. x-onerway-value: nullable: true empty: true when: en: Has a value after the transaction is processed; empty at the SDK transaction creation stage (`status=U`). zh: 交易处理后才有值；下单创建阶段（`status=U`）为空。 txnTime: type: - string - "null" description: Transaction completion time in `yyyy-MM-dd HH:mm:ss` format. x-onerway-value: nullable: true empty: true when: en: Has a value after the transaction completes; empty before completion. zh: 交易完成后才有值，未完成时为空。 txnTimeZone: type: - string - "null" description: Transaction time zone offset in `±HH:mm` format. x-onerway-value: nullable: true empty: true when: en: Has a value after the transaction completes; empty at the SDK transaction creation stage (`status=U`). zh: 交易完成后才有值；下单创建阶段（`status=U`）为空。 orderAmount: type: string description: Original order amount in the transaction currency. Returned as a decimal string using the amount precision accepted for the submitted `orderCurrency`. orderCurrency: type: string description: Order currency, a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. txnAmount: type: - string - "null" description: Legacy settlement amount field. x-onerway-value: nullable: true empty: true when: en: Deprecated field; no reliable settlement amount is available from the SDK transaction creation response. zh: 已弃用字段；SDK 下单创建响应中不提供可靠到账金额。 deprecated: true x-onerway-deprecated: description: en: Do not rely on this field for the settled amount. The actual settlement amount is settled per settlement batch; refer to the batch settlement details or report. zh: 请勿依赖本字段判断到账金额。实际结算金额按结算批次结算，以对应批次的结算明细 / 结算报表为准。 txnCurrency: type: - string - "null" description: Legacy settlement currency field. x-onerway-value: nullable: true empty: true when: en: Deprecated field; no reliable settlement currency is available from the SDK transaction creation response. zh: 已弃用字段；SDK 下单创建响应中不提供可靠结算币种。 deprecated: true x-onerway-deprecated: description: en: Do not rely on this field for the settlement currency. The settlement currency follows the settlement configuration pre-agreed between the merchant and Onerway. zh: 请勿依赖本字段判断结算币种。结算币种以商户与 Onerway 预先约定的结算配置为准。 status: type: string description: Current transaction processing status. Immediately after SDK transaction creation, this is `U` because payment has not occurred yet. enum: - S - F - P - R - N - I - U x-enum-descriptions: S: Successful transaction. F: Failed transaction. P: Transaction is processing. R: Redirect is required to continue payment. N: Transaction was canceled, including closure after timing out without payment. I: Transaction is under review or approval. U: SDK transaction is created but payment has not started or finished. paymentStatus: type: string description: Payment-intent-level status reflecting the lifecycle state across attempts under the same `paymentId`. enum: - I - U - P - R - A - O - S - N x-enum-descriptions: I: Initialized payment intent. U: Payment intent is pending. P: Payment intent is processing. R: Payment intent requires redirect. A: Payment intent is authorized. O: Payment intent is open. S: Payment intent succeeded. N: Payment intent is closed. It timed out without a successful payment — either no attempt was made or all attempts failed. redirectUrl: type: string description: The current Web SDK initializes with `paymentId` and does not consume this field. contractId: type: - string - "null" description: Subscription contract ID identifying the subscription; a key parameter for subsequent charges. x-onerway-value: nullable: true empty: true when: en: Has a value after the initial subscription succeeds, usually stored together with `tokenId` for subsequent billing; empty at SDK transaction creation. zh: 初始订阅成功后才有值，通常与 `tokenId` 成对用于后续扣款；SDK 下单创建时为空。 tokenId: type: - string - "null" description: Payment token identifier for subsequent subscription charges or token payments. Obtain subscription tokens from the [Subscription payment webhook](/payments/api-reference/webhooks/subscription-payment) and saved-card tokens from [List saved tokens](/payments/api-reference/endpoints/list-saved-tokens); do not infer either from this creation response. The two token systems must not be mixed. Store both token types securely in accordance with PCI requirements. x-onerway-value: nullable: true empty: true when: en: Empty in the synchronous SDK transaction creation response. zh: SDK 下单的同步创建响应中为空。 eci: type: - string - "null" description: Electronic Commerce Indicator (ECI) marking the transaction security level and liability shift. x-onerway-value: nullable: true empty: true when: en: Has a value only for 3DS transactions. zh: 3DS 交易才有值。 periodValue: type: - string - "null" description: Number of installment periods. x-onerway-value: nullable: true empty: true when: en: Has a value only for installment transactions. zh: 分期交易才有值。 codeForm: type: - string - "null" description: Payment code information object. contentMediaType: application/json contentSchema: type: object properties: {} x-onerway-value: nullable: true empty: true when: en: Always empty in the synchronous SDK transaction creation response; current SDK integration has no usage scenario for this field. zh: 同步创建响应恒为空；当前 SDK 接入无使用场景。 x-onerway-format: json_string presentContext: type: - string - "null" description: Additional context for rendering payment interface elements. x-onerway-value: nullable: true empty: true when: en: Always empty in the synchronous SDK transaction creation response; current SDK integration has no usage scenario for this field. zh: 同步创建响应恒为空；当前 SDK 接入无使用场景。 actionType: type: - string - "null" description: Next action type to execute. x-onerway-value: nullable: true empty: true when: en: Always empty in the synchronous SDK transaction creation response; current SDK integration has no usage scenario for this field. zh: 同步创建响应恒为空；当前 SDK 接入无使用场景。 subscriptionManageUrl: type: - string - "null" description: Subscription management URL where the buyer can view and manage their subscription. x-onerway-value: nullable: true empty: true when: en: Has a value only in subscription scenarios. zh: 订阅场景才有值。 rrn: type: - string - "null" description: Retrieval Reference Number (RRN), used for reconciliation and inquiries. x-onerway-value: nullable: true empty: true when: en: Has a value after the transaction is accepted by the acquiring network, usually after authorization or payment completion; empty before the transaction reaches the network. zh: 交易被收单网络受理（通常在授权 / 支付完成后）后才有值；3DS 待验证等未达网络的阶段为空。 authorizationCode: type: - string - "null" description: Issuer authorization code, used for reconciliation and dispute handling. x-onerway-value: nullable: true empty: true when: en: Has a value after issuer authorization is approved. zh: 发卡行授权通过后才有值。 cardInfo: type: - string - "null" description: Masked card information object returned when card details are available. contentMediaType: application/json contentSchema: type: object properties: {} x-onerway-value: nullable: true empty: true when: en: Has a value for card transactions after card details are available. zh: 卡类交易在卡信息可用后才有值。 x-onerway-format: json_string retryAdvice: type: - string - "null" description: Retry advice returned when the transaction fails or retry guidance is available. Treat a non-empty value as informational guidance. x-onerway-value: nullable: true empty: true when: en: Has a value when the transaction fails or retry guidance is available. zh: 交易失败或存在重试建议时才有值。 sign: type: string description: Response signature string; verifying the response signature is currently not recommended for merchants. description: 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. examples: one-time-card: summary: One-time SDK card transaction created value: 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 managed-monthly-subscription: summary: Managed monthly SDK subscription created value: respCode: "20000" respMsg: Success data: transactionId: "2077158348415176704" paymentId: "2077158348402593792" responseTime: 2026-07-15 06:28:36 txnTime: null txnTimeZone: +08:00 orderAmount: "20.00" orderCurrency: USD txnAmount: null txnCurrency: null status: U paymentStatus: U redirectUrl: https://sandbox-checkout-sdk.onerway.com contractId: null tokenId: null eci: null periodValue: null codeForm: null presentContext: null actionType: null subscriptionManageUrl: https://sandbox-myscribe.onerway.com/pages/subscription-list/details?subKey=1BnKnULObhtYuOG rrn: null authorizationCode: null cardInfo: null retryAdvice: null sign: replace_with_response_signature self-managed-daily-subscription: summary: Self-managed daily SDK subscription created value: respCode: "20000" respMsg: Success data: transactionId: example_transaction_id_subscription paymentId: example_payment_id_subscription responseTime: 2026-07-15 06:28:38 txnTime: null txnTimeZone: +08:00 orderAmount: "20.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 saved-card-opt-in: summary: SDK payment with saved-card opt-in created value: respCode: "20000" respMsg: Success data: transactionId: example_transaction_id_saved_card paymentId: example_payment_id_saved_card responseTime: 2026-07-15 06:28:39 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 pre-authorization: summary: SDK pre-authorization transaction created value: respCode: "20000" respMsg: Success data: transactionId: "2077158362398986240" paymentId: "2077158362390597632" responseTime: 2026-07-15 06:28:40 txnTime: null txnTimeZone: +08:00 orderAmount: "1.00" orderCurrency: USD txnAmount: null txnCurrency: null status: U paymentStatus: U redirectUrl: https://sandbox-checkout-sdk.onerway.com 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 marketplace-retailers: summary: SDK marketplace transaction created value: respCode: "20000" respMsg: Success data: transactionId: "2077158362398986241" paymentId: "2077158362390597633" responseTime: 2026-07-15 06:28:40 txnTime: null txnTimeZone: +08:00 orderAmount: "150.00" orderCurrency: USD txnAmount: null txnCurrency: null status: U paymentStatus: U redirectUrl: https://sandbox-checkout-sdk.onerway.com 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 ```