Onerway
POST

生成卡 token

查看 Markdown
该接口用于在 PCI DSS 合规接入中生成卡 token。同步响应承载处理状态与后续动作字段，最终 tokenization 结果通过 notifyUrl 回调接收。

请求

appIdstring必填
商户入驻 Onerway 后生成的店铺 ID。
示例：replace_with_app_id
商户后端在 PCI DSS 合规环境下直接采集的卡支付信息；授权后不得存储敏感认证数据。
countrystring必填
客户国家或地区代码，使用 ISO 3166-1 alpha-2 两位字母格式。
示例：US
emailstring必填
客户邮箱地址，用于交易确认和争议处理。
示例：customer@example.com
merchantCustIdstring必填
客户在商户系统中的唯一标识；保存的卡 token 会关联到该客户。
示例：cust_demo_tokenization_202606150001
merchantNostring必填
Onerway 分配的商户号；获取方式参见接入准备。
示例：replace_with_merchant_no
notifyUrlstring必填
接收最终卡 token 生成结果回调的 HTTPS 地址；回调会包含卡 token、脱敏卡信息等结果字段，报文契约见保存支付方式结果 Webhook。
示例：https://developers.onerway.com/example-card-token-notify
returnUrlstring必填
浏览器回跳 HTTPS 地址；用于绑卡 3DS challenge 跳转场景。
示例：https://developers.onerway.com/example-card-token-return
signstring必填
请求签名字符串；生成方式详见请求签名。
transactionIpstring必填
商户采集的持卡人交易 IP；应传终端用户 IP，而不是商户服务器 IP。
示例：192.0.2.10

请求示例

curl -X POST 'https://sandbox-acq.onerway.com/v1/txn/bindCard' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "appId": "replace_with_app_id",
  "cardInfo": "{\"holderName\":\"replace_with_cardholder_name\",\"cardNumber\":\"{{CARD-NUMBER}}\",\"month\":\"12\",\"year\":\"2030\",\"cvv\":\"{{CVV}}\"}",
  "country": "US",
  "email": "customer@example.com",
  "merchantCustId": "cust_demo_tokenization_202606150001",
  "merchantNo": "replace_with_merchant_no",
  "notifyUrl": "https://developers.onerway.com/example-card-token-notify",
  "returnUrl": "https://developers.onerway.com/example-card-token-return",
  "sign": "{{SIGN}}",
  "transactionIp": "192.0.2.10"
}'

响应

respCodestring
响应码；20000 表示请求处理成功，其余为错误码。完整码表见响应码。
respMsgstring
响应码对应的可读说明。
业务数据对象，承载本次令牌化请求的同步处理状态与后续动作字段。

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "txn_demo_tokenization_202606150001",
    "tokenId": "example_token_id",
    "status": "S",
    "redirectUrl": null,
    "sign": "{{SIGN}}"
  }
}
该接口暂未记录错误响应。

创建 SDK 交易

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

删除卡 token

使用查询已保存 token 返回的绑卡记录 ID 删除已保存卡绑定。