Onerway
支付场景

分账

选择自动分账或通过 API 发起分账，配置结果通知，并将分账与分账回退关联到原支付交易。
查看 Markdown

分账是平台模式下的能力，用于在支付完成后分配交易资金；是否为平台商户在开户时按约定的合作模式确定，普通商户不适用本页内容。通常由平台商户以收款子商户名义发起分账。自动分账的接收方为平台商户；通过 API 发起时，接收方与金额由请求中的 receivers 指定。创建支付时，merchantNo 使用收款子商户号，后续通过 API 发起分账或查询时保持一致。

概念与选择

创建支付时，必须在 paymentMethodOptions.share 中设置 profitShare=true，该笔支付才可参与分账。收银台、Web SDK 与 API 直连均使用这一配置。

方式创建支付时的配置支付成功后的处理
自动分账同时设置 profitShare=true 和 profitShareRateSALE 或 CAPTURE 成功后，Onerway 按比例自动分账给平台商户；每笔原支付只产生一笔自动分账记录
通过 API 发起分账设置 profitShare=true，不传 profitShareRate商户服务端调用分账接口，指定接收方与分账金额

profitShareRate 是 1–100 的整数百分比，以字符串提交，"10" 表示 10%；小数、0、负数或大于 100 的取值会被拒绝。已自动分账的支付发生退款或拒付时，Onerway 按同一比例退还对应的分账金额。

仅设置 profitShare=true 或通知地址不会触发自动分账。需要自动分账时，还必须设置 profitShareRate。字段要求与完整请求示例见各接入方式的 API 参考。

生命周期与通知

创建支付并配置通知地址

按选定方式设置 paymentMethodOptions.share。需要接收自动分账或自动分账回退通知时，同时设置 profitShareNotifyUrl；不传时，不发送自动通知。

通知地址必须使用 HTTPS，且与 profitShare=true 同时提交。CAPTURE 交易继承原 AUTH 交易的通知地址。paymentMethodOptions 按接口要求以 JSON 字符串提交，完整示例见下方各接入方式的 API 参考。

确认支付成功

按所用接入方式确认支付结果，并保存原交易的 transactionId、商户订单号及收款商户号。支付结果的通知处理见 Webhook 通知；分账结果使用独立的分账结果通知。

自动分账或调用分账接口

选择自动分账时，由 Onerway 在 SALE 或 CAPTURE 成功后执行，无需再调用分账接口。自动分账与自动分账回退的 profitReference 由 Onerway 生成。

通过 API 发起时，调用发起分账或分账回退，设置 profitType=share，gatewayReference 使用原支付的 transactionId。为本次请求提供全局唯一的 profitReference，通过 currency 提交分账币种，在 receivers 中指定接收方商户号、资金用途和金额，并按接口要求序列化为 JSON 字符串。

profitCompleted 在 profitType=share 时必填，表示本次请求是否结束该笔支付的分账；后续还会继续分账时传 false。一旦传入 true，该笔支付后续分账请求会被拒绝。通过 API 发起时的完整条件见对应字段说明。

通过 API 发起的分账或分账回退使用 urlCallback 接收结果。原支付已配置 profitShareNotifyUrl 时，无需再传 urlCallback；未配置时，必须在本次 API 请求中提供 urlCallback。

处理分账结果

保存 profitReference 和 Onerway 返回的 profitGatewayReference，用于后续查询与分账回退。收到通知后，通过 relatedTxnId、relatedMerchantTxnId 关联原支付；这些字段为字符串，允许返回 null。已有分账记录也可按分账请求号与 Onerway 分账单号关联。

分账及分账回退通知使用通知体中的 sign 字段验签，具体算法见分账及分账回退通知验签。使用收到的原始 receivers 字符串参与验签，不要解析后重新序列化。成功接收并受理后返回 HTTP 200，响应体可为空。

state=completed 只表示整体处理结束，不代表每条明细都成功。逐条检查 receivers[].result；失败时结合 failReason 排查，但不要根据其文本内容判断处理结果。

查询分账结果

未收到通知或需要核对结果时，调用查询分账结果。使用原支付的收款商户号，并通过 profitType=share 或 return 选择分账或分账回退。

profitReference、gatewayReference、profitGatewayReference、relatedTxnId 和 relatedMerchantTxnId 至少提供一个；同时提供多个时按组合条件过滤。可按原支付的 relatedTxnId 或 relatedMerchantTxnId 查询，也可使用已保存的分账请求号或 Onerway 分账单号。查询字段、适用条件和示例见 API 参考。

查询中的 gatewayReference 随单据类型变化：share 时指原 SALE 支付的 transactionId，return 时指被回退的 Onerway 分账单号。按原支付查询分账回退时，使用 relatedTxnId。

查询请求中的商户号和交易流水号建议使用字符串，避免数值精度损失。查询响应返回 data.sign，但商户无需对查询响应验签；这不改变分账 Webhook 的验签要求。

分账回退

需要通过 API 回退已有分账时，调用发起分账或分账回退，设置 profitType=return：

  • 为本次回退提供新的全局唯一 profitReference，并通过 currency 提交回退币种。
  • profitParentReference 使用原分账请求号；自动分账时该请求号由 Onerway 生成，可从查询结果或通知中取得。
  • profitGatewayReference 使用被回退的原 Onerway 分账单号。
  • 为每条回退明细提供在本次 profitReference 下唯一的 profitDetailReference。
  • 明细中的 profitDetailParentReference 使用原分账明细请求号，profitDetailGatewayReference 使用原 Onerway 分账明细单号。接收方使用原明细的接收方商户号。金额与其他条件见接口字段说明。
  • 发起回退时不传 gatewayReference；这与查询回退结果时该字段的含义不同。

分账回退也通过通知或查询确认处理结果，并逐条检查明细。不要将提交回退请求视为回退成功。

各接入方式的参数差异

三种接入方式都在创建支付时配置 paymentMethodOptions.share；自动分账规则相同。通过 API 发起分账、查询或分账回退时，均由商户服务端调用分账接口。

接入方式接口关键参数差异说明接入指南
收银台创建收银台支付paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无收银台接入
Web SDK创建 SDK 交易paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无Web SDK 接入
API 直连创建直连交易paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无API 直连接入

预授权与请款

先冻结额度、后按履约请款：预授权的适用范围、从授权到请款或撤销的生命周期与通知、边界与状态判断，以及三种接入方式的参数差异。

退款

申请退款、处理退款结果与审核拒绝通知，并在需要时查询结果或取消尚未获批的退款申请。