Onerway
POST

创建直连交易

查看 Markdown
该接口用于创建服务端到服务端的直连交易，支持卡、钱包、已保存 token、订阅、分期和本地支付方式。

请求

条件：除订阅后续扣款 / 更新（subscription.requestType=1 或 2）外必填。
交易账单信息，包含客户账单地址和联系信息。
条件：
  • 商户自行采集卡信息支付时必填。
  • Apple Pay / Google Pay 商户自解密模式时必填。
  • 卡 token 支付（subProductType=TOKEN）时必填；与 tokenInfo 一起提交 cardInfo.cvv。
  • Google Pay Onerway 代解密模式下，商户自行采集 PAN_ONLY 支付的 CVC 时必填；此时 cardInfo 只包含 cvv，并与 tokenInfo 一起提交。
卡支付信息。商户自行采集卡信息（含卡 token 支付时的 cardInfo.cvv）需具备 PCI DSS 合规资质。钱包支付可选择通过 cardInfo 传商户自解密结果，或通过 tokenInfo 交由 Onerway 代解密；只有 Google Pay PAN_ONLY token 需补 CVC 时两者同时提交，此时 cardInfo 只含 cvv。
约束
规则
Google Pay 商户自解密模式同样需按 Onerway 要求配置 allowedAuthMethods，详见 tokenInfo 的约束说明。
merchantCustIdstring条件必填
条件：卡 token 支付（subProductType=TOKEN）和订阅场景必填。
客户在商户系统中的唯一标识。订阅交易中应以 subscription.merchantCustId 作为订阅客户标识；外层 merchantCustId 可不传，若同传则必须与 subscription.merchantCustId 保持一致。
示例：customer_12345
merchantNostring必填
Onerway 分配的商户号；获取方式参见接入准备。
示例：800209
约束
规则
平台模式下传该笔交易所属子商户的商户号，而不是平台商户号；该子商户需已在 Onerway 完成报备。
merchantTxnIdstring必填
商户系统生成的每笔支付唯一交易标识，用于交易跟踪、对账和防重复处理。
merchantTxnTimestring可选
商户发起交易的时间戳，格式为 yyyy-MM-dd HH:mm:ss；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。
merchantTxnTimeZonestring可选
商户交易时间的时区偏移量；未传时 Onerway 默认使用 UTC+8 时区记录交易时间。
示例：+08:00
metaDatastring可选
本次交易的商户自定义数据，必须是包含合法 JSON 的字符串；交易查询和异步通知会原样返回，未传入时其中的 metaData 为空。
条件：当 risk3dsStrategy=EXTERNAL 时必填。
外部 3DS / MPI 认证结果。直连接入可使用自有或外部 MPI / 3DS Server 完成 3DS 认证，并将认证结果原样回传。
条件：当 productType=LPMS 时必填。
本地支付方式信息，包含所选本地支付方式的配置参数。
orderAmountstring必填
指定货币的交易金额，使用十进制字符串。零小数币种必须表示整数金额，可带 .00 这类全 0 小数；非零小数会被拒绝。格式要求详见币种与金额校验。
示例：99.99
orderCurrencystring必填
ISO 4217 三位字母货币代码，需与 orderAmount 匹配。
示例：USD
osTypestring条件必填
条件：当 paymentMode 不是 WEB 时必填。
移动端和应用交易的操作系统类型。
示例：IOS
可选值
IOS
iOS 设备。
ANDROID
Android 设备。
paymentModestring可选默认WEB
交易平台或环境的支付模式；默认 WEB。
示例：WEB
可选值
WEB
桌面浏览器支付。
APP
原生移动 App 支付。
WAP
移动浏览器支付。
支付方式配置选项；直连交易支持 card 与 share 对象。
productTypestring必填
支付方式范围。直连接口必须明确选择 CARD 或 LPMS；ALL 属于收银台聚合展示概念，本接口不支持。
示例：CARD
可选值
CARD
卡支付范围，包含商户自行采集卡信息的卡支付以及 Apple Pay / Google Pay 钱包支付。
LPMS
本地支付方式范围；使用该取值时需同时传入 lpmsInfo。
marketplace 交易的零售商信息；订单包含的每个零售商各传入一个对象。
自 2026-08-10marketplace 零售商信息的新增字段。
约束
规则
适用于 marketplace / 平台模式下商品由第三方零售商销售的场景；仅销售自有商品的商户无需传入。
一致性
传入该字段后，txnOrderMsg.products 中的每个商品都需要传入 retailerId，且取值需命中此处列出的某个零售商。
risk3dsStrategystring可选默认DEFAULT
3DS 风控策略；直连接入支持 DEFAULT、INNER、NONE、EXTERNAL。选择 EXTERNAL 时必须同时传入 mpiInfo 回传外部 3DS 认证结果；如需指定非默认策略，需提前联系 Onerway 确认配置。
示例：DEFAULT
可选值
DEFAULT
默认策略，由 Onerway 根据交易、商户配置和风控判断是否发起 3DS 验证。
INNER
强制使用 Onerway 托管的 3DS 验证流程。
NONE
不走 3DS 验证；是否可用需结合商户配置和风控要求确认。
条件：除订阅后续扣款 / 更新（subscription.requestType=1 或 2）外必填。
交易配送信息，包含客户配送地址和联系信息。
signstring必填
请求签名字符串；生成方式详见请求签名。
subProductTypestring必填
所选支付方式范围下的交易处理模式，需要与 productType 和 txnType 配合定义交易模型。
示例：DIRECT
可选值
DIRECT
普通直连支付，按 productType 与 txnType 执行一次性扣款、钱包支付、本地支付或预授权。
TOKEN
卡 token 支付，使用已保存的卡 token 扣款；需配合客户标识，并必须提交 cardInfo.cvv。
SUBSCRIBE
订阅交易；通过 subscription.requestType 支持初始订阅、商户自主管理后续扣款与托管订阅计划更新。
条件：当 subProductType=SUBSCRIBE 时必填。
订阅信息。本直连接口支持初始订阅（requestType=0）、后续扣款（requestType=1，自主管理订阅的本期扣款）和订阅更新（requestType=2，托管订阅计划升级 / 降级）。
条件：
  • Apple Pay / Google Pay Onerway 代解密模式时必填。
  • 卡 token 支付（subProductType=TOKEN）时必填。
以 token 凭据发起支付。钱包场景传钱包 SDK 返回的加密 token，由 Onerway 代解密。卡 token 支付传生成卡 token 或保存支付方式返回的卡 token；订阅 token 通过 subscription.tokenId 传入，不在此处。
约束
规则
Onerway 要求 Google Pay CARD 支付方式参数中的 allowedAuthMethods 同时包含 PAN_ONLY 和 CRYPTOGRAM_3DS。该要求适用于 Onerway 代解密和商户自解密两种模式；商户自解密时通过 cardInfo 提交解密后的支付数据。
规则
Google Pay 由 Onerway 代解密时对应 PAYMENT_GATEWAY tokenization：Google Pay 前端的 gateway 与 gatewayMerchantId 参数分别取查询可用支付方式返回的 gatewayName 与 gatewayMerchantId。该 token 以 Onerway 密钥加密，商户无法自行解密。
规则
Google Pay Onerway 代解密模式下，创建交易前可选择调用检查 Google Pay PAN_ONLY token。提交 PAN_ONLY token 时，若未传 cardInfo.cvv，无论是否已调用检查接口，交易响应均返回 data.status=R 和 data.redirectUrl。商户需引导用户跳转至 data.redirectUrl，在 Onerway 托管页面输入 CVC；若自行采集 CVC，则通过 cardInfo.cvv 与 tokenInfo 一起提交。
条件：除订阅后续扣款 / 更新（subscription.requestType=1 或 2）外必填。
交易业务信息，包含 returnUrl、notifyUrl、appId、商品信息以及由商户采集的浏览器、设备和持卡人 IP 信息。
txnTypestring必填
要执行的支付操作类型；该字段与 productType、subProductType 共同定义交易模型。REFUND 与 BIND_CARD 不在本下单接口范围。
示例：SALE
可选值
SALE
扣款型交易。与 subProductType=DIRECT / TOKEN / SUBSCRIBE / INSTALLMENT 组合时，分别用于普通支付、token 支付、订阅或分期交易。
AUTH
预授权交易，先冻结持卡人卡上金额、暂不扣款；适用于商户自行采集卡信息支付和卡 token 支付，不适用于 LPMS、订阅或分期。

请求示例

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

响应

respCodestring
响应码；20000 表示请求处理成功，其余为错误码。完整码表见响应码。
respMsgstring
响应码对应的可读说明。
直连交易响应的业务数据对象。同步响应即可返回终态，也可能要求商户跳转或展示后续动作。

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "2064485863093829632",
    "paymentId": "2064485863068663808",
    "responseTime": "2026-06-14 10:30:02",
    "txnTime": null,
    "txnTimeZone": null,
    "orderAmount": "99.99",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "status": "R",
    "paymentStatus": "R",
    "redirectUrl": "https://developers.onerway.com/example-direct-redirect",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL",
    "subscriptionManageUrl": null,
    "rrn": null,
    "authorizationCode": null,
    "cardInfo": null,
    "sign": "{{SIGN}}"
  }
}
该接口暂未记录错误响应。

创建收银台支付

创建收银台支付并获取跳转到 Onerway 托管页面的 redirectUrl。

创建 SDK 交易

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