Onerway
支付场景

保存支付方式

保存客户的卡以支持复购:客户自选保存与服务端绑卡的选择、绑卡结果通知、已保存 token 的查询与删除,以及三种接入方式的参数差异。

保存支付方式(绑卡)把客户的卡转换为可复用的 tokenId,后续支付不再重复输入卡信息。收银台与 Web SDK 由客户在 Onerway 页面上自选是否保存;API 直连由商户服务端提交卡信息完成绑卡。

概念与选择

  • 客户自选保存(收银台、Web SDK):下单时传入稳定的 merchantCustId,Onerway 页面向客户提供保存卡选项。该选项不会默认选中,只有客户主动勾选并完成支付后才会保存卡。后续在相同环境、merchantNo 和 appId 范围内再次支付时,继续传入同一个 merchantCustId,页面会向该客户回显可用的已保存卡并在页面内完成选卡与支付。卡数据不经过商户系统,没有 PCI DSS 要求。
  • 服务端绑卡(API 直连):商户服务端调用生成卡 token提交卡信息,得到 tokenId 后以 token 支付发起后续交易。卡数据经过商户系统,须持有有效的 PCI DSS 认证。

两条路径得到的 tokenId 属同一体系,但服务端发起 token 支付时必须在 cardInfo.cvv 提交客户本次输入的 CVC,仍然经手卡数据,因此同样要求 PCI DSS。不具备资质的商户应让复购也在收银台或 Web SDK 页面上完成:页面回显已保存卡并在页面内完成支付;服务端可通过查询已保存 token 核对保存记录,但不能自行发起 token 支付。

merchantCustId 应来自稳定的服务端客户记录,不要直接使用邮箱、手机号等可变信息,也不要为不同客户复用同一个标识;没有持久客户记录的访客应省略 merchantCustId。卡 token 与订阅 token 属不同体系,区分见场景概览。

生命周期与通知

  • 支付成功不等于保存成功。保存结果以保存支付方式结果通知(txnType=BIND_CARD)为最终依据,仅当 status=S 时保存通知中的 tokenId;回跳到 returnUrl 与同步响应都不代表绑卡成功。服务端也可调用查询已保存 token 核对。
  • 管理已保存 token:查询已保存 token 返回每条绑定记录的 id 与 tokenId;客户要求删除卡时调用删除卡 token,入参是绑定记录的 id,不是 tokenId。
  • token 支付仍可能触发 3DS:服务端以已保存 tokenId 发起的支付同样可能返回 status=R,按 API 直连接入处理跳转。
  • 订阅并绑卡:托管卡订阅传入 subscription.bindCard=true 时,绑卡结果由独立的保存支付方式结果通知承载,与订阅扣款通知的 transactionId 不同,应各自幂等处理,见订阅。

各接入方式的参数差异

接入方式接口关键参数差异说明接入指南
收银台创建收银台支付merchantCustId由收银台页面展示保存选项与已保存卡;subProductType 按场景传 DIRECT、SUBSCRIBE 或 INSTALLMENT,保存卡无专用取值收银台接入
Web SDK创建 SDK 交易merchantCustId、subProductType=DIRECTSDK 内完成选卡与支付,客户端无需获取 tokenIdWeb SDK 接入
API 直连生成卡 token、创建直连交易绑卡:卡信息、merchantCustId;卡 token 支付:subProductType=TOKEN、tokenInfo.tokenId、cardInfo.cvv、merchantCustId绑卡与卡 token 支付是两次调用,都需 PCI DSSAPI 直连接入