POST

创建 SDK 交易

该接口用于创建 SDK 交易，并获取用于初始化当前 Onerway Web SDK 的 paymentId。

billingInformationobject{16}可选{ email, country, ... }

可选的交易账单信息，包含客户账单地址和联系信息。可在创建交易时传入；业务流程需要且初始下单省略时，可在确认支付前通过更新 SDK 订单补充。传入该对象后，其内部字段原有的必填条件仍然生效。

merchantCustIdstring

条件：

旧版 Web SDK 保存卡流程使用 subProductType=TOKEN 时必填。
当前 Web SDK 的 DIRECT 支付需要向客户提供保存卡选项时必填。

客户在商户系统中的唯一标识，用于关联客户、已保存支付方式和交易信息。

示例：customer_12345

约束

范围: 63字符
规则: 当前 Web SDK 的 DIRECT 支付如需让客户选择是否在支付后保存卡，请传入本字段。保存卡由客户主动勾选，不会默认启用。
一致性: 后续支付中应对同一客户复用相同的服务端管理标识。
一致性: 订阅交易应以 subscription.merchantCustId 作为必填客户标识；若内外层同时传入，两者必须一致。

merchantNostring

Onerway 分配的商户号；获取方式参见接入准备。

示例：replace_with_merchant_no

约束

规则: 平台模式下传该笔交易所属子商户的商户号，而不是平台商户号；该子商户需已在 Onerway 完成报备。

merchantTxnIdstring

商户系统生成的每笔支付唯一交易标识，用于交易跟踪、对账和防重复处理。

merchantTxnOriginalIdstring可选

商户原始订单 ID，用于将多次 SDK 下单尝试关联到同一笔原始订单。用户支付前，商户可以用相同的 merchantTxnOriginalId 和不同的 merchantTxnId 再次下单，获得多个 transactionId；但实际能完成支付的只会是其中一个 merchantTxnOriginalId + merchantTxnId + transactionId 组合。用户一旦发生支付行为，再用相同 merchantTxnOriginalId 下单会因重复订单报错。

merchantTxnTimestring可选

商户发起交易的时间戳，格式为 yyyy-MM-dd HH:mm:ss；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。

merchantTxnTimeZonestring可选

merchantTxnTime 对应的时区偏移量；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。

示例：+08:00

metaDatastring可选

本次交易的商户自定义数据，必须是包含合法 JSON 的字符串；交易查询和异步通知会原样返回，未传入时其中的 metaData 为空。同时传入外层 metaData 与 subscription.metaData 时，以 subscription.metaData 为准。

orderAmountstring

指定货币的交易金额，使用十进制字符串。零小数币种必须表示整数金额，可带 .00 这类全 0 小数；非零小数会被拒绝。格式要求详见币种与金额校验。

示例：99.99

orderCurrencystring

ISO 4217 三位字母货币代码，需与 orderAmount 匹配。

示例：USD

osTypestring

条件：当 paymentMode 不是 WEB 时必填。

App 与移动浏览器支付的操作系统类型；普通 Web SDK 支付请省略。

示例：IOS

可选值

IOS: iOS 设备。
ANDROID: Android 设备。

paymentModestring可选默认WEB

可选的支付模式。Web SDK 接入通常省略该字段，无需区分桌面和移动浏览器；传入非 WEB 值时，osType 必填。

示例：WEB

可选值

WEB: 浏览器支付。
APP: 原生移动 App 支付。
WAP: 移动浏览器支付。

paymentMethodOptionsobject{6}可选{ card, share }

支付方式配置选项；SDK 下单支持 card 与 share 对象。

productTypestring默认ALL

SDK 下单的支付方式范围。ALL 为默认值，涵盖卡支付、Google Pay、Apple Pay 及商户已开通的其他方式。CARD 为旧版 SDK 使用的取值，不推荐新接入商户使用。

示例：ALL

可选值

ALL: 所有支持的支付方式。新接入商户的默认值；涵盖卡支付、Google Pay、Apple Pay 及商户已开通的其他方式。
CARD: 仅卡支付范围。旧版 SDK 使用的取值，不推荐新接入商户使用。

retailersarray<object>[3]可选新增{ retailerId, retailerName, ... }

marketplace 交易的零售商信息；订单包含的每个零售商各传入一个对象。

自 2026-08-10marketplace 零售商信息的新增字段。

约束

规则: 适用于 marketplace / 平台模式下商品由第三方零售商销售的场景；仅销售自有商品的商户无需传入。
一致性: 传入该字段后，txnOrderMsg.products 中的每个商品都需要传入 retailerId，且取值需命中此处列出的某个零售商。

risk3dsStrategystring可选默认DEFAULT

3DS 风控策略；默认值为 DEFAULT。SDK 下单支持 DEFAULT、INNER、NONE，不支持传 EXTERNAL；如需指定非默认策略，需提前联系 Onerway 确认配置。

示例：DEFAULT

可选值

DEFAULT: 默认策略，由 Onerway 根据交易、商户配置和风控判断是否发起 3DS 验证。
INNER: 强制使用 Onerway 托管的 3DS 验证流程。
NONE: 不走 3DS 验证；是否可用需结合商户配置和风控要求确认。

shippingInformationobject{16}可选{ email, country, ... }

可选的交易配送信息，包含客户配送地址和联系信息。可在创建交易时传入；业务流程需要且初始下单省略时，可在确认支付前通过更新 SDK 订单补充。传入该对象后，其内部字段原有的必填条件仍然生效。

signstring

请求签名字符串；生成方式详见请求签名。

subProductTypestring

所选支付方式范围下的交易处理模式，需要与 productType 和 txnType 配合定义交易模型。

示例：DIRECT

可选值

DIRECT: 普通 SDK 支付，按 txnType 执行一次性扣款或预授权。
TOKEN: 旧版 Web SDK 保存卡模式。仅当所接入的旧版 Web SDK 契约明确要求 TOKEN 时使用；当前 Web SDK 的保存卡选项改用 DIRECT 并传入 merchantCustId。
SUBSCRIBE: 初始订阅交易，用于通过 SDK 创建订阅合约；需同时传入 subscription，后续扣款、取消和更新需走对应订阅接口。

约束

规则: 当前 Web SDK 如需在支付后提供保存卡选项，应使用 DIRECT 并传入 merchantCustId；是否保存由客户在 SDK 内主动选择。
不支持: 本接口不要把 BIND_CARD 作为 txnType 传入。

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

条件：当 subProductType=SUBSCRIBE 时必填。

用于通过 SDK 创建或初始化订阅的订阅信息，包含订阅频率、执行方式和其他配置。本接口仅用于初始订阅；订阅后续扣款、取消、更新需走对应订阅接口。selfExecute=1 表示托管订阅；selfExecute=2 表示自主管理订阅。

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

交易业务信息，包含 returnUrl、notifyUrl、appId 和商品信息等。浏览器、设备和持卡人 IP 信息由 Web SDK 采集，不在本请求中由商户传入。

txnTypestring

要执行的支付操作类型；该字段与 productType、subProductType 共同定义交易模型，交易查询和异步通知也会返回。REFUND、BIND_CARD 不适用于本 SDK 下单接口。

示例：SALE

可选值

SALE: 扣款型交易。与 subProductType=DIRECT / SUBSCRIBE / INSTALLMENT 组合时，分别用于普通支付、初始订阅或分期交易。
AUTH: 预授权型交易，先完成授权不立即请款。通常用于支持预授权的卡支付场景，仍需结合 productType、subProductType 和商户开通配置确认是否可用。

respCodestring

响应码；20000 表示请求处理成功，其余为错误码。完整码表见响应码。

respMsgstring

响应码对应的可读说明。

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

SDK 下单创建响应的业务数据对象。同步响应只表示订单创建（status=U）。SDK 回调仅用于客户端交互，最终支付结果需以服务端 Webhook 或交易查询为准。

该接口暂未记录错误响应。

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

创建 SDK 交易

该接口用于创建 SDK 交易，并获取用于初始化当前 Onerway Web SDK 的 paymentId。

billingInformationobject{16}可选{ email, country, ... }

merchantCustIdstring

条件：

旧版 Web SDK 保存卡流程使用 subProductType=TOKEN 时必填。
当前 Web SDK 的 DIRECT 支付需要向客户提供保存卡选项时必填。

客户在商户系统中的唯一标识，用于关联客户、已保存支付方式和交易信息。

示例：customer_12345

约束

范围: 63字符
规则: 当前 Web SDK 的 DIRECT 支付如需让客户选择是否在支付后保存卡，请传入本字段。保存卡由客户主动勾选，不会默认启用。
一致性: 后续支付中应对同一客户复用相同的服务端管理标识。
一致性: 订阅交易应以 subscription.merchantCustId 作为必填客户标识；若内外层同时传入，两者必须一致。

merchantNostring

Onerway 分配的商户号；获取方式参见接入准备。

示例：replace_with_merchant_no

约束

规则: 平台模式下传该笔交易所属子商户的商户号，而不是平台商户号；该子商户需已在 Onerway 完成报备。

merchantTxnIdstring

商户系统生成的每笔支付唯一交易标识，用于交易跟踪、对账和防重复处理。

merchantTxnOriginalIdstring可选

merchantTxnTimestring可选

商户发起交易的时间戳，格式为 yyyy-MM-dd HH:mm:ss；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。

merchantTxnTimeZonestring可选

merchantTxnTime 对应的时区偏移量；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。

示例：+08:00

metaDatastring可选

orderAmountstring

示例：99.99

orderCurrencystring

ISO 4217 三位字母货币代码，需与 orderAmount 匹配。

示例：USD

osTypestring

条件：当 paymentMode 不是 WEB 时必填。

App 与移动浏览器支付的操作系统类型；普通 Web SDK 支付请省略。

示例：IOS

可选值

IOS: iOS 设备。
ANDROID: Android 设备。

paymentModestring可选默认WEB

可选的支付模式。Web SDK 接入通常省略该字段，无需区分桌面和移动浏览器；传入非 WEB 值时，osType 必填。

示例：WEB

可选值

WEB: 浏览器支付。
APP: 原生移动 App 支付。
WAP: 移动浏览器支付。

paymentMethodOptionsobject{6}可选{ card, share }

支付方式配置选项；SDK 下单支持 card 与 share 对象。

productTypestring默认ALL

示例：ALL

可选值

ALL: 所有支持的支付方式。新接入商户的默认值；涵盖卡支付、Google Pay、Apple Pay 及商户已开通的其他方式。
CARD: 仅卡支付范围。旧版 SDK 使用的取值，不推荐新接入商户使用。

retailersarray<object>[3]可选新增{ retailerId, retailerName, ... }

marketplace 交易的零售商信息；订单包含的每个零售商各传入一个对象。

自 2026-08-10marketplace 零售商信息的新增字段。

约束

规则: 适用于 marketplace / 平台模式下商品由第三方零售商销售的场景；仅销售自有商品的商户无需传入。
一致性: 传入该字段后，txnOrderMsg.products 中的每个商品都需要传入 retailerId，且取值需命中此处列出的某个零售商。

risk3dsStrategystring可选默认DEFAULT

3DS 风控策略；默认值为 DEFAULT。SDK 下单支持 DEFAULT、INNER、NONE，不支持传 EXTERNAL；如需指定非默认策略，需提前联系 Onerway 确认配置。

示例：DEFAULT

可选值

DEFAULT: 默认策略，由 Onerway 根据交易、商户配置和风控判断是否发起 3DS 验证。
INNER: 强制使用 Onerway 托管的 3DS 验证流程。
NONE: 不走 3DS 验证；是否可用需结合商户配置和风控要求确认。

shippingInformationobject{16}可选{ email, country, ... }

signstring

请求签名字符串；生成方式详见请求签名。

subProductTypestring

所选支付方式范围下的交易处理模式，需要与 productType 和 txnType 配合定义交易模型。

示例：DIRECT

可选值

DIRECT: 普通 SDK 支付，按 txnType 执行一次性扣款或预授权。
TOKEN: 旧版 Web SDK 保存卡模式。仅当所接入的旧版 Web SDK 契约明确要求 TOKEN 时使用；当前 Web SDK 的保存卡选项改用 DIRECT 并传入 merchantCustId。
SUBSCRIBE: 初始订阅交易，用于通过 SDK 创建订阅合约；需同时传入 subscription，后续扣款、取消和更新需走对应订阅接口。

约束

规则: 当前 Web SDK 如需在支付后提供保存卡选项，应使用 DIRECT 并传入 merchantCustId；是否保存由客户在 SDK 内主动选择。
不支持: 本接口不要把 BIND_CARD 作为 txnType 传入。

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

条件：当 subProductType=SUBSCRIBE 时必填。

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

交易业务信息，包含 returnUrl、notifyUrl、appId 和商品信息等。浏览器、设备和持卡人 IP 信息由 Web SDK 采集，不在本请求中由商户传入。

txnTypestring

示例：SALE

可选值

SALE: 扣款型交易。与 subProductType=DIRECT / SUBSCRIBE / INSTALLMENT 组合时，分别用于普通支付、初始订阅或分期交易。
AUTH: 预授权型交易，先完成授权不立即请款。通常用于支持预授权的卡支付场景，仍需结合 productType、subProductType 和商户开通配置确认是否可用。

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

响应码；20000 表示请求处理成功，其余为错误码。完整码表见响应码。

respMsgstring

响应码对应的可读说明。

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"
  }
}

该接口暂未记录错误响应。

创建直连交易

创建直连交易，支持卡、钱包、已保存 token、订阅、分期和本地支付方式。

生成卡 token

在 PCI DSS 合规接入中生成卡 token，并通过 notifyUrl 接收最终 tokenization 结果。

请求

响应

请求

请求示例

响应

响应示例