# 收银台接入

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

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

开始前，先按[接入准备](/zh/payments/get-started/setup)获取 API 凭证，并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按[请求签名](/zh/payments/get-started/request-signing)生成 `sign`。上线前，参考[沙盒测试](/zh/payments/get-started/testing)在沙盒环境验证集成中使用的全部场景。

收银台使用 Onerway 的 Google Pay 能力，无需报备网站；网站报备仅适用于 [API 直连接入](/zh/payments/online-payments/payment-methods/google-pay#%E4%B8%8A%E7%BA%BF%E5%89%8D%E7%BD%91%E7%AB%99%E6%8A%A5%E5%A4%87)。

## 接入流程

<steps level="3">

### 在服务端创建支付

通过[创建收银台支付](/zh/payments/api-reference/endpoints/create-checkout-payment)创建交易。[字段 `txnOrderMsg`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-txnOrderMsg) 必须包含 `returnUrl`（同步返回地址）和 `notifyUrl`（Webhook 通知地址）；[字段 `products`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-txnOrderMsg-products) 中商品金额、折扣和运费合计必须等于 `orderAmount`。

创建成功后交易状态为 `U`（未支付），响应返回[字段 `redirectUrl`](/zh/payments/api-reference/endpoints/create-checkout-payment#response-data-redirectUrl)。

### 重定向到收银台

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

### 处理支付返回

客户完成支付后经 `returnUrl` 返回商户网站。同步返回只用于页面流转：建议在 `returnUrl` 上拼接商户订单号，客户返回时向其展示“处理中”，等待 Webhook 到达后再处理订单。最终支付结果以 [Webhook](#%E7%A1%AE%E8%AE%A4%E6%94%AF%E4%BB%98%E7%BB%93%E6%9E%9C) 为准。

</steps>

## 支付方式展示范围

收银台展示哪些支付方式由[字段 `productType`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-productType) 决定；实际交易处理方式还取决于 `subProductType` 和 `txnType`。

| 目标 | 服务端输入 |
| --- | --- |
| 只展示卡支付 | `productType=CARD` |
| 展示全部可用支付方式 | `productType=ALL`，由客户在收银台自行选择。 |
| 锁定单一本地支付方式或钱包 | `productType=ALL`，并传入[字段 `lpmsInfo.lpmsType`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-lpmsInfo-lpmsType)；收银台只展示该支付方式，Apple Pay、Google Pay 分别取 `ApplePay`、`GooglePay`。 |

各支付方式在收银台下的支持情况与接入准备见[支付方式](/zh/payments/online-payments/payment-methods)。

## 保存卡选项

传入稳定的[字段 `merchantCustId`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-merchantCustId) 后，收银台会向客户提供保存卡信息的选项；该选项不会默认选中，只有客户主动勾选并完成支付后才会保存卡。[字段 `subProductType`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-subProductType) 按场景传入 `DIRECT`、`SUBSCRIBE` 或 `INSTALLMENT` 即可，不需要为保存卡使用单独取值。后续支付继续传入同一个 `merchantCustId`，收银台会向该客户回显可用的已保存卡。

收银台接入需额外注意：订阅场景的客户标识通过外层 `merchantCustId` 传入；[字段 `subscription.merchantCustId`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-subscription-merchantCustId) 选填，如同时传入，两者必须一致。`merchantCustId` 的取值要求、保存支付方式结果通知与已保存 token 的查询、删除见[保存支付方式](/zh/payments/online-payments/scenarios/saved-payment-methods)。

## 订阅支付

初始订阅在收银台完成：传入[字段 `subProductType`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-subProductType) `=SUBSCRIBE` 和[字段 `subscription`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-subscription)（`requestType=0`），计费方式由[字段 `subscription.selfExecute`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-subscription-selfExecute) 决定。续费与计划升降级由服务端通过 API 直连发起，收银台不参与。

托管订阅与自主管理订阅的选择、合约凭证、生命周期通知与升降级规则见[订阅支付](/zh/payments/online-payments/scenarios/subscriptions)。

## 预授权

传入[字段 `txnType`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-txnType) `=AUTH` 时，收银台完成的是预授权：冻结客户卡上的订单金额，不立即扣款；需要 3DS 时由收银台页面引导完成。预授权成功后保存响应中的 `transactionId` 与 `paymentId`，后续请款或撤销由服务端调用[预授权请款或撤销](/zh/payments/api-reference/endpoints/capture-or-void-authorization)完成。

适用范围、请款与撤销的生命周期、通知、边界与状态判断见[预授权与请款](/zh/payments/online-payments/scenarios/pre-authorization)。

## 分账

分账是平台模式下的能力：平台商户以收款子商户的 `merchantNo` 创建支付，并传入[字段 `paymentMethodOptions`](/zh/payments/api-reference/endpoints/create-checkout-payment#request-paymentMethodOptions) 在其中的 `share` 设置 `profitShare=true`，该笔支付才可参与分账；收银台的支付流程与普通支付一致。同时设置 `profitShareRate` 时，`SALE` 或 `CAPTURE` 成功后由 Onerway 自动分账；不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时，同时设置 `profitShareNotifyUrl`。`paymentMethodOptions` 按接口要求以 JSON 字符串提交。

自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见[分账](/zh/payments/online-payments/scenarios/profit-sharing)。

## 确认支付结果

收银台支付的最终结果以 Webhook 为准：普通支付见[支付结果通知](/zh/payments/api-reference/webhooks/payment-result)，订阅见[订阅扣款通知](/zh/payments/api-reference/webhooks/subscription-payment)，预授权见[预授权、请款与撤销通知](/zh/payments/api-reference/webhooks/authorization-capture)；客户自选保存卡时，绑卡结果由[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)单独承载。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 [Webhook 通知](/zh/payments/get-started/webhooks)。

收银台接入需额外注意：`returnUrl` 同步返回不保证附带交易参数，不要以回跳 URL 上的任何参数作为订单处理依据；客户已返回但未收到 Webhook 时，用[查询交易记录](/zh/payments/api-reference/endpoints/query-transactions)补偿。交易状态以[响应字段 `status`](/zh/payments/api-reference/endpoints/create-checkout-payment#response-data-status) 与 Webhook 中的同名字段为准，完整取值见 API Reference。