Onerway
线上支付

收银台接入

服务端创建收银台支付,重定向客户至 Onerway 托管页面完成支付,并通过 Webhook 确认支付结果。

收银台(Checkout)支付由服务端创建:调用创建收银台支付接口获取 redirectUrl,再将客户浏览器重定向到 Onerway 托管的收银台页面完成支付。支付页面、3DS 认证与 PCI 合规由 Onerway 承担;浏览器、设备和持卡人 IP 信息由收银台页面采集,商户服务端不要采集或传入。

开始前,先按接入准备获取 API 凭证,并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按请求签名生成 sign。上线前,参考沙盒测试在沙盒环境验证集成中使用的全部场景。

收银台使用 Onerway 的 Google Pay 能力,无需报备网站;网站报备仅适用于 API 直连接入。

接入流程

在服务端创建支付

通过创建收银台支付创建交易。字段 txnOrderMsg 必须包含 returnUrl(同步返回地址)和 notifyUrl(Webhook 通知地址);字段 products 中商品金额、折扣和运费合计必须等于 orderAmount。

创建成功后交易状态为 U(未支付),响应返回字段 redirectUrl。

重定向到收银台

服务端将客户浏览器重定向到 redirectUrl。客户在托管页面选择支付方式并完成支付;需要 3DS 认证时由收银台页面引导完成,商户无需处理。

处理支付返回

客户完成支付后经 returnUrl 返回商户网站。同步返回只用于页面流转:建议在 returnUrl 上拼接商户订单号,客户返回时向其展示“处理中”,等待 Webhook 到达后再处理订单。最终支付结果以 Webhook 为准。

支付方式展示范围

收银台展示哪些支付方式由字段 productType 决定;实际交易处理方式还取决于 subProductType 和 txnType。

目标服务端输入
只展示卡支付productType=CARD
展示全部可用支付方式productType=ALL,由客户在收银台自行选择。
锁定单一本地支付方式或钱包productType=ALL,并传入字段 lpmsInfo.lpmsType;收银台只展示该支付方式,Apple Pay、Google Pay 分别取 ApplePay、GooglePay。

各支付方式在收银台下的支持情况与接入准备见支付方式。

保存卡选项

传入稳定的字段 merchantCustId 后,收银台会向客户提供保存卡信息的选项;该选项不会默认选中,只有客户主动勾选并完成支付后才会保存卡。字段 subProductType 按场景传入 DIRECT、SUBSCRIBE 或 INSTALLMENT 即可,不需要为保存卡使用单独取值。后续支付继续传入同一个 merchantCustId,收银台会向该客户回显可用的已保存卡。

收银台接入需额外注意:订阅场景的客户标识通过外层 merchantCustId 传入;字段 subscription.merchantCustId 选填,如同时传入,两者必须一致。merchantCustId 的取值要求、保存支付方式结果通知与已保存 token 的查询、删除见保存支付方式。

订阅支付

初始订阅在收银台完成:传入字段 subProductType =SUBSCRIBE 和字段 subscription(requestType=0),计费方式由字段 subscription.selfExecute 决定。续费与计划升降级由服务端通过 API 直连发起,收银台不参与。

托管订阅与自主管理订阅的选择、合约凭证、生命周期通知与升降级规则见订阅支付。

预授权

传入字段 txnType =AUTH 时,收银台完成的是预授权:冻结客户卡上的订单金额,不立即扣款;需要 3DS 时由收银台页面引导完成。预授权成功后保存响应中的 transactionId 与 paymentId,后续请款或撤销由服务端调用预授权请款或撤销完成。

适用范围、请款与撤销的生命周期、通知、边界与状态判断见预授权与请款。

分账

分账是平台模式下的能力:平台商户以收款子商户的 merchantNo 创建支付,并传入字段 paymentMethodOptions 在其中的 share 设置 profitShare=true,该笔支付才可参与分账;收银台的支付流程与普通支付一致。同时设置 profitShareRate 时,SALE 或 CAPTURE 成功后由 Onerway 自动分账;不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时,同时设置 profitShareNotifyUrl。paymentMethodOptions 按接口要求以 JSON 字符串提交。

自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见分账。

确认支付结果

收银台支付的最终结果以 Webhook 为准:普通支付见支付结果通知,订阅见订阅扣款通知,预授权见预授权、请款与撤销通知;客户自选保存卡时,绑卡结果由保存支付方式结果通知单独承载。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 Webhook 通知。

收银台接入需额外注意:returnUrl 同步返回不保证附带交易参数,不要以回跳 URL 上的任何参数作为订单处理依据;客户已返回但未收到 Webhook 时,用查询交易记录补偿。交易状态以响应字段 status 与 Webhook 中的同名字段为准,完整取值见 API Reference。