> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get list of settlements

> 查询结算列表，支持可选的筛选条件。

#### 使用说明
- 如果同时省略 `settled_start_time` 和 `settled_end_time`，接口将返回默认时间窗口内的第一页结算记录：从今天往前一个月起至今天（含当天）。
- 指定日期范围时，必须同时提供 `settled_start_time` 和 `settled_end_time`。两者间隔不得超过一个月，且 `settled_end_time` 必须大于或等于 `settled_start_time`。




## OpenAPI

````yaml /zh/global-acquiring/v1.6/payment.yaml get /v2/payment/settlements
openapi: 3.0.2
info:
  title: Payment API
  version: 0.0.1
  x-source-en-commit: 821171b
  x-source-en-path: global-acquiring/v1.6/payment.yaml
  description: >
    UQPAY Payment API 让你接受付款、管理交易，并处理退款与出款。


    ## 功能概览

    - 使用卡、数字钱包和本地支付方式创建并确认 PaymentIntent

    - 处理全额和部分退款

    - 管理客户与已保存的支付方式

    - 创建出款与银行账户记录

    - 查询 PaymentAttempt、余额与交易历史


    ## 身份认证

    所有请求都需要携带有效的鉴权 Token，Token 通过 [Access
    Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在
    `x-auth-token` 请求头中携带该 Token。


    ## 幂等性

    POST 请求支持 `x-idempotency-key` 请求头，可在不重复创建资源的前提下安全重试。
  contact:
    name: UQPAY Support Team
    url: https://www.uqpay.com/support
    email: support@uqpay.com
  license:
    name: Proprietary
    url: https://www.uqpay.com/legal/api-terms
  termsOfService: https://www.uqpay.com/legal/terms
servers:
  - url: https://api-sandbox.uqpaytech.com/api
    description: 沙盒环境基础 URL。
  - url: https://api.uqpay.com/api
    description: 生产环境基础 URL。
security:
  - XAuthToken: []
tags:
  - name: Customers
    description: 创建和管理客户档案。客户对象保存支付方式和账单信息，可在多笔支付中复用。
  - name: Payment Intents
    description: >-
      PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该
      PaymentIntent，查看某次会话的 PaymentAttempt 历史。
  - name: Payment Attempts
    description: >-
      每当客户使用所选 PaymentMethod 付款时，都会创建一个 PaymentAttempt 对象。通过该 API
      可以了解客户是如何为订单付款的。
  - name: Payment Refunds
    description: >
      你可以创建多笔部分退款，直至累计达到原交易金额。每笔退款都会生成唯一记录，并自动校验可用余额。

      PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该
      PaymentIntent，查看某次会话的 PaymentAttempt 历史。
  - name: Payment Balances
    description: |
      支付余额管理让你查询不同币种的账户余额。你可以查询单个币种的余额，也可以分页查询所有币种的余额。
  - name: Payment Payouts
    description: |
      出款管理让你创建和管理用于资金划转的出款单。你可以创建出款、查询单笔出款，也可以分页并按条件筛选列出所有出款。
  - name: Terminal Management
    description: 用于 POS 设备注册和密钥管理的终端管理 API。
  - name: Bank Accounts
    description: |
      用于结算账户的银行账户管理 API。可创建、更新、查询和列出用于接收结算款项的银行账户。
paths:
  /v2/payment/settlements:
    get:
      tags:
        - Payment Reports
      summary: Get list of settlements
      description: >
        查询结算列表，支持可选的筛选条件。


        #### 使用说明

        - 如果同时省略 `settled_start_time` 和
        `settled_end_time`，接口将返回默认时间窗口内的第一页结算记录：从今天往前一个月起至今天（含当天）。

        - 指定日期范围时，必须同时提供 `settled_start_time` 和 `settled_end_time`。两者间隔不得超过一个月，且
        `settled_end_time` 必须大于或等于 `settled_start_time`。
      operationId: get-list-of-settlements
      parameters:
        - $ref: '#/components/parameters/XOnBehalfOf'
        - $ref: '#/components/parameters/XIdempotencyKey'
        - $ref: '#/components/parameters/SETTLEMENT_PaymentIntentId'
        - $ref: '#/components/parameters/SettlementBatchId'
        - $ref: '#/components/parameters/SettledStartTime'
        - $ref: '#/components/parameters/SettledEndTime'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: 成功获取结算列表
          content:
            application/json:
              schema:
                title: PaymentSettlementListResponse
                properties:
                  total_pages:
                    $ref: '#/components/schemas/TotalPages'
                  total_items:
                    $ref: '#/components/schemas/TotalItems'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SettlementObjectResponse'
components:
  parameters:
    XOnBehalfOf:
      in: header
      name: x-on-behalf-of
      schema:
        type: string
      required: false
      description: >
        指定代表哪个子账户发起该请求。应设置为 `account_id`，可通过 [List Connected
        Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts)
        获取。若省略或为空，则使用主账户执行请求。

        更多信息见 [Connected
        Accounts](/zh/account-center/v1.6/guide/connected-accounts)。
      example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
    XIdempotencyKey:
      in: header
      name: x-idempotency-key
      schema:
        type: string
        format: uuid
      required: true
      description: 用于保持操作幂等性的唯一标识符（UUID），确保同一操作重复执行不会产生意外影响或重复结果。它有助于在网络错误、重试或故障时保持数据一致性。
      example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde
    SETTLEMENT_PaymentIntentId:
      name: payment_intent_id
      in: query
      required: false
      description: PaymentIntent 的唯一 ID。
      schema:
        type: string
        example: PI1945730395043532800
    SettlementBatchId:
      name: settlement_batch_id
      in: query
      required: false
      description: 结算批次的标识符。
      schema:
        type: string
        example: SB1947180993781698560
    SettledStartTime:
      name: settled_start_time
      in: query
      required: false
      description: |
        用于按 settlement_date 筛选的起始日期（含），格式为 YYYY-MM-DD。时间基于 UTC+8。

        示例：'2025-07-01' 表示 settlement_date ≥ 2025-07-01T00:00:00（UTC+8）。
      schema:
        type: string
        example: '2025-07-01'
    SettledEndTime:
      name: settled_end_time
      in: query
      required: false
      description: |
        用于按 settlement_date 筛选的结束日期（含），格式为 YYYY-MM-DD。时间基于 UTC+8。

        示例：'2025-07-31' 表示 settlement_date ≤ 2025-07-31T23:59:59（UTC+8）。
      schema:
        type: string
        example: '2025-07-31'
    PageNumber:
      name: page_number
      description: 用于获取下一批条目的页码，取值必须大于 1。
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        example: 1
    PageSize:
      name: page_size
      description: 每页返回的最大条目数，取值范围 1 - 100。
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        example: 10
        maximum: 100
  schemas:
    TotalPages:
      type: integer
      example: 10
      description: 可用条目的总页数。
    TotalItems:
      type: integer
      example: 105
      description: 可用条目的总数。
    SettlementObjectResponse:
      type: object
      properties:
        settlement_id:
          $ref: '#/components/schemas/SETTLEMENT_SettlementId'
        account_id:
          $ref: '#/components/schemas/SETTLEMENT_AccountId'
        account_name:
          $ref: '#/components/schemas/SETTLEMENT_AccountName'
        source_type:
          $ref: '#/components/schemas/SETTLEMENT_SourceType'
        transaction_type:
          $ref: '#/components/schemas/SETTLEMENT_TransactionType'
        merchant_order_id:
          $ref: '#/components/schemas/SETTLEMENT_MerchantOrderId'
        payment_intent_id:
          $ref: '#/components/schemas/SETTLEMENT_PaymentIntentId'
        payment_method:
          $ref: '#/components/schemas/SETTLEMENT_PaymentMethod'
        transaction_create_date:
          $ref: '#/components/schemas/SETTLEMENT_TransactionCreateDate'
        transaction_amount:
          $ref: '#/components/schemas/SETTLEMENT_TransactionAmount'
        transaction_currency:
          $ref: '#/components/schemas/SETTLEMENT_TransactionCurrency'
        transaction_date:
          $ref: '#/components/schemas/SETTLEMENT_TransactionDate'
        settlement_amount:
          $ref: '#/components/schemas/SETTLEMENT_SettlementAmount'
        settlement_currency:
          $ref: '#/components/schemas/SETTLEMENT_SettlementCurrency'
        net_settlement_amount:
          $ref: '#/components/schemas/SETTLEMENT_NetSettlementAmount'
        exchange_rate:
          $ref: '#/components/schemas/SETTLEMENT_ExchangeRate'
        fee_currency:
          $ref: '#/components/schemas/SETTLEMENT_FeeCurrency'
        interchange_fee:
          $ref: '#/components/schemas/SETTLEMENT_InterchangeFee'
        scheme_fee:
          $ref: '#/components/schemas/SETTLEMENT_SchemeFee'
        transcation_fee:
          $ref: '#/components/schemas/SETTLEMENT_TranscationFee'
        return_fee:
          $ref: '#/components/schemas/SETTLEMENT_ReturnFee'
        total_fee_amount:
          $ref: '#/components/schemas/SETTLEMENT_TotalFeeAmount'
        settlement_status:
          $ref: '#/components/schemas/SETTLEMENT_SettlementStatus'
        settlement_batch_id:
          $ref: '#/components/schemas/SETTLEMENT_SettlementBatchId'
        settlement_create_date:
          $ref: '#/components/schemas/SETTLEMENT_SettlementCreateDate'
        settlement_date:
          $ref: '#/components/schemas/SETTLEMENT_SettlementDate'
    SETTLEMENT_SettlementId:
      type: string
      description: 结算的唯一标识（UUID）。
      example: ST1945730404245835776
    SETTLEMENT_AccountId:
      type: string
      description: 与该结算关联的账户 UUID。
      example: a7b92a19-bfc3-4c8b-8a4f-cfcf74cab345
    SETTLEMENT_AccountName:
      type: string
      description: 账户名称。
      example: UQPAY PTE. LTD.
    SETTLEMENT_SourceType:
      type: string
      description: 交易记录的来源类型。
      example: PAYMENT
    SETTLEMENT_TransactionType:
      type: string
      description: 交易类型。
      example: PAYMENT
    SETTLEMENT_MerchantOrderId:
      $ref: '#/components/schemas/MerchantOrderId'
    SETTLEMENT_PaymentIntentId:
      $ref: '#/components/schemas/PaymentIntentId'
    SETTLEMENT_PaymentMethod:
      type: string
      description: |
        该交易使用的支付方式。
        - `card`：卡支付（Visa、Mastercard、UnionPay）。
        - `alipaycn`：支付宝（中国大陆）。
        - `alipayhk`：AlipayHK（中国香港）。
        - `unionpay`：UnionPay 二维码支付。
        - `wechatpay`：WeChat Pay。
      example: card
      enum:
        - card
        - alipaycn
        - alipayhk
        - unionpay
        - wechatpay
    SETTLEMENT_TransactionCreateDate:
      $ref: '#/components/schemas/DateTime'
      description: 交易的创建时间（ISO 8601 日期时间，UTC）。
    SETTLEMENT_TransactionAmount:
      $ref: '#/components/schemas/Amount'
      description: 交易金额。
      example: '7.77'
    SETTLEMENT_TransactionCurrency:
      $ref: '#/components/schemas/Currency'
      example: SGD
    SETTLEMENT_TransactionDate:
      $ref: '#/components/schemas/DateTime'
      description: 交易（PaymentIntent 或 Refund）的完成时间。
      example: '2025-07-17T14:20:50+08:00'
    SETTLEMENT_SettlementAmount:
      $ref: '#/components/schemas/Amount'
      description: 结算金额。
      example: '7.77'
    SETTLEMENT_SettlementCurrency:
      $ref: '#/components/schemas/Currency'
      example: SGD
    SETTLEMENT_NetSettlementAmount:
      $ref: '#/components/schemas/Amount'
      description: |
        净结算金额。
      example: '8.11'
    SETTLEMENT_ExchangeRate:
      type: string
      description: 从 `transaction_currency` 到 `settlement_currency` 所应用的汇率（如适用）。
      example: '1'
    SETTLEMENT_FeeCurrency:
      $ref: '#/components/schemas/Currency'
      example: SGD
    SETTLEMENT_InterchangeFee:
      $ref: '#/components/schemas/FeeAmount'
      example: '0'
    SETTLEMENT_SchemeFee:
      $ref: '#/components/schemas/FeeAmount'
      example: '0'
    SETTLEMENT_TranscationFee:
      $ref: '#/components/schemas/FeeAmount'
      example: '0.34'
    SETTLEMENT_ReturnFee:
      $ref: '#/components/schemas/FeeAmount'
      example: '0'
    SETTLEMENT_TotalFeeAmount:
      $ref: '#/components/schemas/FeeAmount'
      example: '0.34'
    SETTLEMENT_SettlementStatus:
      type: string
      description: 结算的状态。仅会返回 `SUCCEEDED`。
      example: SUCCEEDED
      enum:
        - SUCCEEDED
    SETTLEMENT_SettlementBatchId:
      type: string
      description: 结算批次的标识符。
      example: SB1947180993781698560
    SETTLEMENT_SettlementCreateDate:
      $ref: '#/components/schemas/DateTime'
      description: 结算记录的创建时间。
      example: '2025-07-17T14:20:52+08:00'
    SETTLEMENT_SettlementDate:
      $ref: '#/components/schemas/DateTime'
      description: 结算的完成时间。
      example: '2025-07-21T14:25:01+08:00'
    MerchantOrderId:
      type: string
      maxLength: 36
      description: 商户系统中为该 PaymentIntent 创建的商户参考 ID
    PaymentIntentId:
      type: string
      description: PaymentIntent 的 ID。
      example: PI1234567890123456789
    DateTime:
      type: string
      format: date/time
      example: '2024-03-01T00:00:00+08:00'
    Amount:
      type: string
    Currency:
      type: string
      description: 三位币种代码
    FeeAmount:
      type: string
      description: 手续费金额。
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: UQPay 提供的登录 API Token。

````