支付场景
保存支付方式(绑卡)把客户的卡转换为可复用的 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=DIRECT | SDK 内完成选卡与支付,客户端无需获取 tokenId | Web SDK 接入 |
| API 直连 | 生成卡 token、创建直连交易 | 绑卡:卡信息、merchantCustId;卡 token 支付:subProductType=TOKEN、tokenInfo.tokenId、cardInfo.cvv、merchantCustId | 绑卡与卡 token 支付是两次调用,都需 PCI DSS | API 直连接入 |