# 创建 SDK 交易 > 创建 SDK 交易并获取用于初始化当前 Onerway Web SDK 的 paymentId。 ```yaml openapi: 3.1.0 info: title: 创建 SDK 交易 version: 1.0.0 description: 创建 SDK 交易并获取用于初始化当前 Onerway Web SDK 的 paymentId。 paths: /v1/sdkTxn/doTransaction: post: summary: 创建 SDK 交易 description: 创建 SDK 交易并获取用于初始化当前 Onerway Web SDK 的 paymentId。 requestBody: required: true content: application/json: schema: type: object properties: billingInformation: type: string description: 可选的交易账单信息，包含客户账单地址和联系信息。可在创建交易时传入；业务流程需要且初始下单省略时，可在确认支付前通过[更新 SDK 订单](/zh/payments/api-reference/endpoints/sdk-update-order)补充。传入该对象后，其内部字段原有的必填条件仍然生效。 contentMediaType: application/json contentSchema: type: object properties: firstName: type: string description: 客户名字。 lastName: type: string description: 客户姓氏。 jpFirstName: type: string description: 日语片假名格式的名字；仅日本支付方式和日本发行的卡需要。 jpLastName: type: string description: 日语片假名格式的姓氏；仅日本支付方式和日本发行的卡需要。 phone: type: string description: 客户电话号码，仅填本地号码（不含国家码）；国家码请单独传入 `phoneCountryCode`，二者组合为完整号码。Onerway 当前不强校验格式。 phoneCountryCode: type: string description: 客户电话号码的国家拨号码，纯数字、不含 `+`；与 `phone` 组合为完整号码。 email: type: string description: 客户邮箱地址，用于交易确认和争议处理。 postalCode: type: string description: 邮政编码；许多地区的 AVS 验证需要此字段。 address: type: string description: 完整地址字段，可替代街道、门牌号和城市等拆分字段；不建议用于 AVS 验证。 country: type: string description: "[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alph\ a-2) 国家或地区代码。" province: type: string description: "[ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_code\ s) 省/州代码。" x-onerway-required: conditional x-onerway-condition: - 当 `country` 为 `US` 或 `CA` 时必填。 city: type: string description: 城市名称。开启 AVS 或需要完整账单地址时建议传入，用于补充地址完整性、授权率和风控判断；不同发卡行和地区的实际校验维度可能不同。 street: type: string description: 街道名称。开启 AVS 时建议与 `number`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息；不要仅用完整 `address` 字段替代拆分地址。 number: type: string description: 门牌号或建筑号。开启 AVS 时建议与 `street`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息。 identityNumber: type: string description: 政府颁发的身份标识，通常用于特定本地支付方式；可能是身份证号码，也可能是个人税号。 birthDate: type: string description: 出生日期，格式为 `yyyy/MM/dd`。 required: - email - country x-onerway-format: json_string merchantCustId: type: string description: 客户在商户系统中的唯一标识，用于关联客户、已保存支付方式和交易信息。 x-onerway-required: conditional x-onerway-condition: - 旧版 Web SDK 保存卡流程使用 `subProductType=TOKEN` 时必填。 - 当前 Web SDK 的 `DIRECT` 支付需要向客户提供保存卡选项时必填。 x-onerway-constraints: - kind: range max: 63 unit: 字符 - kind: rule text: 当前 Web SDK 的 `DIRECT` 支付如需让客户选择是否在支付后保存卡，请传入本字段。保存卡由客户主动勾选，不会默认启用。 - kind: consistency text: 后续支付中应对同一客户复用相同的服务端管理标识。 - kind: consistency text: 订阅交易应以 `subscription.merchantCustId` 作为必填客户标识；若内外层同时传入，两者必须一致。 merchantNo: type: string description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。 x-onerway-constraints: - kind: rule text: 平台模式下传该笔交易所属子商户的商户号，而不是平台商户号；该子商户需已在 Onerway 完成报备。 merchantTxnId: type: string description: 商户系统生成的每笔支付唯一交易标识，用于交易跟踪、对账和防重复处理。 merchantTxnOriginalId: type: string description: 商户原始订单 ID，用于将多次 SDK 下单尝试关联到同一笔原始订单。用户支付前，商户可以用相同的 `merchantTxnOriginalId` 和不同的 `merchantTxnId` 再次下单，获得多个 `transactionId`；但实际能完成支付的只会是其中一个 `merchantTxnOriginalId + merchantTxnId + transactionId` 组合。用户一旦发生支付行为，再用相同 `merchantTxnOriginalId` 下单会因重复订单报错。 merchantTxnTime: type: string description: 商户发起交易的时间戳，格式为 `yyyy-MM-dd HH:mm:ss`；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。 merchantTxnTimeZone: type: string description: "`merchantTxnTime` 对应的时区偏移量；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。" metaData: type: string description: 本次交易的商户自定义数据，必须是包含合法 JSON 的字符串；交易查询和异步通知会原样返回，未传入时其中的 `metaData` 为空。同时传入外层 `metaData` 与 `subscription.metaData` 时，以 `subscription.metaData` 为准。 orderAmount: type: string description: 指定货币的交易金额，使用十进制字符串。零小数币种必须表示整数金额，可带 `.00` 这类全 0 小数；非零小数会被拒绝。格式要求详见[币种与金额校验](/zh/payments/get-started/currency-and-amount)。 orderCurrency: type: string description: "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码，需与 `orderAmount` 匹配。" osType: type: string description: App 与移动浏览器支付的操作系统类型；普通 Web SDK 支付请省略。 enum: - IOS - ANDROID x-enum-descriptions: IOS: iOS 设备。 ANDROID: Android 设备。 x-onerway-required: conditional x-onerway-condition: - 当 `paymentMode` 不是 `WEB` 时必填。 paymentMode: type: string description: 可选的支付模式。Web SDK 接入通常省略该字段，无需区分桌面和移动浏览器；传入非 `WEB` 值时，`osType` 必填。 enum: - WEB - APP - WAP x-enum-descriptions: WEB: 浏览器支付。 APP: 原生移动 App 支付。 WAP: 移动浏览器支付。 paymentMethodOptions: type: string description: 支付方式配置选项；SDK 下单支持 `card` 与 `share` 对象。 contentMediaType: application/json contentSchema: type: object properties: card: type: object properties: avsEnabled: type: boolean description: 是否开启 AVS（地址验证服务）；使用前需提前联系 Onerway 开通。设为 `true` 时使用账单地址进行 AVS 验证，结果通过交易查询和 Webhook 的 `paymentMethodDetails.card.checks` 返回。 description: 卡支付配置项。 share: type: object properties: profitShare: type: boolean description: 本次交易是否允许分账；启用后该笔交易才可参与后续分账。传 `true` 但未同时传 `profitShareRate` 时不会自动分账，仍可使用本次请求返回的 `transactionId`，通过[发起分账或分账回退](/zh/payments/api-reference/endpoints/create-or-reverse-profit-share)接口发起分账。 profitShareNotifyUrl: type: string description: 接收自动分账及分账回退通知的地址。不传时，不发送自动分账或分账回退通知。 x-onerway-constraints: - kind: consistency text: 非空地址必须使用 HTTPS，并与 `profitShare=true` 同时提交，否则支付请求会被拒绝。 - kind: rule text: 仅在 `profitShare=true` 时保存该地址。`CAPTURE` 交易继承原 `AUTH` 交易的地址。原支付已配置该地址时，后续分账或分账回退请求无需再传 `urlCallback`。 profitShareRate: type: string description: 自动分账比例，`1` 表示 1%，`100` 表示 100%。`SALE` 或 `CAPTURE` 成功后按该比例自动分账给平台商户；发生退款或拒付时，按同一比例退还对应的分账金额。 x-onerway-constraints: - kind: range min: 1 max: 100 unit: "%" - kind: rule text: 需传入整数形式的字符串；小数、`0`、负数或大于 100 的取值会被拒绝。 - kind: consistency text: 需与 `profitShare=true` 同时传入；`profitShare` 未传或为 `false` 时传入比例会被拒绝。 description: 本次交易的分账配置。平台模式下，子商户收到的款项中会有一部分分给平台商户。 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: SDK 下单的支付方式范围。`ALL` 为默认值，涵盖卡支付、Google Pay、Apple Pay 及商户已开通的其他方式。`CARD` 为旧版 SDK 使用的取值，不推荐新接入商户使用。 enum: - ALL - CARD x-enum-descriptions: ALL: 所有支持的支付方式。新接入商户的默认值；涵盖卡支付、Google Pay、Apple Pay 及商户已开通的其他方式。 CARD: 仅卡支付范围。旧版 SDK 使用的取值，不推荐新接入商户使用。 retailers: type: string description: marketplace 交易的零售商信息；订单包含的每个零售商各传入一个对象。 contentMediaType: application/json contentSchema: type: array items: type: object properties: retailerId: type: string description: 商户自行定义的零售商唯一标识；需在 marketplace 或商户体系内保持唯一。该标识不是 `merchantNo` 中传入的 Onerway 子商户号，两者属于不同的标识体系。 x-onerway-constraints: - kind: range max: 64 unit: 字符 retailerName: type: string description: 零售商名称；建议传入其正式注册名称或对外经营名称。 x-onerway-constraints: - kind: range max: 128 unit: 字符 retailerCountry: type: string description: 零售商所在国家或地区，使用 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 国家或地区代码。 required: - retailerId - retailerName - retailerCountry x-onerway-constraints: - kind: rule text: 适用于 marketplace / 平台模式下商品由第三方零售商销售的场景；仅销售自有商品的商户无需传入。 - kind: consistency text: 传入该字段后，`txnOrderMsg.products` 中的每个商品都需要传入 `retailerId`，且取值需命中此处列出的某个零售商。 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 风控策略；默认值为 `DEFAULT`。SDK 下单支持 `DEFAULT`、`INNER`、`NONE`，不支持传 `EXTERNAL`；如需指定非默认策略，需提前联系 Onerway 确认配置。 enum: - DEFAULT - INNER - NONE x-enum-descriptions: DEFAULT: 默认策略，由 Onerway 根据交易、商户配置和风控判断是否发起 3DS 验证。 INNER: 强制使用 Onerway 托管的 3DS 验证流程。 NONE: 不走 3DS 验证；是否可用需结合商户配置和风控要求确认。 shippingInformation: type: string description: 可选的交易配送信息，包含客户配送地址和联系信息。可在创建交易时传入；业务流程需要且初始下单省略时，可在确认支付前通过[更新 SDK 订单](/zh/payments/api-reference/endpoints/sdk-update-order)补充。传入该对象后，其内部字段原有的必填条件仍然生效。 contentMediaType: application/json contentSchema: type: object properties: firstName: type: string description: 客户名字。 lastName: type: string description: 客户姓氏。 jpFirstName: type: string description: 日语片假名格式的名字；仅日本支付方式和日本发行的卡需要。 jpLastName: type: string description: 日语片假名格式的姓氏；仅日本支付方式和日本发行的卡需要。 phone: type: string description: 客户电话号码，仅填本地号码（不含国家码）；国家码请单独传入 `phoneCountryCode`，二者组合为完整号码。Onerway 当前不强校验格式。 phoneCountryCode: type: string description: 客户电话号码的国家拨号码，纯数字、不含 `+`；与 `phone` 组合为完整号码。 email: type: string description: 客户邮箱地址，用于交易确认和争议处理。 postalCode: type: string description: 邮政编码；许多地区的 AVS 验证需要此字段。 address: type: string description: 完整地址字段，可替代街道、门牌号和城市等拆分字段；不建议用于 AVS 验证。 country: type: string description: "[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alph\ a-2) 国家或地区代码。" province: type: string description: "[ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_code\ s) 省/州代码。" x-onerway-required: conditional x-onerway-condition: - 当 `country` 为 `US` 或 `CA` 时必填。 city: type: string description: 城市名称。开启 AVS 或需要完整账单地址时建议传入，用于补充地址完整性、授权率和风控判断；不同发卡行和地区的实际校验维度可能不同。 street: type: string description: 街道名称。开启 AVS 时建议与 `number`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息；不要仅用完整 `address` 字段替代拆分地址。 number: type: string description: 门牌号或建筑号。开启 AVS 时建议与 `street`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息。 identityNumber: type: string description: 政府颁发的身份标识，通常用于特定本地支付方式；可能是身份证号码，也可能是个人税号。 birthDate: type: string description: 出生日期，格式为 `yyyy/MM/dd`。 required: - email - country x-onerway-format: json_string sign: type: string description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。 subProductType: type: string description: 所选支付方式范围下的交易处理模式，需要与 `productType` 和 `txnType` 配合定义交易模型。 enum: - DIRECT - TOKEN - SUBSCRIBE - INSTALLMENT x-enum-descriptions: DIRECT: 普通 SDK 支付，按 `txnType` 执行一次性扣款或预授权。 TOKEN: 旧版 Web SDK 保存卡模式。仅当所接入的旧版 Web SDK 契约明确要求 `TOKEN` 时使用；当前 Web SDK 的保存卡选项改用 `DIRECT` 并传入 `merchantCustId`。 SUBSCRIBE: 初始订阅交易，用于通过 SDK 创建订阅合约；需同时传入 `subscription`，后续扣款、取消和更新需走对应订阅接口。 INSTALLMENT: 分期交易；需在 `txnOrderMsg.periodValue` 中传入咨询分期期数接口返回的期数值。 x-onerway-constraints: - kind: rule text: 当前 Web SDK 如需在支付后提供保存卡选项，应使用 `DIRECT` 并传入 `merchantCustId`；是否保存由客户在 SDK 内主动选择。 - kind: unsupported text: 本接口不要把 `BIND_CARD` 作为 `txnType` 传入。 subscription: type: string description: 用于通过 SDK 创建或初始化订阅的订阅信息，包含订阅频率、执行方式和其他配置。本接口仅用于初始订阅；订阅后续扣款、取消、更新需走对应订阅接口。`selfExecute=1` 表示托管订阅；`selfExecute=2` 表示自主管理订阅。 contentMediaType: application/json contentSchema: type: object properties: requestType: type: string description: 订阅请求类型。本接口仅用于初始订阅，仅支持 `0`。`1` 用于后续扣款场景，本接口不支持传入。 enum: - "0" x-enum-descriptions: "0": 初始订阅请求。 merchantCustId: type: string description: 订阅客户在商户系统中的唯一标识，用于关联订阅合约、支付信息和交易信息。 x-onerway-constraints: - kind: range max: 63 unit: 字符 - kind: consistency text: 后续支付中应对同一客户复用相同的 `merchantCustId`。 - kind: consistency text: 如果外层 `merchantCustId` 同时传入，必须与本字段保持一致；外层 `merchantCustId` 可不传。 selfExecute: type: string description: 订阅执行方式，用于区分托管订阅和自主管理订阅。 enum: - "1" - "2" x-enum-descriptions: "1": 由 Onerway 按订阅计划自动扣款。 "2": 由商户在每个订阅周期主动发起扣款。 mode: type: string description: 订阅首期扣款方式。`1`：仅获取用户订阅授权并返回授权结果，暂不扣款，首期扣款改由商户自行发起，仅自主管理订阅（`selfExecute=2`）适用；`2`（默认）：获取用户授权后立即完成首期扣款，适用于卡订阅及需用户授权的本地支付方式。不传时默认为 `2`。 enum: - "1" - "2" x-enum-descriptions: "1": 仅获取用户订阅授权，首期扣款改由商户自行发起；仅自主管理订阅（`selfExecute=2`）适用。 "2": 获取用户授权后立即完成首期扣款；适用于卡订阅及需用户授权的本地支付方式。 metaData: type: string description: 订阅的商户自定义数据，必须是包含合法 JSON 的字符串；同时传入外层 `metaData` 与 `subscription.metaData` 时，以 `subscription.metaData` 为准。 productName: type: string description: 订阅产品或计划名称。托管订阅下会展示在邮件、账单和客户可见的管理页面中。 x-onerway-required: conditional x-onerway-condition: - 托管订阅（`selfExecute=1`）时必填；自主管理订阅（`selfExecute=2`）也支持传入，用于在订阅记录中区分商品或计划。 x-onerway-constraints: - kind: rule text: 建议使用稳定、可读的计划名称。可以传入内部 ID，但会降低客户可见页面中的可读性。 - kind: consistency text: 在同一环境下，`txnOrderMsg.appId`、`merchantCustId` 与 `productName` 的组合标识订阅产品；现有订阅结束前，该客户不能重复购买同一产品。 amountOff: type: string description: 优惠期内每期订阅扣款减免的固定金额。 x-onerway-constraints: - kind: rule text: 使用 decimal string 格式；币种和精度与外层 `orderCurrency` 一致，规则见[币种与金额校验](/zh/payments/get-started/currency-and-amount)。 - kind: consistency text: 必须大于 `0` 且小于外层 `orderAmount`，以确保实际扣款金额大于 `0`。 - kind: unsupported text: 续费请求（`requestType=1`）和托管订阅（`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: 享受 `amountOff` 优惠的成功订阅扣款期数；不传时仅首次成功扣款享受优惠。 x-onerway-constraints: - kind: range min: 1 unit: 期 - kind: consistency text: 仅可与 `amountOff` 同时传入；与托管订阅的 `cycleCount` 字段无关。 - kind: rule text: 仅成功扣款消耗优惠期数；仅授权、失败、取消和处理中的交易均不消耗。 - kind: unsupported text: 续费请求（`requestType=1`）和托管订阅（`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: 订阅计费频率类型。`selfExecute=1` 支持 `D`、`M`、`Y`；`selfExecute=2` 仅支持 `D`。 enum: - D - M - Y x-enum-descriptions: D: 按天计费。 M: 按月计费。 Y: 按年计费。 x-onerway-required: conditional x-onerway-condition: - 初始订阅请求中提供；自主管理订阅（`selfExecute=2`）仅支持 `D`。 frequencyPoint: type: string description: 计费周期长度，单位由 `frequencyType` 指定。 x-onerway-required: conditional x-onerway-condition: - 初始订阅请求中提供。 x-onerway-constraints: - kind: values text: 托管订阅（`selfExecute=1`）中，`frequencyType=D` 时可传 `1`、`7`、`14`；`frequencyType=M` 时可传 `1`、`3`、`6`；`frequencyType=Y` 时仅可传 `1`。自主管理订阅（`selfExecute=2`）中该值没有固定取值集合，表示计费周期的天数，例如月度订阅传 `30`、年度订阅传 `365`。 - kind: rule text: 自主管理订阅（`selfExecute=2`）中，该值仅用于记录订阅的计费周期：Onerway 不据此自动发起扣款，也不校验实际扣款时间是否符合该周期；每期续费扣款由商户自行发起。 expireDate: type: string description: 订阅到期日期。与 `cycleCount` 共享最大期数约束；按 `frequencyType` 和 `frequencyPoint` 推导出的订阅周期不得超过 `99` 期。 x-onerway-required: conditional x-onerway-condition: - 使用到期日期定义订阅结束时间时提供。 cycleCount: type: integer description: 托管订阅计费周期数量，取值范围 `1-99`。`selfExecute=2` 自主管理订阅不支持。 x-onerway-required: conditional x-onerway-condition: - 托管订阅中使用固定周期数定义订阅计划时提供。 trialFromPlan: type: string description: 托管订阅的试用期计费控制。`0` 表示试用期不收费；`1` 表示按订阅计划计费。`selfExecute=2` 自主管理订阅不支持。 enum: - "0" - "1" x-enum-descriptions: "0": 试用期不收费。 "1": 试用期按订阅计划计费。 trialDays: type: integer description: 试用期持续天数，用于指定从订阅生效后连续试用多少天，取值范围 `3-365`。`selfExecute=2` 自主管理订阅不支持。 x-onerway-required: conditional x-onerway-condition: - 托管订阅中按天数设置试用期时提供；与 `trialEnd` 二选一。 trialEnd: type: string description: 试用期结束日期，用于直接指定试用期截止到哪一天。`selfExecute=2` 自主管理订阅不支持。 x-onerway-required: conditional x-onerway-condition: - 托管订阅中按结束日期设置试用期时提供；与 `trialDays` 二选一。 notificationEmail: type: string description: 订阅通知邮箱；订阅确认、状态变更、扣款通知都会发送到该邮箱。`selfExecute=2` 自主管理订阅不支持。 bindCard: type: boolean description: 托管卡订阅首次支付成功后，是否保存客户的卡。保存结果由 Onerway 通过独立的[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)（`txnType=BIND_CARD`）发送。 x-onerway-constraints: - kind: rule text: 保存成功时，[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)返回 `status=S`，其 `tokenId` 即保存支付方式 token，可用于[创建直连交易](/zh/payments/api-reference/endpoints/direct-create-transaction)的 `subProductType=TOKEN` 支付；本接口的旧版 `subProductType=TOKEN` 模式不使用该 token。订阅扣款使用[订阅扣款通知](/zh/payments/api-reference/webhooks/subscription-payment)返回的 `contractId` 与 `tokenId`，与保存支付方式 token 是两个不同的 token。 - kind: rule text: 本地支付方式订阅忽略该字段：其订阅授权结果总会通过保存支付方式结果通知发送。 - kind: unsupported text: "`selfExecute=2` 自主管理订阅不支持。" required: - requestType - merchantCustId - selfExecute x-onerway-required: conditional x-onerway-condition: - 当 `subProductType=SUBSCRIBE` 时必填。 x-onerway-format: json_string txnOrderMsg: type: string description: 交易业务信息，包含 `returnUrl`、`notifyUrl`、`appId` 和商品信息等。浏览器、设备和持卡人 IP 信息由 Web SDK 采集，不在本请求中由商户传入。 contentMediaType: application/json contentSchema: type: object properties: returnUrl: type: string description: 客户付款完成后的同步返回地址。建议在 `returnUrl` 后拼接订单号或其他标识，并在客户同步返回时主动查询交易结果。 products: type: string description: 顾客购买的商品信息列表；商品金额、折扣和运费合计需要等于 `orderAmount`。 contentMediaType: application/json contentSchema: type: array items: type: object properties: name: type: string description: 商品名称。 price: type: string description: 商品单价。 num: type: string description: 商品数量。 productAvatarUrl: type: string description: 商品图片链接。 x-onerway-required: conditional x-onerway-condition: - "`stc pay`、`Tamara`、`Tabby`、`MADA` 必填。" desc: type: string description: 商品描述。 currency: type: string description: "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 货币代码。" type: type: string description: 商品类别；默认不填即普通商品。`virtual` 和 `physical` 用于区分是否涉及发货；`shipping_fee` 和 `discount` 可用于所有支付方式。 enum: - virtual - physical - shipping_fee - discount x-enum-descriptions: virtual: 虚拟商品。 physical: 实物商品。 shipping_fee: 运费商品项。 discount: 折扣商品项，金额需要传负数。 x-onerway-required: conditional x-onerway-condition: - "`stc pay`、`Tamara`、`Tabby`、`MADA` 必填；除 `shipping_fee` 和 `discount` 商品项外，每个商品项需传 `virtual` 或 `physical`。" retailerId: type: string description: 销售该商品的零售商标识。 x-onerway-required: conditional x-onerway-condition: - 传入 `retailers` 时必填。 x-onerway-constraints: - kind: consistency text: 取值必须命中 `retailers` 中的某一个 `retailerId`。 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: 店铺 ID，商户在 Onerway 入驻时生成并可在后台获取。 customerPlatform: type: string description: 商户平台标识，Web 端传网站域名，App 端传应用名称。 x-onerway-required: conditional x-onerway-condition: - "`stc pay`、`Tamara`、`Tabby`、`MADA` 必填。" periodValue: type: string description: 分期付款期数，应使用咨询分期期数接口返回的期数值。 x-onerway-required: conditional x-onerway-condition: - 外层 `subProductType=INSTALLMENT` 时必填。 notifyUrl: type: string description: 支付结果异步通知地址；商户收到 Webhook 通知后建议主动查询确认交易结果。 required: - returnUrl - products - appId - notifyUrl x-onerway-format: json_string txnType: type: string description: 要执行的支付操作类型；该字段与 `productType`、`subProductType` 共同定义交易模型，交易查询和异步通知也会返回。`REFUND`、`BIND_CARD` 不适用于本 SDK 下单接口。 enum: - SALE - AUTH x-enum-descriptions: SALE: 扣款型交易。与 `subProductType=DIRECT` / `SUBSCRIBE` / `INSTALLMENT` 组合时，分别用于普通支付、初始订阅或分期交易。 AUTH: 预授权型交易，先完成授权不立即请款。通常用于支持预授权的卡支付场景，仍需结合 `productType`、`subProductType` 和商户开通配置确认是否可用。 required: - merchantNo - merchantTxnId - orderAmount - orderCurrency - productType - sign - subProductType - txnOrderMsg - txnType examples: one-time-card: summary: 一次性 SDK 卡支付 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: SDK 托管月订阅支付 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: SDK 非托管日订阅支付 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 支付 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 预授权支付 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: 多零售商 marketplace SDK 支付 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: 配置自动分账通知的支付 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: 一次性 SDK 卡交易已创建 content: application/json: schema: type: object properties: respCode: type: string description: 响应码；`20000` 表示请求处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。 respMsg: type: string description: 响应码对应的可读说明。 data: type: object properties: transactionId: type: string description: Onerway 为本次交易生成的交易号，用于跟踪与查询。当前 Web SDK 使用 `paymentId` 初始化，不直接消费 `transactionId`。 paymentId: type: string description: 支付意图 ID，用于初始化当前 Web SDK；同一支付意图可包含多次交易尝试。 responseTime: type: - string - "null" description: 接口响应时间，格式 `yyyy-MM-dd HH:mm:ss`。 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: 交易完成时间，格式 `yyyy-MM-dd HH:mm:ss`。 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: 交易时区偏移量，格式 `±HH:mm`。 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: 原始订单金额，以交易币种计价；以十进制字符串返回，精度遵循提交的 `orderCurrency` 可接受的小数规则。 orderCurrency: type: string description: 下单币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。 txnAmount: type: - string - "null" description: 旧版到账金额字段。 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: 旧版结算币种字段。 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: 当前交易处理状态。SDK 下单同步响应是订单创建响应，支付尚未发生，此时为 `U`。 enum: - S - F - P - R - N - I - U x-enum-descriptions: S: 交易成功。 F: 交易失败。 P: 交易处理中。 R: 需要跳转以继续支付。 N: 交易已取消（含超时未支付关单）。 I: 交易审核或审批中。 U: SDK 交易已创建，但支付尚未开始或完成。 paymentStatus: type: string description: 支付意图级状态，反映同一 `paymentId` 下跨多次尝试的生命周期状态。 enum: - I - U - P - R - A - O - S - N x-enum-descriptions: I: 支付意图已初始化。 U: 支付意图待支付。 P: 支付意图处理中。 R: 支付意图需要跳转。 A: 支付意图已授权。 O: 支付意图仍打开。 S: 支付意图已成功。 N: 支付意图已关闭：超时未完成支付，包括下单后未支付关单与多次尝试均失败后关单。 redirectUrl: type: string description: 当前 Web SDK 使用 `paymentId` 初始化，不消费本字段。 contractId: type: - string - "null" description: 订阅合约号，标识订阅，是完成后续扣款的关键参数。 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: 用于订阅后续扣款或 token 支付的支付 token 标识。订阅 token 应从[订阅支付 Webhook](/zh/payments/api-reference/webhooks/subscription-payment)获取，已保存卡 token 应从[查询已保存 token](/zh/payments/api-reference/endpoints/list-saved-tokens)获取；两者均不能根据本次创建响应推断，也不可混用。两种 token 均需按 PCI 要求妥善保管。 x-onerway-value: nullable: true empty: true when: en: Empty in the synchronous SDK transaction creation response. zh: SDK 下单的同步创建响应中为空。 eci: type: - string - "null" description: 电子商务指示符（ECI），标识交易安全等级与责任转移。 x-onerway-value: nullable: true empty: true when: en: Has a value only for 3DS transactions. zh: 3DS 交易才有值。 periodValue: type: - string - "null" description: 分期付款期数。 x-onerway-value: nullable: true empty: true when: en: Has a value only for installment transactions. zh: 分期交易才有值。 codeForm: type: - string - "null" description: 支付码信息对象。 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: 供渲染支付界面元素的附加上下文。 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: 需执行的后续动作类型。 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: 订阅管理地址，买家可通过该地址查看和管理订阅。 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），可用于对账与查询。 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: 发卡行授权码，可用于对账与争议处理。 x-onerway-value: nullable: true empty: true when: en: Has a value after issuer authorization is approved. zh: 发卡行授权通过后才有值。 cardInfo: type: - string - "null" description: 卡信息（脱敏）对象，在卡信息可用时返回。 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: 交易失败或存在重试建议时返回的重试建议；非空值仅作为提示信息。 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: 响应签名字符串；当前不建议商户对响应验签。 description: SDK 下单创建响应的业务数据对象。同步响应只表示订单创建（`status=U`）。SDK 回调仅用于客户端交互，最终支付结果需以服务端 Webhook 或交易查询为准。 examples: one-time-card: summary: 一次性 SDK 卡交易已创建 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: SDK 托管月订阅已创建 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: SDK 非托管日订阅已创建 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 支付已创建 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 预授权交易已创建 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: marketplace SDK 交易已创建 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 ```