# 本地支付方式

> 本地支付方式的清单与可用性查询、三种接入方式的差异、三种客户侧动作与延迟到账的处理、方式专属参数、支持订阅的方式与两步流程，以及部分区域支付方式的额外要求。

本地支付方式是卡与钱包之外、面向特定国家或地区的支付方式，覆盖银行转账与网上银行、虚拟账户、电子钱包、二维码、便利店与现金凭证、预付卡、运营商代扣与先买后付等形态。它们与卡支付共用同一套下单接口，差别在于客户需要离开商户页面、在支付方式自己的界面完成付费，且部分方式并非即时到账。

三种接入方式都可以使用本地支付方式：收银台与 Web SDK 由 Onerway 展示可用方式并承接客户侧动作，API 直连由商户指定方式并自行承接。本地支付方式不支持预授权（`txnType=AUTH`）。

## 查询可用支付方式

Onerway 支持的方式清单以[字段 `lpmsInfo.lpmsType`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo-lpmsType) 的取值为准，每个取值都附有方式说明，可作为接入前的方式名称索引；其中 `ApplePay` 与 `GooglePay` 属于钱包，接入方式见 [Apple Pay](/zh/payments/online-payments/payment-methods/apple-pay) 与 [Google Pay](/zh/payments/online-payments/payment-methods/google-pay)。

某笔订单实际可用哪些方式，取决于商户开通配置、客户所在国家或地区、币种与金额，以[查询可用支付方式](/zh/payments/api-reference/endpoints/list-available-payment-methods)的返回为准：不要只按币种判断可用性。返回的每条记录以 `data[].paymentMethod` 标识支付方式，下单时 `lpmsInfo.lpmsType` 使用同一个取值。币种与金额的校验规则见[币种与金额校验](/zh/payments/get-started/currency-and-amount)。

由商户自建支付方式列表时（API 直连，或收银台锁定单一方式），必须先查询再展示，不要把方式清单硬编码在前端；结果可缓存，并在商户配置变更时刷新。收银台与 Web SDK 展示全部可用方式时由 Onerway 侧完成筛选，商户无需自行调用。

单笔限额，以及部分方式额外的商户注册或地区要求，请向 Onerway 技术支持确认。

## 接入方式选择

| 接入方式 | 展示与选择 | 关键参数 |
| --- | --- | --- |
| [收银台](/zh/payments/online-payments/checkout) | 收银台展示当前订单可用的方式，由客户自行选择；也可锁定单一方式 | 展示全部可用方式传 `productType=ALL`；锁定单一方式在此基础上传 `lpmsInfo.lpmsType` |
| [Web SDK](/zh/payments/online-payments/sdk) | SDK 在商户页面内展示可用方式，二维码与本地支付页等承接界面由 SDK 渲染 | `productType=ALL`；本地支付方式由商户按钮调用 `confirmPayment()` 发起 |
| [API 直连](/zh/payments/online-payments/api) | 商户自建支付方式列表并在下单时指定方式，自行承接客户侧动作 | [字段 `productType`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-productType) 传 `LPMS` 与 `lpmsInfo`；`subProductType` 一次性扣款传 `DIRECT`、订阅传 `SUBSCRIBE` |

收银台与 Web SDK 路径下，客户侧动作与承接界面都由 Onerway 页面或 SDK 处理。本页其余内容说明 API 直连路径的调用方式与三种接入方式共同面对的到账时效；本地支付方式订阅目前只说明 API 直连的建立方式。

## API 直连接入

<steps level="3">

### 创建交易

客户选定支付方式后，服务端调用[创建直连交易](/zh/payments/api-reference/endpoints/direct-create-transaction)，[字段 `productType`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-productType) 传 `LPMS`，并传入 `subProductType=DIRECT`（订阅传 `SUBSCRIBE`，见[本地支付方式订阅](#%E6%9C%AC%E5%9C%B0%E6%94%AF%E4%BB%98%E6%96%B9%E5%BC%8F%E8%AE%A2%E9%98%85)）、`txnType=SALE` 与[字段 `lpmsInfo`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo)：`lpmsType` 指定支付方式，其余子字段按方式条件必填，见[方式专属参数](#%E6%96%B9%E5%BC%8F%E4%B8%93%E5%B1%9E%E5%8F%82%E6%95%B0)。`productType=ALL` 属于收银台的聚合展示概念，直连接口不支持。

### 承接客户侧动作

响应 `status=R` 表示还需要客户完成一次动作，动作形态由[字段 `actionType`](/zh/payments/api-reference/endpoints/direct-create-transaction#response-data-actionType) 决定，三种取值都要处理：

| `actionType` | 处理 |
| --- | --- |
| `RedirectURL` | 把客户重定向到[字段 `redirectUrl`](/zh/payments/api-reference/endpoints/direct-create-transaction#response-data-redirectUrl)。跳转后的界面由支付方式决定，可能是选行页、银行 App 或网银授权页 |
| `QrCode` | 在商户页面展示[字段 `codeForm`](/zh/payments/api-reference/endpoints/direct-create-transaction#response-data-codeForm) 承载的二维码或条码；该字段带 `expireTime` 时按其处理失效 |
| `ShowContext` | 在商户页面展示[字段 `presentContext`](/zh/payments/api-reference/endpoints/direct-create-transaction#response-data-presentContext) 承载的上下文信息 |

涉及拉起 App 的方式，需在移动浏览器上验证拉起与回跳。

### 承接同步回跳

跳转型方式的客户完成或放弃操作后，经 `txnOrderMsg.returnUrl` 返回商户页面。回跳只用于页面流转，不保证附带交易参数，也不代表支付已完成：建议在 `returnUrl` 上拼接商户订单号，客户返回时向其展示“处理中”，并由服务端通过[查询交易记录](/zh/payments/api-reference/endpoints/query-transactions)核实。

### 确认最终结果

最终状态以[支付结果通知](/zh/payments/api-reference/webhooks/payment-result)为准，[字段 `paymentMethod`](/zh/payments/api-reference/webhooks/payment-result#webhook-paymentMethod) 返回本次实际扣款的支付方式。验签、应答与重试、幂等去重与查询补偿见 [Webhook 通知](/zh/payments/get-started/webhooks)。

</steps>

## 方式专属参数

除 `lpmsType` 外，`lpmsInfo` 还有五个子字段，都按所选支付方式条件必填：

| 子字段 | 采集内容 |
| --- | --- |
| `bankName` | 客户选择的银行；`EFT` 与 `Przelewy24` 需要，可选银行见下方 `lpmsInfo` 字段说明中的取值列表 |
| `walletAccountId` | 钱包或本地账户标识符 |
| `walletAccountName` | 钱包或本地账户名称 |
| `iBan` | 以 IBAN 识别银行的地区转账账号 |
| `prepaidNumber` | 日本预付类方式的预付卡或充值卡号 |

各字段的完整必填条件与 `bankName` 的银行取值见[字段 `lpmsInfo`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo)。

`billingInformation` 与 `shippingInformation` 的必填子字段同样随支付方式变化，例如部分本地支付方式要求提供客户的政府身份标识 `identityNumber`。这些要求由支付方式提供方决定，创建直连交易接口只对个别方式给出了明确条件（例如 `lpmsType=MB_WAY` 时 `phoneCountryCode` 必填），其余未逐个列出，请在沙盒环境逐个验证要上线的方式。

## 延迟到账与等待态

部分本地支付方式并非即时到账：客户拿到支付码、凭证或转账信息后，可能过一段时间才实际完成付费，银行转账、虚拟账户、便利店与现金凭证类方式都属于这种形态。这类订单需要按以下方式处理：

- 一次下单对应一个支付意图：响应中的 `paymentId` 与 `transactionId` 一一对应。支付意图未关闭前可继续尝试（通知的 `paymentStatus` 为 `O`），关闭后（`N`）该订单不能再支付。
- 支付结果通知只在交易到达终态时发送，已向客户出示支付码或凭证不代表款项已收到。
- 创建交易后订单可能长时间停在处理中，商户需要为订单设计等待态，并明确超时后如何处理；支付意图超时关闭时，通知的 `paymentStatus` 为 `N`。
- 不要以回跳或同步响应作为到账依据，也不要在客户回跳后立即发货；未收到通知时用[查询交易记录](/zh/payments/api-reference/endpoints/query-transactions)补偿，读交易级 `status`——该接口不返回支付意图级的 `paymentStatus`。

## 本地支付方式订阅

部分本地支付方式可用于订阅，目前包括 `DANA`、`WeChat`、`GCash` 与 `TOUCH_GO_EWALLET`；某个方式在当前商户配置下是否支持订阅，可在[查询可用支付方式](/zh/payments/api-reference/endpoints/list-available-payment-methods)时传 `subProductType=SUBSCRIBE` 筛选。这些方式只支持自主管理订阅（`subscription.selfExecute=2`），续费扣款由商户发起；托管订阅与自主管理订阅的区别见[订阅支付](/zh/payments/online-payments/scenarios/subscriptions)。

计费频率只能传 `frequencyType=D`，但这不表示只能按天扣款：[字段 `subscription.frequencyPoint`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-subscription-frequencyPoint) 按天表示计费周期，例如，月度订阅可传 `30`，年度订阅可传 `365`。该值仅用于记录，实际续费扣款时间由商户自行确定。

订阅分两步完成：

1. **订阅授权**：调用创建直连交易，传入 `productType=LPMS`、`subProductType=SUBSCRIBE`、`txnType=SALE`、`lpmsInfo` 与[字段 `subscription`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-subscription)（`requestType=0`），客户在支付方式提供方的界面完成协议扣款授权，承接方式同样由 `actionType` 决定。首期扣款方式由 `subscription.mode` 决定：默认 `2` 表示客户授权后由 Onerway 立即完成首期扣款；传 `1` 表示只建立授权、首期扣款改由商户自行发起。授权结果以[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)为准（`txnType=BIND_CARD`、`scenarios=SUBSCRIPTION_INITIAL`），仅在 `status=S` 时持久化其中的 `contractId` 与 `tokenId`。请求中的 `orderAmount` 填写真实的订阅金额，`txnOrderMsg.products` 各行合计需与之相等；授权通知本身返回 `orderAmount=0.00`。
2. **后续扣款**：商户按计费周期调用创建直连交易，传入 `subscription.requestType=1` 与已保存的 `contractId`、`tokenId` 和 `merchantCustId`。`mode=2` 下首期扣款已由 Onerway 在授权后完成，商户从第二期开始发起；`mode=1` 下首期也由商户发起。每期扣款的结果都由[订阅扣款通知](/zh/payments/api-reference/webhooks/subscription-payment)返回（`txnType=SALE`）。

与卡订阅的差异：

- 授权失败即订阅终止：不会再有订阅扣款通知，保存支付方式结果通知的 `subscriptionStatus` 为 `canceled`。
- `mode=2` 下订阅授权与首期扣款是两条通知，`transactionId` 与 `channelRequestId` 各不相同，`merchantTxnId`、`contractId` 与 `tokenId` 相同（`paymentId` 有值时同样相同，但首期扣款通知可能不返回该字段，不要用它做唯一匹配键）；两条通知到达商户服务器的先后顺序不保证，都要按各自的 `transactionId` 幂等处理。
- 这里的 `tokenId` 是订阅 token，只能用于订阅相关操作，不能用于 `subProductType=TOKEN` 支付；本地支付方式订阅不返回 `cardTokenId`。
- 首期扣款的订阅扣款通知不返回 `scenarios`，订阅场景由保存支付方式结果通知返回。

## 部分区域支付方式的额外要求

stc pay、Tamara、Tabby 与 MADA 的取值分别是 `stcpay`、`tamara`、`tabby` 与 `cardpay`，可在[字段 `lpmsInfo.lpmsType`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo-lpmsType) 的取值列表中按方式名查到。这几个方式的额外要求不在 `lpmsInfo` 里，而在商品与订单信息上：

- 商品行必须区分类别：[字段 `txnOrderMsg.products[].type`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-products-type) 传 `virtual` 或 `physical`，[字段 `txnOrderMsg.products[].productAvatarUrl`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-products-productAvatarUrl) 传 HTTPS 商品图片链接，格式为 JPG、PNG 或 WebP。
- [字段 `txnOrderMsg.customerPlatform`](/zh/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-customerPlatform) 必填：Web 端传网站域名，App 端传应用名称。
- stc pay 的结算依赖物流信息：交易已成功完成且包裹送达客户并签收后，调用[上传物流信息](/zh/payments/api-reference/endpoints/upload-logistics-info)提交承运商编码与运单号；虚拟商品交易与分期交易不适用该结算前置条件。

这几个方式的开通范围请向 Onerway 技术支持确认。

## 上线前检查

- 自建支付方式列表的接入方式已在展示前调用[查询可用支付方式](/zh/payments/api-reference/endpoints/list-available-payment-methods)，没有把方式清单硬编码在前端。
- `status=R` 下 `actionType` 的三种取值都已处理，回跳页只承接客户，订单结果由服务端查询或通知确认。
- Webhook 端点已按 [Webhook 通知](/zh/payments/get-started/webhooks#%E4%B8%8A%E7%BA%BF%E5%89%8D%E6%A3%80%E6%9F%A5)完成上线前检查，能接收支付结果通知；使用订阅时还能接收保存支付方式结果通知与订阅扣款通知。
- 已为非即时到账的方式设计等待态与超时处理，未在客户回跳后立即发货。
- 已在沙盒环境逐个验证要上线的支付方式，覆盖客户中途取消与移动端跳转。
- 使用本地支付方式订阅时，`contractId` 与 `tokenId` 仅在授权成功时保存，以字符串存储并与客户关联。