直连 API（Direct API）接入由商户自建支付页面并在服务端直接调用创建直连交易：卡信息或 token 由商户服务端提交，3DS 跳转由商户处理，最终结果通过 Webhook 确认。与收银台和 Web SDK 不同，卡数据会经过商户系统，因此本接入方式有 PCI DSS 合规门槛；换来的是完全自定义的支付体验，以及绑卡、token 支付、订阅续费和预授权等服务端场景的直接控制。Apple Pay、Google Pay 与本地支付方式在直连下的接入准备与专属流程见支付方式。
前提
开始前，先按接入准备获取 API 凭证，并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按请求签名生成 sign。上线前，参考沙盒测试在沙盒环境验证集成中使用的全部场景。
API 直连接入另有 PCI DSS 合规门槛：在自建页面收集卡号、有效期和 CVC 并提交到 Onerway，商户必须持有有效的 PCI DSS 认证，通过 TLS 安全传输持卡人数据，不得存储 CVC 等敏感认证数据。不具备资质的商户请改用收银台接入或 Web SDK 接入，卡数据不会经过商户服务器。订阅续费和预授权请款不提交卡数据，不受此限制；卡 token 支付仍须提交 cardInfo.cvv，同样在 PCI DSS 范围内。
接入流程
在服务端创建交易
调用创建直连交易。交易模型由字段 productType、字段 subProductType 与字段 txnType 共同决定；商户自行采集卡信息的卡支付传 productType=CARD、subProductType=DIRECT、txnType=SALE，并在字段 cardInfo 中提交卡信息。
字段 txnOrderMsg 必须包含 returnUrl（3DS 等跳转流程的同步回跳地址）与 notifyUrl（Webhook 通知地址）。与收银台不同，直连接入由商户自行采集浏览器、设备与持卡人 IP 信息（如 transactionIp）并传入 txnOrderMsg；各子字段的必填条件见字段 txnOrderMsg 的字段树。
按响应状态处理跳转
Onerway 判定是否需要 3DS 认证，同步响应的字段 status 可能直接是终态：
| 响应 | 处理 |
|---|---|
status=S | 支付成功，等待 Webhook 后完成订单。 |
status=R 且 actionType=RedirectURL | 将客户浏览器重定向到字段 redirectUrl 完成 3DS 认证或本地支付方式页面。 |
| 其他取值 | 按 status 与 respCode 处理失败或处理中状态，完整取值见 API Reference。 |
原生 App 可在 WebView 中加载 redirectUrl，监听导航到 returnUrl 后关闭 WebView，再由服务端查询结果。
承接同步回跳
客户完成认证后经 returnUrl 返回商户页面。回跳只用于页面流转，不保证附带交易参数：建议在 returnUrl 上拼接商户订单号，客户返回时向其展示“处理中”，并由服务端通过查询交易记录核实，不要以回跳 URL 上的任何参数作为订单处理依据。
以 Webhook 确认结果
Onerway 将最终结果 POST 到 notifyUrl。确认支付结果一节说明验签、应答、重试与幂等处理。
绑卡与 token 支付
直连接入的保存支付方式（绑卡）流程是：服务端提交卡信息生成 token，随后用 tokenId 发起 token 支付，并按需查询或删除已保存记录。客户自选保存与服务端绑卡的选择、三类 token 的区分见保存支付方式。
- 生成卡 token：调用生成卡 token，提交卡信息与稳定的字段
merchantCustId，同时传入notifyUrl与returnUrl。响应字段status=R时，将持卡人重定向到redirectUrl完成 3DS 认证。 - 确认保存结果：以保存支付方式结果通知（
txnType=BIND_CARD）为最终依据，仅当status=S时保存tokenId；回跳到returnUrl与同步响应都不代表绑卡成功。也可调用查询已保存 token核对。 - 发起 token 支付：调用创建直连交易，传入
subProductType=TOKEN与字段tokenInfo（tokenId为已保存的卡 token，provider不传），并在cardInfo.cvv提交客户本次输入的 CVC，同时传入绑卡时使用的merchantCustId。token 支付同样可能返回status=R要求 3DS 认证，处理方式与接入流程一致。 - 管理已保存 token：查询已保存 token返回每条绑定记录的
id与tokenId；客户要求删除卡时调用删除卡 token，入参是绑定记录的id，不是tokenId。
API 直连接入需额外注意：生成卡 token 与 token 支付都经手卡数据（token 支付须提交 cardInfo.cvv），两步都要求 PCI DSS。不具备资质的商户应让保存卡与复购都在收银台或 Web SDK 页面上完成。
订阅
托管订阅与自主管理订阅的选择、合约凭证与生命周期通知见订阅支付。本节说明选定方案后在直连侧如何调用。三类请求都使用创建直连交易，传入 subProductType=SUBSCRIBE 与字段 subscription，并以字段 subscription.requestType 区分：
requestType | 用途 | 关键输入 |
|---|---|---|
0 | 初始订阅，建立合约 | cardInfo 或 tokenInfo、merchantCustId、selfExecute、计费周期与期数 |
1 | 自主管理订阅的本期扣款 | contractId、tokenId、merchantCustId、本期金额 |
2 | 托管订阅升级或降级 | contractId、tokenId、changeMode、prorationMode |
初始订阅成功后，保存订阅扣款通知中的 contractId 与 tokenId。初始订阅也可以在收银台或 Web SDK 完成，后续扣款与更新仍走直连接口。
自主管理订阅续费（requestType=1）传入 contractId、tokenId、merchantCustId 与本期金额，不传卡信息，因此续费环节没有 PCI DSS 要求。
托管订阅升降级（requestType=2）使用已存储的 contractId 与 tokenId 发起，生效时机由字段 subscription.changeMode 决定，差价由 prorationMode 决定按剩余天数自动计算还是由商户通过 proration 提交。
API 直连接入需额外注意：托管卡订阅同时传入 subscription.bindCard=true 时，会收到保存支付方式结果通知与订阅扣款通知两条 transactionId 不同的通知，应各自幂等处理。
预授权
预授权先冻结持卡人卡上的订单金额、暂不扣款。直连侧的 txnType=AUTH 适用于自行采集卡信息的卡支付和 token 支付（subProductType=DIRECT 或 TOKEN），不适用于本地支付方式、订阅或分期。
调用创建直连交易并传入 txnType=AUTH，其余参数与自行采集卡信息的卡支付或 token 支付相同；需要 3DS 时同样按 status=R 处理跳转。保存响应中的 transactionId 与 paymentId，后续请款或撤销调用预授权请款或撤销。
授权到请款或撤销的生命周期、通知、边界与状态判断见预授权与请款。
本地支付
本地支付方式与卡支付共用创建直连交易接口，差别只在参数组合与流程形态：传入 productType=LPMS 与字段 lpmsInfo（lpmsType 指定支付方式，其余子字段按方式条件必填），subProductType 一次性扣款传 DIRECT、订阅传 SUBSCRIBE；本地支付方式不支持 txnType=AUTH。方式清单与可用性查询、跳转与延迟到账的处理、方式专属参数与订阅形态见本地支付方式。
API 直连接入需额外注意：productType=ALL 属于收银台的聚合展示概念，直连接口不支持，商户需自建支付方式列表，并自行处理 status=R 下的客户侧动作与回跳承接。
分账
分账是平台模式下的能力：平台商户以收款子商户的 merchantNo 创建支付，并传入字段 paymentMethodOptions 在其中的 share 设置 profitShare=true，该笔支付才可参与分账；其余参数与普通交易相同。同时设置 profitShareRate 时，SALE 或 CAPTURE 成功后由 Onerway 自动分账；不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时，同时设置 profitShareNotifyUrl。paymentMethodOptions 按接口要求以 JSON 字符串提交。
自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见分账。
确认支付结果
API 直连接入的最终结果以 Webhook 为准，按场景分别见支付结果通知、保存支付方式结果通知、订阅扣款通知与预授权、请款与撤销通知。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 Webhook 通知。
API 直连接入需额外注意：本接入方式同时使用四类通知，Webhook 端点必须能接收所用场景涉及的全部通知类型；绑卡、订阅并绑卡、预授权及后续请款或撤销会产生多笔 transactionId 各不相同的关联通知，用 paymentId、contractId 关联。同步响应可能直接返回终态 status=S，仍应等待 Webhook 后再完成订单；客户已回跳但未收到 Webhook 时，用查询交易记录补偿。
上线前检查
- 持有有效的 PCI DSS 认证，支付页面通过 TLS 传输且不存储 CVC。
- 已处理
status=R跳转与returnUrl回跳，回跳后由服务端查询而非信任 URL 参数。 - Webhook 端点已按 Webhook 通知完成上线前检查，且能接收绑卡、订阅、预授权等所用场景的全部通知类型。
- 已保存的
tokenId、contractId与paymentId以字符串存储并与客户或订单关联。 - 沙盒验证已覆盖 3DS Challenge、3DS Frictionless 以及所用的绑卡、订阅、预授权与本地支付场景。