绑卡支付

两方支付商户必须提供 PCI DSS（支付卡行业数据安全标准）

请求参数

POST

名称	类型	长度	必填	签名	描述
merchantNo	String	20	Yes	Yes	商户号。 商户注册时，OnerWay会为商户创建商户号
appId	String	20	Yes	Yes	商户应用程序 ID。 商户注册网站时，OnerWay会为商户创建一个应用id
merchantCustId	String	50	Yes	Yes	客户在商户的唯一标识
cardInfo	String	/	Yes	Yes	交易卡信息。 格式为 json 字符串。 请参阅对象
email	String	256	Yes	Yes	商户客户的邮箱
country	String	64	Yes	Yes	商户客户的国家。请参考 ISO 3166。
transactionIp	String	64	Yes	Yes	商户客户的交易IP
returnUrl	String	256	Yes	Yes	3DS 认证完成后的浏览器回跳地址。绑卡请求触发 3DS challenge 时，持卡人完成或退出发卡行认证页面后，Onerway 会将浏览器重定向到该 URL。请使用可公网访问的 HTTPS 页面，并在该页面继续处理绑卡结果展示或后续查询。
sign	String	/	Yes	No	签名字符串，请参阅签名接口

CardInfo

名称	类型	长度	必填	描述
holderName	String	48	Yes	持卡人姓名
cardNumber	String	128	Yes	持卡人卡号
month	String	64	Yes	卡号月份
year	String	64	Yes	卡号年份
cvv	String	64	Yes	卡号cvv

响应参数

名称	类型	签名	描述
respCode	String	No	来自 Onerway 的响应码
respMsg	String	No	来自 Onerway 的响应信息
data	Object	No	响应数据。 请参阅对象 token 信息，subProductType为TOKEN或AUTO_DEBIT时必填，格式为json字符串。 请参阅对象TokenInfo

TokenInfo

名称	类型	签名	描述
transactionId	String	Yes	Onerway 创建的交易订单号
tokenId	String	Yes	绑卡令牌id。仅在最终绑卡成功后保存并用于后续 Token支付
status	String	Yes	绑卡状态。S 表示绑卡成功，R 表示需要重定向完成 3DS 认证，F 表示绑卡失败
redirectUrl	String	Yes	3DS 认证跳转地址。绑卡请求需要持卡人完成 3DS challenge 时返回；商户应将持卡人浏览器重定向到该 URL 完成发卡行认证。该地址包含交易上下文，不应缓存或复用
sign	String	No	签名字符串，请参阅签名接口

3DS 跳转处理

当响应中的 status=R 且返回 redirectUrl 时，表示本次绑卡需要持卡人完成 3DS challenge。商户应立即将持卡人浏览器重定向到 redirectUrl，并在请求中的 returnUrl 页面承接认证完成后的浏览器回跳。

returnUrl 只表示浏览器已从认证流程返回，不应单独作为绑卡成功依据。请根据返回参数或后续查询结果确认最终状态；只有最终状态为 S 时，才保存 tokenId 并用于后续 Token 支付。

绑卡支付请求响应示例

POST

请求参数

{
  "appId": "<APP_ID>",
  "cardInfo": "{\"cardNumber\":\"4000020951595032\",\"cvv\":\"123\",\"month\":\"12\",\"year\":\"2031\",\"holderName\":\"CARD HOLDER\"}",
  "country": "US",
  "email": "customer@example.com",
  "merchantCustId": "customer_12345",
  "merchantNo": "<MERCHANT_NO>",
  "returnUrl": "https://merchant.example.com/card-binding/return", // 3DS 完成后的浏览器回跳地址
  "sign": "<SIGNATURE>",
  "transactionIp": "127.0.0.1"
}

响应参数 - 绑卡成功

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "<TRANSACTION_ID>",
    "tokenId": "<TOKEN_ID>", // 最终成功后保存该 tokenId
    "status": "S", // S 表示绑卡成功
    "sign": "<RESPONSE_SIGNATURE>"
  }
}

响应参数 - 需要 3DS

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "<TRANSACTION_ID>",
    "status": "R", // R 表示需要重定向完成 3DS 认证
    "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/<SESSION_ID>", // 3DS 认证跳转地址
    "sign": "<RESPONSE_SIGNATURE>"
  }
}