# 查询账户余额变动流水

> 查询调用方商户账户或指定子商户账户的余额变动记录。

```yaml
openapi: 3.1.0
info:
  title: 查询账户余额变动流水
  version: 1.0.0
  description: 查询调用方商户账户或指定子商户账户的余额变动记录。
paths:
  /api/v2/account/transactions/query:
    post:
      summary: 查询账户余额变动流水
      description: 查询调用方商户账户或指定子商户账户的余额变动记录。
      parameters:
        - name: apikey
          in: header
          required: true
          description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
          schema:
            type: string
            description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
        - name: x-timestamp
          in: header
          required: true
          description: 请求时间戳；网关使用该 Header 防止请求被重放。
          schema:
            type: string
            description: 请求时间戳；网关使用该 Header 防止请求被重放。
            x-onerway-constraints:
              - kind: rule
                text: 时间戳必须在服务端当前时间 10分钟以内；支持 10 位秒级或 13 位毫秒级时间戳。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: 请求 ID，用于幂等控制和链路追踪。
                onBehalfOf:
                  type: string
                  description: 平台商户代子商户查询时使用的子商户号。未传时，查询 `apikey` 所属商户的账户流水；传入时，调用方商户必须是该子商户的父商户。
                currency:
                  type: string
                  description: 可选的交易币种过滤条件；使用 [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    三位字母货币代码。
                balanceType:
                  type: string
                  description: 可选的余额类型过滤条件。
                  enum:
                    - PAYMENT
                    - FUNDING
                    - PENDING_SETTLEMENT
                    - ON_HOLD
                    - RISK_DEPOSIT
                  x-enum-descriptions:
                    PAYMENT: Payment 账户余额。
                    FUNDING: Funding 账户余额。
                    PENDING_SETTLEMENT: 待结算余额。
                    ON_HOLD: 冻结余额。
                    RISK_DEPOSIT: 风险保证金余额。
                acntTxnId:
                  type: string
                  description: 可选的账户流水 ID 精确过滤条件，使用数字字符串。
                beginTime:
                  type: string
                  description: 查询范围的开始时间，按 `balanceUpdDate` 过滤。
                  x-onerway-constraints:
                    - kind: rule
                      text: 使用带时区偏移的 ISO-8601 时间戳，例如 `2026-07-20T00:00:00+08:00`。
                endTime:
                  type: string
                  description: 查询范围的结束时间，按 `balanceUpdDate` 过滤。
                  x-onerway-constraints:
                    - kind: consistency
                      text: "`endTime` 不能早于 `beginTime`。"
                    - kind: range
                      max: 31
                      unit: 天
                      text: 查询时间范围不能超过 31 天。
                businessType:
                  type: string
                  description: 可选的业务类型过滤条件。
                  enum:
                    - ACQUIRING
                    - PAYOUT
                  x-enum-descriptions:
                    ACQUIRING: 收单业务余额变动。
                    PAYOUT: 付款业务余额变动。
                current:
                  type: number
                  description: 当前查询页码；`size` 由服务端控制，请使用 `current` 翻页。
              required:
                - requestId
                - beginTime
                - endTime
            examples:
              query-transactions-by-time-range:
                summary: 按时间范围查询 USD 账户流水
                value:
                  requestId: REQ-TRX-20260423-0001
                  currency: USD
                  beginTime: 2026-04-01T00:00:00+08:00
                  endTime: 2026-04-23T23:59:59+08:00
                  current: 1
      responses:
        "200":
          description: 分页 USD 账户流水
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 标准化响应码；`20000` 表示成功。
                  respMsg:
                    type: string
                    description: 与 `respCode` 对应的可读响应信息。
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: 符合查询条件的总记录数。
                      pages:
                        type: integer
                        description: 总页数。
                      current:
                        type: integer
                        description: 当前页码。
                      list:
                        type: array
                        description: 当前页中所选商户账户的余额变动记录。
                        items:
                          type: object
                          properties:
                            acntTxnId:
                              type: integer
                              description: 账户流水 ID，用于标识单条余额变动记录。
                            serviceId:
                              type: integer
                              description: 与该笔余额变动关联的交易单号。
                            currency:
                              type: string
                              description: 交易币种。
                            balanceType:
                              type: string
                              description: 受影响的余额类型。
                              enum:
                                - PAYMENT
                                - FUNDING
                                - PENDING_SETTLEMENT
                                - ON_HOLD
                                - RISK_DEPOSIT
                              x-enum-descriptions:
                                PAYMENT: Payment 账户余额。
                                FUNDING: Funding 账户余额。
                                PENDING_SETTLEMENT: 待结算余额。
                                ON_HOLD: 冻结余额。
                                RISK_DEPOSIT: 风险保证金余额。
                            amount:
                              type: string
                              description: 带符号的余额变动金额；正数表示余额增加，负数表示余额减少。
                            balanceUpdDate:
                              type: string
                              description: 余额更新时间，使用 UTC ISO-8601 格式。
                            businessType:
                              type: string
                              description: 触发该余额变动的业务类型。
                              enum:
                                - ACQUIRING
                                - PAYOUT
                              x-enum-descriptions:
                                ACQUIRING: 收单业务余额变动。
                                PAYOUT: 付款业务余额变动。
                            externalOrderId:
                              type: string
                              description: 上游业务系统传入的外部订单号，可选。
                            remark:
                              type: string
                              description: 交易备注。
                    description: 分页账户余额变动流水数据，账户范围由 `apikey` 和可选的 `onBehalfOf` 决定。
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: 对外业务错误码，与 `respCode` 对齐。
                      declineCode:
                        type: string
                        description: 兼容字段，与 `code` 保持一致。
                      message:
                        type: string
                        description: 可读错误信息。
                      type:
                        type: string
                        description: 标准化错误类型。
                      param:
                        type: string
                        description: 触发错误的请求参数名，可选。
                      requestId:
                        type: string
                        description: 调用方请求 ID，与 body `requestId` 保持一致。
                    description: 标准化错误对象；成功响应中该字段为 null，序列化时省略。
              examples:
                query-transactions-by-time-range:
                  summary: 分页 USD 账户流水
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      total: 50
                      pages: 3
                      current: 1
                      list:
                        - acntTxnId: 10001
                          serviceId: 20001
                          currency: USD
                          balanceType: PAYMENT
                          amount: "-100.00"
                          balanceUpdDate: 2026-04-20T10:30:00Z
                          businessType: PAYOUT
                          externalOrderId: replace_with_external_order_id
                          remark: Payout to bank account
                        - acntTxnId: 10002
                          serviceId: 20002
                          currency: USD
                          balanceType: PAYMENT
                          amount: "500.00"
                          balanceUpdDate: 2026-04-19T08:15:00Z
                          businessType: ACQUIRING
                          externalOrderId: replace_with_external_order_id
                          remark: Payment received
      x-onerway-lifecycle:
        phase: active
        access:
          description:
            en: Access to the Account service APIs is enabled by Onerway approval.
            zh: 账户服务 API 的访问权限需经 Onerway 审批后开通。
```