# 分账

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

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

## 概念与选择

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

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

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

<note>

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

</note>

## 生命周期与通知

<steps level="3">

### 创建支付并配置通知地址

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

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

### 确认支付成功

按所用接入方式确认支付结果，并保存原交易的 `transactionId`、商户订单号及收款商户号。支付结果的通知处理见 [Webhook 通知](/zh/payments/get-started/webhooks)；分账结果使用独立的[分账结果通知](/zh/payments/api-reference/webhooks/profit-share-result)。

### 自动分账或调用分账接口

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

通过 API 发起时，调用[发起分账或分账回退](/zh/payments/api-reference/endpoints/create-or-reverse-profit-share)，设置 `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` 字段验签，具体算法见[分账及分账回退通知验签](/zh/payments/get-started/request-signing#%E5%88%86%E8%B4%A6%E5%8F%8A%E5%88%86%E8%B4%A6%E5%9B%9E%E9%80%80%E9%80%9A%E7%9F%A5)。使用收到的原始 `receivers` 字符串参与验签，不要解析后重新序列化。成功接收并受理后返回 HTTP 200，响应体可为空。

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

</steps>

## 查询分账结果

未收到通知或需要核对结果时，调用[查询分账结果](/zh/payments/api-reference/endpoints/query-profit-share)。使用原支付的收款商户号，并通过 `profitType=share` 或 `return` 选择分账或分账回退。

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

<note>

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

</note>

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

## 分账回退

需要通过 API 回退已有分账时，调用[发起分账或分账回退](/zh/payments/api-reference/endpoints/create-or-reverse-profit-share)，设置 `profitType=return`：

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

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

## 各接入方式的参数差异

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

| 接入方式 | 接口 | 关键参数 | 差异说明 | 接入指南 |
| --- | --- | --- | --- | --- |
| 收银台 | [创建收银台支付](/zh/payments/api-reference/endpoints/create-checkout-payment#request-paymentMethodOptions) | `paymentMethodOptions.share`：`profitShare`、`profitShareRate`、`profitShareNotifyUrl` | 无 | [收银台接入](/zh/payments/online-payments/checkout#%E5%88%86%E8%B4%A6) |
| Web SDK | [创建 SDK 交易](/zh/payments/api-reference/endpoints/sdk-create-transaction#request-paymentMethodOptions) | `paymentMethodOptions.share`：`profitShare`、`profitShareRate`、`profitShareNotifyUrl` | 无 | [Web SDK 接入](/zh/payments/online-payments/sdk#%E5%88%86%E8%B4%A6) |
| API 直连 | [创建直连交易](/zh/payments/api-reference/endpoints/direct-create-transaction#request-paymentMethodOptions) | `paymentMethodOptions.share`：`profitShare`、`profitShareRate`、`profitShareNotifyUrl` | 无 | [API 直连接入](/zh/payments/online-payments/api#%E5%88%86%E8%B4%A6) |