Onerway
POST

创建收银台支付

查看 Markdown
该接口用于创建收银台支付，并获取跳转到 Onerway 托管支付页面的 redirectUrl。

请求

交易账单信息，包括客户账单地址与联系方式。
卡支付信息。收银台场景当前仅支持 holderName；提供后可预填持卡人姓名。
本地支付方式信息。结合 productType=ALL 使用时，设置 lpmsType 后收银台仅展示指定本地支付方式。
merchantCustIdstring可选
客户在商户系统中的唯一标识。
示例：customer_12345
约束
规则
非订阅收银台场景下，商户如希望降低复购摩擦，可传入该字段，收银台会向客户提供保存卡信息的选项。
一致性
订阅交易中应以 subscription.merchantCustId 作为订阅客户标识；外层 merchantCustId 可不传，若同传则必须与 subscription.merchantCustId 保持一致。
merchantNostring必填
Onerway 分配的商户号；获取方式参见接入准备。
示例：demo_merchant_no
约束
规则
平台模式下传该笔交易所属子商户的商户号，而不是平台商户号；该子商户需已在 Onerway 完成报备。
merchantTxnIdstring必填
商户系统生成的每笔支付唯一交易标识，用于交易跟踪、对账和防重复处理。
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 为 APP 或 WAP 时必填。
移动端和应用交易的操作系统类型。收银台建议使用 WEB 模式，通常不建议传此字段。
示例：IOS
可选值
IOS
iOS 设备。
ANDROID
Android 设备。
paymentModestring可选默认WEB
交易平台或环境的支付模式；收银台建议使用默认值 WEB。
示例：WEB
可选值
WEB
桌面浏览器支付。
APP
原生移动 App 支付。
WAP
移动浏览器支付。
支付方式配置选项。收银台支持 card 与 share 对象。
productTypestring必填
收银台支付方式展示范围，用于决定客户在收银台可选择的支付方式类别；后续交易处理方式还需结合 subProductType 和 txnType 判断。
示例：ALL
可选值
ALL
聚合收银台，展示当前商户和交易条件下可用的所有支付方式；如同时传入 lpmsInfo.lpmsType，则仅展示指定本地支付方式。
CARD
仅展示卡支付方式；是否支持预授权、订阅、分期或保存卡等能力，还需结合 subProductType、txnType 和商户开通配置确认。
marketplace 交易的零售商信息；订单包含的每个零售商各传入一个对象。
自 2026-08-10marketplace 零售商信息的新增字段。
约束
规则
适用于 marketplace / 平台模式下商品由第三方零售商销售的场景；仅销售自有商品的商户无需传入。
一致性
传入该字段后，txnOrderMsg.products 中的每个商品都需要传入 retailerId，且取值需命中此处列出的某个零售商。
risk3dsStrategystring可选默认DEFAULT
收银台交易的 3DS 风控策略。
示例：DEFAULT
可选值
DEFAULT
默认策略，由 Onerway 根据交易、商户配置和风控判断是否发起 3DS 验证。
INNER
强制使用 Onerway 托管的 3DS 验证流程。
NONE
不走 3DS 验证；是否可用需结合商户配置和风控要求确认。
约束
不支持
收银台不支持 EXTERNAL。
规则
如需指定非默认策略，需提前联系 Onerway 确认配置。
交易收货信息，包括客户收货地址与联系方式。
signstring必填
请求签名字符串；生成方式详见请求签名。
subProductTypestring必填
所选支付方式范围下的交易处理模式。
示例：DIRECT
可选值
DIRECT
普通收银台支付，按 txnType 执行一次性扣款或预授权。
SUBSCRIBE
初始订阅交易，用于通过收银台创建订阅合约；需同时传入 subscription，后续扣款、取消和更新需走对应订阅接口。
INSTALLMENT
分期交易；需在 txnOrderMsg.periodValue 中传入咨询分期期数接口返回的期数值。
约束
一致性
需要与 productType 和 txnType 配合定义交易模型。
不支持
收银台不支持 TOKEN。
规则
收银台如需让客户保存支付信息，可在非订阅场景传入 merchantCustId，或在托管卡订阅场景使用 subscription.bindCard。
条件：当 subProductType=SUBSCRIBE 时必填。
用于通过收银台创建或初始化订阅的信息。本接口仅用于初始订阅；订阅后续扣款、取消、更新需走对应订阅接口。selfExecute=1 表示托管订阅；selfExecute=2 表示自主管理订阅。
交易业务信息，包含 returnUrl、notifyUrl、appId 和商品信息等。浏览器、设备和持卡人 IP 信息由收银台页面侧采集，不在本请求中由商户传入。
txnTypestring必填
要执行的支付操作类型；该字段与 productType、subProductType 共同定义交易模型，交易查询和异步通知也会返回。
示例：SALE
可选值
SALE
扣款型交易。与 subProductType=DIRECT / SUBSCRIBE / INSTALLMENT 组合时，分别用于普通支付、初始订阅或分期交易。
AUTH
预授权型交易，先完成授权不立即请款。通常用于支持预授权的卡支付场景，仍需结合 productType、subProductType 和商户开通配置确认是否可用。

请求示例

curl -X POST 'https://sandbox-acq.onerway.com/txn/payment' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "billingInformation": "{\"country\":\"US\",\"email\":\"customer@test.com\",\"province\":\"CA\"}",
  "cardInfo": "{\"holderName\":\"Test Cardholder\"}",
  "merchantCustId": "custId_1784021156",
  "merchantNo": "replace_with_merchant_no",
  "merchantTxnId": "card-4f71d2ae-4d0b-4fc2-8f2c-e450cf735baf",
  "merchantTxnTime": "2025-08-21 10:17:31",
  "orderAmount": "1",
  "orderCurrency": "USD",
  "productType": "CARD",
  "shippingInformation": "{\"country\":\"US\",\"email\":\"customer@test.com\",\"province\":\"CA\"}",
  "sign": "4ee2d1398368a3cad281e97614fc134418922400f61a34c1fc1e81eca40002ba",
  "subProductType": "DIRECT",
  "txnOrderMsg": "{\"appId\":\"replace_with_app_id\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"test product\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"1\\\",\\\"type\\\":\\\"\\\"}]\",\"returnUrl\":\"https://developers.onerway.com/example-return\",\"notifyUrl\":\"https://developers.onerway.com/example-notify\"}",
  "txnType": "SALE"
}'

响应

respCodestring
响应码；20000 表示请求处理成功，其余为错误码。完整码表见响应码。
respMsgstring
响应码对应的可读说明。
收银台会话创建响应的业务数据对象。

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "2076961389037359104",
    "merchantTxnId": "card-4f71d2ae-4d0b-4fc2-8f2c-e450cf735baf",
    "merchantNo": "replace_with_merchant_no",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "1.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "txnTimeZone": null,
    "status": "U",
    "paymentId": "2076961389016387584",
    "paymentStatus": "U",
    "reason": null,
    "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=bb02fff76ddf4ea9b021e4cd738e13e3",
    "sign": "3607ed6b158396e7a16574e2d62d5abb4b0157fa1e7321714438749488eb2f12",
    "contractId": "",
    "tokenId": null,
    "eci": null,
    "transactionOrderNo": null,
    "periodValue": null,
    "lpmsType": null,
    "qrCode": null,
    "subscriptionManageUrl": null,
    "tokenization": null,
    "linkName": null,
    "itemName": null
  }
}
该接口暂未记录错误响应。

退款

申请退款、处理退款结果与审核拒绝通知，并在需要时查询结果或取消尚未获批的退款申请。

创建直连交易

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