# 查询分账结果

> 查询一笔分账或分账回退的处理结果与各接收方明细。

```yaml
openapi: 3.1.0
info:
  title: 查询分账结果
  version: 1.0.0
  description: 查询一笔分账或分账回退的处理结果与各接收方明细。
paths:
  /profit/query:
    post:
      summary: 查询分账结果
      description: 查询一笔分账或分账回退的处理结果与各接收方明细。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                gatewayReference:
                  type: string
                  description: "`share` 时为原 SALE 支付的 `transactionId`；`return` 时为被回退的 Onerway
                    分账单号。按原支付交易查询分账回退时，使用 `relatedTxnId`。"
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`profitReference`、`gatewayReference`、`profitGatewayRefer\
                      ence`、`relatedTxnId`、`relatedMerchantTxnId` 至少提供一个。"
                merchantNo:
                  type: string
                  description: 发起本次查询的商户号。
                  x-onerway-constraints:
                    - kind: rule
                      text: 接受字符串或 JSON 数字。建议使用字符串，避免数值精度损失并保留完整标识。
                    - kind: rule
                      text: 平台模式下，传入原支付的收款子商户号。通过 API 发起分账时，应与该分账请求中的 `merchantNo` 一致。
                profitGatewayReference:
                  type: string
                  description: 发起分账或分账回退时 Onerway 返回的单号。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`profitReference`、`gatewayReference`、`profitGatewayRefer\
                      ence`、`relatedTxnId`、`relatedMerchantTxnId` 至少提供一个。"
                profitReference:
                  type: string
                  description: 分账或分账回退请求号。通过 API 发起时，使用商户在发起请求中提供的请求号；自动分账或自动分账回退时，由 Onerway 生成。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`profitReference`、`gatewayReference`、`profitGatewayRefer\
                      ence`、`relatedTxnId`、`relatedMerchantTxnId` 至少提供一个。"
                relatedTxnId:
                  type: string
                  description: 原支付交易流水号；分账与分账回退均关联原支付交易。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`profitReference`、`gatewayReference`、`profitGatewayRefer\
                      ence`、`relatedTxnId`、`relatedMerchantTxnId` 至少提供一个。"
                  x-onerway-constraints:
                    - kind: rule
                      text: 接受字符串或 JSON 数字。建议使用字符串，避免数值精度损失并保留完整标识。
                    - kind: consistency
                      text: 同时提供多个查询标识时，按这些条件组合过滤。
                relatedMerchantTxnId:
                  type: string
                  description: 原支付的商户订单号；分账与分账回退均关联原支付订单。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`profitReference`、`gatewayReference`、`profitGatewayRefer\
                      ence`、`relatedTxnId`、`relatedMerchantTxnId` 至少提供一个。"
                  x-onerway-constraints:
                    - kind: consistency
                      text: 同时提供多个查询标识时，按这些条件组合过滤。
                profitType:
                  type: string
                  description: 要查询的单据类型：分账或分账回退。
                  enum:
                    - share
                    - return
                  x-enum-descriptions:
                    share: 查询分账结果。
                    return: 查询分账回退结果。
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
              required:
                - merchantNo
                - profitType
                - sign
            examples:
              query-profit-share:
                summary: 查询分账
                value:
                  gatewayReference: replace_with_transaction_id
                  merchantNo: replace_with_merchant_no
                  profitGatewayReference: replace_with_profit_gateway_reference
                  profitReference: example_profit_share_reference
                  profitType: share
                  sign: replace_with_calculated_signature
              query-profit-share-reversal:
                summary: 查询分账回退
                value:
                  merchantNo: replace_with_merchant_no
                  profitGatewayReference: replace_with_profit_reversal_gateway_reference
                  profitReference: example_profit_reversal_reference
                  profitType: return
                  sign: replace_with_calculated_signature
              query-profit-share-partially-failed:
                summary: 查询含失败明细的分账
                value:
                  gatewayReference: replace_with_transaction_id
                  merchantNo: replace_with_merchant_no
                  profitGatewayReference: replace_with_profit_gateway_reference
                  profitReference: example_partial_failure_profit_share_reference
                  profitType: share
                  sign: replace_with_calculated_signature
              query-reversal-by-original-order:
                summary: 按原商户订单查询分账回退
                value:
                  merchantNo: replace_with_merchant_no
                  profitType: return
                  relatedMerchantTxnId: example_payment_order
                  sign: replace_with_calculated_signature
              query-by-original-transaction:
                summary: 按原支付交易查询
                value:
                  merchantNo: replace_with_merchant_no
                  profitType: share
                  relatedTxnId: "9007199254740993"
                  sign: replace_with_calculated_signature
      responses:
        "200":
          description: 分账已完成
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 响应码；`20000`
                      表示查询处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                  respMsg:
                    type: string
                    description: 响应码对应的可读说明。
                  data:
                    type: object
                    properties:
                      profitType:
                        type: string
                        description: 被查询单据的类型。
                        enum:
                          - share
                          - return
                        x-enum-descriptions:
                          share: 查询分账结果。
                          return: 查询分账回退结果。
                      profitReference:
                        type: string
                        description: 被查询的分账或分账回退请求号。通过 API 发起时，返回商户在发起请求中提供的请求号；自动分账或自动分账回退时，由 Onerway
                          生成。
                      profitGatewayReference:
                        type: string
                        description: 被查询单据的 Onerway 单号。
                      state:
                        type: string
                        description: 分账单整体处理状态。`completed` 不代表每条明细都成功，需逐条检查 `receivers[].result`。
                        enum:
                          - processing
                          - completed
                        x-enum-descriptions:
                          processing: 分账单处理中。
                          completed: 分账单处理结束；单条明细结果需逐条检查。
                      currency:
                        type: string
                        description: 分账或分账回退结算币种。
                      relatedTxnId:
                        type:
                          - string
                          - "null"
                        description: 原支付交易流水号。分账回退仍关联原支付，而非分账单。
                        x-onerway-value:
                          nullable: true
                      relatedMerchantTxnId:
                        type:
                          - string
                          - "null"
                        description: 原支付的商户订单号。
                        x-onerway-value:
                          nullable: true
                      sign:
                        type: string
                        description: 响应签名。商户无需对本查询响应验签。
                      receivers:
                        type: string
                        description: 各接收方的处理结果列表。
                        contentMediaType: application/json
                        contentSchema:
                          type: array
                          items:
                            type: object
                            properties:
                              profitDetailReference:
                                type: string
                                description: 商户侧提交的明细请求号。
                              profitDetailGatewayReference:
                                type: string
                                description: Onerway 返回的明细单号。
                              type:
                                type:
                                  - string
                                  - "null"
                                description: 该明细对应的资金用途。
                                enum:
                                  - "1"
                                  - "2"
                                  - "3"
                                  - "4"
                                  - "5"
                                  - "6"
                                  - "7"
                                  - "99"
                                  - null
                                x-enum-descriptions:
                                  "1": 商户结算款：分给实际卖家、子商户或服务提供方的订单结算金额。
                                  "2": 平台服务费：归属平台的佣金、技术服务费与软件服务费。
                                  "3": 合作方佣金：支付给渠道、代理或分销合作方的佣金。
                                  "4": 支付处理费：收单处理费、交易处理费与支付通道相关费用。
                                  "5": 税费：VAT、GST 或其他需要单独归集的税项。
                                  "6": 物流履约费：物流、配送、仓储与履约相关费用。
                                  "7": 营销补贴：优惠、补贴、活动成本或由某一方承担的营销费用。
                                  "99": 其他：由 Onerway 与商户约定的其他分账用途。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Returns `null` when the fund purpose is not recorded.
                                    zh: 未记录资金用途时返回 `null`。
                              amount:
                                type: string
                                description: 实际分账或分账回退金额。
                                x-onerway-constraints:
                                  - kind: rule
                                    text: 金额使用 decimal string；商户系统应避免用二进制浮点数直接计算金额。
                              result:
                                type: string
                                description: 该明细的处理结果。
                                enum:
                                  - pending
                                  - success
                                  - failed
                                x-enum-descriptions:
                                  pending: 该明细处理中。
                                  success: 该明细处理成功。
                                  failed: 该明细处理失败；失败原因见 `failReason`。
                              failReason:
                                type:
                                  - string
                                  - "null"
                                description: 该明细的失败原因。
                                x-onerway-constraints:
                                  - kind: rule
                                    text: 面向排查的可读文本，取值不固定；程序分支应依据 `result`，不要匹配该字符串。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Returned only when `result` is `failed`; otherwise `null`.
                                    zh: 仅当 `result` 为 `failed` 时返回；其余情况为 `null`。
                              createdAt:
                                type: string
                                description: 明细创建时间。
                                x-onerway-constraints:
                                  - kind: rule
                                    text: 格式为 `yyyy-MM-dd HH:mm:ss`；不要按 Unix 时间戳解析。
                              finishedAt:
                                type:
                                  - string
                                  - "null"
                                description: 明细完成时间。
                                x-onerway-constraints:
                                  - kind: rule
                                    text: 格式为 `yyyy-MM-dd HH:mm:ss`；不要按 Unix 时间戳解析。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Returns `null` while `result` is `pending`.
                                    zh: "`result` 为 `pending` 时返回 `null`。"
                        x-onerway-format: json_string
                    description: 分账或分账回退结果。
              examples:
                query-profit-share:
                  summary: 分账已完成
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      profitType: share
                      profitReference: example_profit_share_reference
                      profitGatewayReference: replace_with_profit_gateway_reference
                      state: completed
                      currency: USD
                      relatedTxnId: "9007199254740993"
                      relatedMerchantTxnId: example_payment_order
                      sign: replace_with_response_signature
                      receivers: '[{"profitDetailReference":"example_profit_share_detail_reference","profitDetailGatewayReference":"replace_with_profit_detail_gateway_reference","type":"1","amount":"80.00","result":"success","failReason":null,"createdAt":"2026-06-22
                        10:00:00","finishedAt":"2026-06-22 10:00:08"}]'
                query-profit-share-reversal:
                  summary: 分账回退已完成
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      profitType: return
                      profitReference: example_profit_reversal_reference
                      profitGatewayReference: replace_with_profit_reversal_gateway_reference
                      state: completed
                      currency: USD
                      relatedTxnId: "9007199254740993"
                      relatedMerchantTxnId: example_payment_order
                      sign: replace_with_response_signature
                      receivers: '[{"profitDetailReference":"example_profit_reversal_detail_reference","profitDetailGatewayReference":"replace_with_profit_reversal_detail_gateway_reference","type":"1","amount":"80.00","result":"success","failReason":null,"createdAt":"2026-06-22
                        11:00:00","finishedAt":"2026-06-22 11:00:08"}]'
                query-profit-share-partially-failed:
                  summary: 分账已完成但有明细失败
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      profitType: share
                      profitReference: example_partial_failure_profit_share_reference
                      profitGatewayReference: replace_with_profit_gateway_reference
                      state: completed
                      currency: USD
                      relatedTxnId: "9007199254740993"
                      relatedMerchantTxnId: example_payment_order
                      sign: replace_with_response_signature
                      receivers: '[{"profitDetailReference":"example_successful_profit_detail_reference","profitDetailGatewayReference":"replace_with_successful_profit_detail_gateway_reference","type":"1","amount":"80.00","result":"success","failReason":null,"createdAt":"2026-06-22
                        12:00:00","finishedAt":"2026-06-22
                        12:00:08"},{"profitDetailReference":"example_failed_profit_detail_reference","profitDetailGatewayReference":"replace_with_failed_profit_detail_gateway_reference","type":"2","amount":"20.00","result":"failed","failReason":"Receiver
                        account is not enabled for profit
                        sharing.","createdAt":"2026-06-22
                        12:00:00","finishedAt":"2026-06-22 12:00:09"}]'
```