收银台支付

收银台支付：顾客从商家网站或应用程序重定向到支付供应商的托管页面进行支付。

Content-Type: application/json; charset=UTF-8 ❌
Content-Type: application/json ✅

请求参数

POST

销售虚拟商品的商户 必须提前与我们沟通。

名称	类型	长度	必填	签名	描述
merchantNo	String	20	Yes	Yes	商户号，由Onerway分配，在Onerway后台获取
merchantTxnId	String	64	Yes	Yes	顾客每次付款的订单号，必须保证单号唯一
merchantTxnTime	String	/	No	Yes	商户交易订单发生的时间。 格式为 yyyy-MM-dd HH:mm:ss
merchantTxnTimeZone	String	64	No	Yes	商户交易订单发生的时区。
merchantTxnOriginalId	String	128	No	Yes	商家生成的主订单号，单号可以重复，但重复的单号只有一笔可以成功。
productType	String	16	Yes	Yes	产品类型，请参阅
subProductType	String	16	Yes	Yes	子产品类型，请参阅
txnType	String	16	Yes	Yes	交易类型，
orderAmount	String	19	Yes	Yes	订单金额，以"元"为单位。
orderCurrency	String	8	Yes	Yes	交易订单的货币。 ISO 4217货币代码
subscription	String	/	No	Yes	订阅付款所需的订阅信息。 格式为 json 字符串。 请参阅对象
mpiInfo	String	/	No	Yes	mpi信息，3ds验证结果集，risk3dsStrategy为EXTERNAL时需要。 格式为 json 字符串。 请参阅对象
txnOrderMsg	String	/	Yes	Yes	交易业务信息，除订阅复购外必填。 格式为 json 字符串。 请参阅对象
cardInfo	String	/	No	Yes	交易卡信息。 格式为 json 字符串。 请参阅对象
billingInformation	String	/	Yes	Yes	交易账单信息，格式为 json 字符串。 请参阅对象
shippingInformation	String	/	Yes	Yes	交易邮寄信息，格式为 json 字符串。 请参阅对象
lpmsInfo	String	/	No	Yes	本地支付方式信息，格式为 json 字符串。 请参阅对象
sign	String	/	Yes	No	签名字符串，请参阅签名接口

TxnOrderMsg

名称	类型	长度	必填	描述
returnUrl	String	256	Yes	同步返回地址，顾客完成3ds挑战后，会通过这个地址重定向回商家的指定页面。
products	String	1024	Yes	顾客购买的商品信息列表，请参考下方Products对象
transactionIp	String	64	Yes	持卡人交易IP
appId	String	20	Yes	店铺ID，商家在Onerway入驻网站/应用程序时，会生成一个与该网站/应用程序的唯一ID。 该ID在Onerway后台获取。
javaEnabled	Boolean	/	Yes	持卡人浏览器是否开启java，获取方式：window.navigator.javaEnabled()
colorDepth	String	64	Yes	持卡人屏幕色深，获取方式：window.screen.colorDepth
screenHeight	String	64	Yes	持卡人的屏幕分辨率，获取方式：window.screen.height
screenWidth	String	64	Yes	持卡人的屏幕分辨率，获取方式：window.screen.width
timeZoneOffset	String	64	Yes	持卡人浏览器的时区，获取方式：((new Date()).getTimezoneOffset()).toString()
accept	String	2048	Yes	持卡人浏览器的 Accept 请求头
userAgent	String	2048	Yes	持卡人的浏览器类型，获取方式：window.navigator.userAgent
contentLength	String	64	Yes	持卡人浏览器内容长度头部以外的内容长度
language	String	64	Yes	持卡人浏览器的语言，获取方式：window.navigator.language
periodValue	String	/	No	分期付款期数。对应咨询分期期数接口返回的期数值。当 subProductType 为 INSTALLMENT 时必填。
notifyUrl	String	256	No	通知地址。详见通知
billAddress	String	64	No	收银台展示的网址

Products

名称	类型	长度	必填	描述
name	String	256	Yes	商品名称
price	String	1024	Yes	商品单价。
num	String	20	Yes	商品数量。
desc	String	1024	No	商品描述
currency	String	256	Yes	商品价格对应得货币，请参考 ISO_3166
type	String	256	No	商品类型。请参考

products 必须为JSON字符串格式

示例：

如果type为 discount，折扣金额需要传负数

一般情况

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\"

有折扣

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"

有运费

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"}]\"

有折扣和运费

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"

要注意的是 price * num（商品金额）+ price * num（折扣金额）- price * num（运费） = orderAmount（订单交易金额）

TxnCardInfo

名称	类型	长度	必填	描述
holderName	String	48	No	持卡人姓名

Subscription

托管订阅（自动扣款）

订阅测试卡

无摩擦3ds-成功

卡号：4000000000002701
有效期：05/26
CVV：123
持卡人姓名：CL BRW2

无摩擦3ds-失败

卡号：5200000000001013
有效期：05/26
CVV：123
持卡人姓名：CL BRW2

3ds-成功

卡号：4000000000001091
有效期：05/26
CVV：123
持卡人姓名：CL BRW2

3ds-失败

卡号：4000000000001109
有效期：05/26
CVV：123
持卡人姓名：CL BRW2

3ds-authentication 不可用

卡号：5200000000001039
有效期：05/26
CVV：123
持卡人姓名：CL BRW2

订阅首购

升降级

名称	类型	长度	必填	描述
requestType	String	1	Yes	订阅请求类型，请参阅
merchantCustId	String	40	Yes	商户系统中的用户唯一标识，用于关联用户与订阅信息。此ID将用于订阅的创建、查询和管理，请确保其在商户系统中的唯一性。
productName	String	256	No	订阅产品名称，用于区分不同的订阅服务或套餐。不传入时，每个用户仅能创建一个订阅；传入时，同一用户可订阅多个不同产品。
frequencyType	String	1	No	订阅周期单位： D-天 M-月 Y-年 决定账单周期的基本时间单位。
frequencyPoint	String	2	Yes	建议的订阅周期值。
cycleCount	int	256	No	循环期数，支持1-100。
expireDate	String	10	Yes	订阅终止日期，格式为yyyy-MM-dd。超过此日期后，托管系统将不再触发扣款。
mode	String	1	Yes	签约模式： 1 - 先签约后扣款，需分两步完成 2 - 签约并立即扣款，一步完成（默认值）
selfExecute	String	1	Yes	订阅扣款模式： 1 - 系统自动扣款（推荐）：由支付系统按照设定的频率自动执行周期性扣款 2 - 商户触发扣款：需要商户系统主动调用API发起每期扣款 非托管订阅
bindCard	String	300	No	订阅信用卡绑定选项： true - 完成订阅并将卡信息绑定到用户ID false - 仅完成订阅但不绑定卡信息
trialFromPlan	String	256	No	试用期计费模式: 0 - 试用期不计入订阅计划（不收费） 1 - 试用期计入订阅计划（收费）
trialDays	int	256	No	试用期天数，支持范围 3-365 天。当设置试用期时，与 trialEnd 二选一。
trialEnd	String	256	No	试用期结束日期，格式为yyyy-MM-dd。当设置试用期时，与trialDays二选一。
notificationEmail	String	256	No	买家订阅后邮件通知地址（含订阅扣款成功、取消订阅等其他邮件通知）。
metaData	String	2048	No	商户自定义信息，用于存储业务数据。支持JSON格式，在查询订阅时原样返回。

trialDays

// 试用首购 - 每天扣款一次，共30天，前3天为试用期且包含在订阅计划内，试用结束后自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"自动扣30天-试用3天（含）-1天1次\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"1\",\"trialDays\":3,\"notificationEmail\":\"abel.wang@onerway.com\"}"

trialEnd

// 试用首购 - 每天扣款一次，共33天，前3天为试用期且不包含在订阅计划内，试用结束后自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"自动扣30天-试用1天（不含）-1天1次\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"0\",\"trialEnd\":\"2024-11-07\",\"notificationEmail\":\"abel.wang@onerway.com\"}"

无试用

// 非试用首购 - 每天扣款一次直到指定过期日期（2024-12-04），无试用期，立即开始自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522099\",\"productName\":\"自动扣30天-无试用-1天1次-到期时间6\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\"}"

仅签约模式

// 仅签约模式 - 每月扣款一次，签约但不立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522100\",\"productName\":\"仅签约-1月1次\",\"frequencyType\":\"M\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"mode\":\"1\"}"

升级

// 升降级 - 每天扣款一次，共30天，立即升级, 补差价30
"subscription": "{\"requestType\":\"2\",\"tokenId\":\"tokenId_xxx\",\"contractId\":\"contractId_xxx\",\"productName\":\"订阅升级-立即生效并补差价\",\"proration\":\"30\",\"merchantCustId\":\"custId_xxx\"}"

非托管订阅（商户发起扣款）

注意

• 商户需自行管理订阅周期和发起扣款操作
• 不支持升降级、邮件通知、订阅管理页面
• 订阅频率由商户控制，仅支持按天

首次订阅

续期订阅

名称	类型	长度	必填	描述
requestType	String	1	Yes	订阅请求类型：固定值为0（首购）。
merchantCustId	String	40	Yes	商户系统中的用户唯一标识，用于关联用户与订阅信息。此ID将用于订阅的创建、查询和管理，请确保其在商户系统中的唯一性。
productName	String	256	No	订阅产品名称，用于区分不同的订阅服务或套餐。不传入时，每个用户仅能创建一个订阅；传入时，同一用户可订阅多个不同产品。
frequencyType	String	1	No	订阅周期单位：非托管订阅模式下仅支持D（天）。
frequencyPoint	String	2	Yes	建议的订阅周期值，表示每隔多少天。
expireDate	String	10	Yes	建议的订阅终止日期，格式为yyyy-MM-dd。
mode	String	1	Yes	签约模式： 1 - 先签约后扣款，需分两步完成 2 - 签约并立即扣款，一步完成（默认值）
selfExecute	String	1	Yes	订阅扣款模式： 非托管订阅固定为2 - 商户触发扣款：由商户系统负责计算扣款时间并主动调用API发起每期扣款

订阅支付请求参数说明

进行订阅支付时，请参考标准收银台支付或SDK下单请求中的信用卡支付，并注意以下修改：

1. 将 subProductType 参数值由 DIRECT 修改为 SUBSCRIBE
2. 添加 subscription 参数包含订阅详情

{
  // 关键参数示例
  "subProductType": "SUBSCRIBE",  // 必须设置为SUBSCRIBE
  "subscription": "..."           // json格式订阅请求参数
}

非托管订阅-仅签约

// 非托管订阅 - 仅签约模式，不立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"非托管-仅签约\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

非托管订阅-立即扣款

// 非托管订阅 - 立即扣款模式，立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"非托管-立即扣款\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}"

非托管订阅-续期扣款

// 非托管订阅 - 续期扣款，使用已有订阅合同发起新一期扣款
"subscription": "{\"requestType\":\"1\",\"contractId\":\"contractId_xxx\",\"tokenId\":\"tokenId_xxx\",\"merchantCustId\":\"custId_xxx\"}"

TransactionAddress

名称	类型	长度	必填	描述
firstName	String	64	Yes	名 (虚拟商品可不传)
lastName	String	64	Yes	姓 (虚拟商品可不传)
jpFirstName	String	64	No	（日文片假名）名
jpLastName	String	64	No	（日文片假名）姓
phone	String	32	Yes	电话号码 (虚拟商品的可不传)
email	String	256	Yes	电子邮件
postalCode	String	32	Yes	邮政编码 (虚拟商品可不传)
address	String	256	Yes	地址 (虚拟商品可不传)
country	String	64	Yes	国家。 请参阅 ISO 3166。
province	String	64	Yes	州。 当国家是美国 (US) 或加拿大 (CA) 时必填。 请参阅 ISO 3166。
city	String	64	Yes	城市 (虚拟商品可不传)
street	String	64	No	街道
number	String	64	No	门牌号
identityNumber	String	64	No	证件号码
birthDate	String	64	No	出生日期，格式为 yyyy/MM/dd

LpmsInfo

名称	类型	长度	必填	描述
lpmsType	String	64	Yes	本地支付方式。 请参阅 LpmsTypeEnum。
bankName	String	128	No	银行名称，某些本地支付方式需要。lpmsType为EFT时请参阅 。 lpmsType为Przelewy24时请参阅 Przelewy24BankNameEnum。
iBan	String	64	No	银行账户，部分地区转账时需要
walletAccountId	String	/	No	钱包/本地账户id，部分地区转账时需要。场景如下： 1.当 productType 为 LPMS，并且 lpmsType 为 ATM_CARD 时必填，此时需传送本地银行账户号。 2.当 productType 为 PAYMENT_CODE 时必填，此时需传送钱包付款码
walletAccountName	String	/	No	钱包/本地账户名称，部分地区转账时需要。当 productType 为 LPMS，并且 lpmsType 为 ATM_CARD 时必填，此时需传送本地银行账户名称。
prepaidNumber	String	/	No	预付费卡号，部分支付方式需要

MpiInfo

名称	类型	长度	必填	描述
eci	String	2	Yes	责任转移
cavv	String	128	Yes	由发卡行创建
xid	String	128	No	3D-Secure v1版本Mpi交易id（与dsTransID任选其一填写）
dsTransID	String	128	No	3D-Secure v2版本Mpi交易id（与xid任选其一填写）

响应参数

名称	类型	描述
respCode	String	来自 Onerway 的响应码
respMsg	String	来自 Onerway 的响应信息
data	Object	响应数据。 请参阅对象 data

data

名称	类型	必填	描述
transactionId	String	Yes	Onerway创建的交易订单号，对应商户订单号
merchantTxnId	String	Yes	顾客每次付款的订单号。
merchantNo	String	Yes	商户号。 商户注册时, OnerWay会为商户创建商户号
responseTime	String	Yes	接口响应时间，格式为 yyyy-MM-dd HH:mm:ss
txnTime	String	Yes	交易完成时间，格式为 yyyy-MM-dd HH:mm:ss
orderAmount	String	Yes	订单金额。
orderCurrency	String	Yes	交易订单币种。 请参阅 ISO 4217 货币代码
txnAmount	String	Yes	订单金额转换成结算币种后的金额
txnCurrency	String	Yes	结算币种。 请参阅 ISO 4217 货币代码
txnTimeZone	String	Yes	交易时区。 请参阅 ISO 4217 货币代码
status	String	Yes	交易处理结果。 请参阅
reason	String	Yes	交易失败原因
redirectUrl	String	Yes	收银台地址，商家拿到这个地址后，需要重定向打开。
sign	String	Yes	签名字符串，请参阅签名接口
contractId	String	Yes	订阅合同号：区分是哪笔订阅，完成订阅复购的重要参数。通常与tokenId成对保存。订阅首购成功后返回，订阅复购中使用
tokenId	String	Yes	订阅token：根据买家支付信息生成的支付token，完成复购的重要参数。订阅首购成功后返回，订阅复购中使用
eci	String	Yes	责任转移，3D Secure 所需参数
periodValue	String	Yes	分期付款期数
lpmsType	String	Yes	本地支付方式，请参阅对象
qrCode	String	Yes	二维码值
subscriptionManageUrl	String	Yes	订阅托管地址，买家可以通过此地址查看订阅订单信息
subscriptionsManageUrl	String	Yes	订阅列表托管地址

收银台接口请求、响应示例

POST

Request

{
  "merchantNo": "800079",
  "merchantTxnId": 2099220674,
  "merchantTxnTime": null,
  "merchantTxnTimeZone": null,
  "productType": "CARD", // 随收银台类型变化
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "orderAmount": "200",
  "orderCurrency": "USD",
  "txnOrderMsg": "{\"returnUrl\":\"https:\/\/www.merchant-store-website.com\/\",\"notifyUrl\":\"https:\/\/www.merchant-store-notify.com\/\",\"products\":\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1673591020057956352}",
  "shippingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"13976448789\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"US\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10,\"identityNumber\":\"717.628.937-97\"}",
  "billingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"13976448789\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"US\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10,\"identityNumber\":\"717.628.937-97\"}",
  "sign": "c7a8a2bf3bf2f762dba18b9ef6a6c734b7370b324d00a48cc1291576d318017b"
}

Response

{
  "data": {
    "transactionId": "1810961729430360064",
    "merchantTxnId": "2099220674",
    "merchantNo": "800079",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "status": "U",
    "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=5fbf64a805c74600aff384efa29feefd", // 重定向到收银台
    "sign": "",
    "contractId": ""
  },
  "respCode": "20000",
  "respMsg": "Success"
}

顾客支付完成示例

同步返回（returnurl）

https://www.merchant-store-website.com/?transactionId=1810961729430360064&merchantTxnId=2099220674&merchantNo=800079&responseTime=2024-07-10%2017:00:56&txnTime=2024-07-10%2017:00:32&txnTimeZone=+08:00&orderAmount=200.00&orderCurrency=USD&txnAmount=200.00&txnCurrency=USD&status=S&reason=Payment%20successful&eci=5

异步通知（notifyurl）

{
  "notifyType": "TXN",
  "transactionId": "1810961729430360064",
  "txnType": "SALE",
  "merchantNo": "800079",
  "merchantTxnId": "2099220674",
  "responseTime": "2024-07-10 17:00:56",
  "txnTime": "2024-07-10 17:00:32",
  "txnTimeZone": "+08:00",
  "orderAmount": "200.00",
  "orderCurrency": "USD",
  "txnAmount": "",
  "status": "S",
  "eci": "5",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "2abc7bf9e3274a040bb4b946823673e6dabade4589a5ed5dde5fcfe4dfb400f4",
  "paymentMethod": "VISA"
}