分账服务

分账服务用于在支付交易完成后，将订单资金按业务约定分配给一个或多个接收方，并支持对已发起的分账进行撤销。本文覆盖分账与撤销请求、结果查询，以及由 Onerway 推送给商户的分账结果通知。

适合以下场景：

• 支付交易完成后，需要按业务约定向多个接收方分配资金。
• 需要按接收方明细跟踪分账金额、处理结果和失败原因。
• 需要撤销已发起的分账，并保留原分账单与原明细的关联。
• 需要通过 webhook 和主动查询完成异步结果确认与对账。

使用前提

使用分账服务前，请先在支付创建请求中传 profitSharing: true 启用分账。支付完成后，再使用该笔支付的 gatewayReference 发起分账请求。

接口路径

本文请求示例使用 sandbox 地址。生产环境请将 base URL 替换为 Onerway 分配给商户的正式 API 域名。

本文不包含分账准入校验接口。

接口列表

操作	Endpoint	说明
分账和撤销	POST /profit/share	发起分账，或撤销一笔已发起的分账。
分账和撤销结果查询	POST /profit/query	查询分账或分账撤销的处理结果。
分账和撤销结果通知	商户提供的回调地址	Onerway 向商户推送异步处理结果。

分账和撤销

POST

使用该接口发起分账或分账撤销。profitReference 是商户侧请求号，也是幂等键，请确保全局唯一。撤销分账时，需要传入原分账请求号、原分账单号和原分账明细信息。

请求参数

注意

• 所有 JSON 字段必须在提交前进行字符串化处理
• 嵌套对象必须序列化为 JSON 字符串格式
• JSON 字段不能包含未转义的特殊字符
• JSON 中的数组应该正确格式化
• JSON 字符串字段示例：

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Required	Signed	Description
merchantNo	String	Yes	Yes	Merchant number that starts this profit sharing or cancellation request.
profitType	String	Yes	Yes	Business type. Use share for profit sharing and return for profit sharing cancellation. Available values: share / return .
profitReference	String	Yes	Yes	Merchant-side profit sharing or cancellation request number. It is used as an idempotency key and must be globally unique.
gatewayReference	String	Conditional	Yes	Onerway payment transaction ID, corresponding to the existing transactionId field. Required when profitType=share; not required when profitType=return.
profitParentReference	String	Conditional	Yes	Original profit sharing request number. Required when profitType=return.
profitGatewayReference	String	Conditional	Yes	Original Onerway profit sharing order number. Required when profitType=return.
currency	String	Yes	Yes	Profit sharing or cancellation currency. Use a three-letter currency code whenever possible.
urlCallback	String	Yes	Yes	Callback URL used to receive asynchronous profit sharing or cancellation results.
profitCompleted	Boolean	Conditional	Yes	Whether all profit sharing plans for this payment order have been completed. Applies when profitType=share. Available values: true - no further profit sharing will be submitted; false - more profit sharing requests may be submitted later.
receivers	String (JSON array)	Yes	Yes	Receiver list for profit sharing or cancellation. Submit this field as a JSON string. See receivers structure for complete structure.
sign	String	Yes	No	Request signature generated according to the Onerway signature rules.

receivers

receivers 字段在请求中按 JSON string 传输，内部数组对象字段如下。

Field	Type	Required	Description
profitDetailReference	String	Yes	Merchant-side detail request number. Keep it unique under the same profitReference.
profitDetailParentReference	String	Conditional	Original profit sharing detail request number. Required when profitType=return.
profitDetailGatewayReference	String	Conditional	Original Onerway profit sharing detail order number. Required when profitType=return.
type	String	Yes	Profit sharing detail type code. This field identifies the fund usage or profit sharing reason; it is not the receiver account type. Available values: detail type codes .
account	String	Yes	Receiver merchant number. For cancellation, use the receiver merchant number from the original profit sharing detail.
amount	String	Yes	Profit sharing or cancellation amount, expressed as a decimal string.
description	String	No	Detail description for reconciliation and troubleshooting.

响应参数

以下为分账结果业务字段。接入时请以实际接口返回结构读取这些业务字段。

Field	Type	Description
profitType	String	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Onerway profit sharing or cancellation order number.
state	String	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Receiver processing result list returned as a JSON string. See receivers structure for complete structure.

receivers

receivers 字段在响应中按 JSON string 返回，内部数组对象字段如下。

Field	Type	Description
profitDetailReference	String	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Onerway profit sharing or cancellation detail order number.
type	String	Nullable. Profit sharing detail type code when returned. Available values: detail type codes .
amount	String	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	Nullable. Failure reason when result=failed; otherwise returns null.
createdAt	String	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	Nullable. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

API 使用示例

分账请求

{
  "merchantNo": "800209",
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "gatewayReference": "203000000000000001",
  "currency": "USD",
  "urlCallback": "https://merchant.example.com/webhooks/profit-sharing",
  "profitCompleted": false,
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"type\":\"1\",\"account\":\"800210\",\"amount\":\"80.00\",\"description\":\"Seller settlement\"},{\"profitDetailReference\":\"psd_202606220002\",\"type\":\"2\",\"account\":\"800211\",\"amount\":\"20.00\",\"description\":\"Platform service fee\"}]",
  "sign": "a1b2c3d4e5f6..."
}

撤销请求

{
  "merchantNo": "800209",
  "profitType": "return",
  "profitReference": "psr_202606220001",
  "profitParentReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "currency": "USD",
  "urlCallback": "https://merchant.example.com/webhooks/profit-sharing",
  "receivers": "[{\"profitDetailReference\":\"psrd_202606220001\",\"profitDetailParentReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"account\":\"800210\",\"amount\":\"80.00\",\"description\":\"Reverse seller settlement\"}]",
  "sign": "a1b2c3d4e5f6..."
}

响应参数

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "processing",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"pending\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":null}]"
}

示例说明

以上示例仅用于说明字段结构，请勿直接作为生产请求参数使用。

分账和撤销结果查询

POST

使用该接口查询分账或分账撤销的处理结果。查询时需要传入 profitType、profitReference 和 Onerway 返回的 profitGatewayReference。

请求参数

Parameter	Type	Required	Signed	Description
merchantNo	String	Yes	Yes	Merchant number that starts the query.
profitType	String	Yes	Yes	Business type to query. Use share for profit sharing results and return for cancellation results. Available values: share / return .
profitReference	String	Yes	Yes	Merchant-side profit sharing or cancellation request number.
gatewayReference	String	No	Yes	Onerway payment transaction ID, corresponding to the existing transactionId field. Optional for queries.
profitGatewayReference	String	Yes	Yes	Onerway profit sharing or cancellation order number.
sign	String	Yes	No	Request signature generated according to the Onerway signature rules.

响应参数

查询接口返回的业务字段与分账请求接口一致。

Field	Type	Description
profitType	String	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Onerway profit sharing or cancellation order number.
state	String	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Receiver processing result list returned as a JSON string. See receivers structure for complete structure.

receivers

Field	Type	Description
profitDetailReference	String	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Onerway profit sharing or cancellation detail order number.
type	String	Nullable. Profit sharing detail type code when returned. Available values: detail type codes .
amount	String	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	Nullable. Failure reason when result=failed; otherwise returns null.
createdAt	String	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	Nullable. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

API 使用示例

请求参数

{
  "merchantNo": "800209",
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "gatewayReference": "203000000000000001",
  "profitGatewayReference": "pg_203000000000000001",
  "sign": "a1b2c3d4e5f6..."
}

响应参数

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "completed",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"success\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":\"2026-06-22 10:00:08\"}]"
}

分账和撤销结果通知

分账或分账撤销处理完成后，Onerway 会向请求中的 urlCallback 推送结果通知。通知内容中的 receivers 字段同样按 JSON string 传输。

Webhook 请求参数

Field	Type	Required	Description
profitType	String	Yes	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Yes	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Yes	Onerway profit sharing or cancellation order number.
state	String	Yes	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Yes	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Yes	Receiver processing result list sent as a JSON string. See receivers structure for complete structure.
sign	String	Yes	Notification signature. Verify it according to the Onerway webhook signature rules.

receivers

Field	Type	Required	Description
profitDetailReference	String	Yes	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Yes	Onerway profit sharing or cancellation detail order number.
type	String	No	Profit sharing detail type code. It identifies the fund usage or profit sharing reason. Available values: detail type codes .
amount	String	Yes	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Yes	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	No	Failure reason when result=failed; returns null when the detail is not failed.
createdAt	String	Yes	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	No	Detail completion time. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

Webhook 响应

商户系统返回 HTTP 200 即表示通知接收成功；不需要在响应 body 中返回固定 JSON payload。

Webhook 示例

通知

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "completed",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"success\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":\"2026-06-22 10:00:08\"}]",
  "sign": "a1b2c3d4e5f6..."
}

响应

HTTP/1.1 200 OK

常见响应处理

情况	处理建议
请求验签失败	检查参与签名的非空请求参数、参数排序、密钥和 sign 排除规则。
receivers 格式错误	确认 receivers 为 JSON string，且内部数组字段名和必填字段符合本文参数表。
分账仍在处理中	当 state=processing 或明细 result=pending 时，等待 webhook 或再次主动查询。
明细处理失败	通过 receivers[].failReason 定位失败原因，并按商户侧对账规则处理。

接口还可能返回 IP 白名单、权限校验、参数校验或下游系统映射后的其他错误信息，具体以实际响应为准。

最佳实践

1. 使用全局唯一的 profitReference，并在商户侧落库 profitGatewayReference 用于查询和撤销。
2. receivers 请按 JSON string 传输；签名前确认字符串内容与实际请求内容一致。
3. 撤销分账时，保留并传入原分账请求号、原分账单号和原分账明细单号。
4. 不要仅根据 state=completed 判断全部成功，请逐条检查 receivers[].result。
5. 将 webhook 作为异步结果入口，并使用 POST /profit/query 作为补偿查询和对账手段。

相关文档链接

• 签名
• 交易 Webhook
• 交易订单查询
• Payment 查询
• 货币支持