> ## 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

> Retrieve a list of settlements with optional filtering

#### Usage Guidelines
- If `settled_start_time` and `settled_end_time` are both omitted, the API returns the first page of settlements within the default window: from one month before today up to today (inclusive).
- When specifying the date range, both `settled_start_time` and `settled_end_time` must be provided. The interval between them must not exceed one month, and `settled_end_time` must be greater than or equal to `settled_start_time`.




## OpenAPI

````yaml /global-acquiring/v1.6/payment.yaml get /v2/payment/settlements
openapi: 3.0.2
info:
  title: Payment API
  version: 0.0.1
  description: >
    UQPAY Payment API allows you to accept payments, manage transactions, and
    process refunds and payouts.


    ## What you can do

    - Create and confirm payment intents using cards, digital wallets, and local
    payment methods

    - Process full and partial refunds

    - Manage customers and saved payment methods

    - Create payouts and bank account records

    - Query payment attempts, balances, and transaction history


    ## Authentication

    All requests require a valid auth token obtained via the [Access
    Token](/account-center/v1.6/api-reference/access-token) endpoint. Include
    the token in the `x-auth-token` header.


    ## Idempotency

    POST requests support the `x-idempotency-key` header to safely retry without
    creating duplicate resources.
  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: Sandbox base URL.
  - url: https://api.uqpay.com/api
    description: Production base URL.
security:
  - XAuthToken: []
tags:
  - name: Customers
    description: >-
      Create and manage customer profiles. Customer objects store payment
      methods and billing details for use across multiple payments.
  - name: Payment Intents
    description: >-
      A PaymentIntent guides you through the process of collecting a payment
      from your customer. We recommend that you create exactly one PaymentIntent
      for each order or customer session in your system. You can reference the
      PaymentIntent later to see the history of payment attempts for a
      particular session.
  - name: Payment Attempts
    description: >-
      A PaymentAttempt object is created whenever a customer makes a payment
      with the chosen PaymentMethod. This API allows you to find out how your
      customer paid for your order.
  - name: Payment Refunds
    description: >
      You can create multiple partial refunds until reaching the original
      transaction amount. Each refund generates a unique record and undergoes
      automatic validation against available balances.

      A PaymentIntent guides you through the process of collecting a payment
      from your customer. We recommend that you create exactly one PaymentIntent
      for each order or customer session in your system. You can reference the
      PaymentIntent later to see the history of payment attempts for a
      particular session.
  - name: Payment Balances
    description: >
      Payment balance management allows you to query account balances for
      different currencies. You can retrieve individual currency balances or all
      currency balances with pagination support.
  - name: Payment Payouts
    description: >
      Payout management allows you to create and manage payout orders for fund
      transfers. You can create payouts, query individual payouts, and list all
      payouts with filtering and pagination support.
  - name: Terminal Management
    description: Terminal management APIs for POS device registration and key management.
  - name: Bank Accounts
    description: >
      Bank account management APIs for settlement accounts. Create, update,
      retrieve, and list bank accounts used for receiving settlement payments.
paths:
  /v2/payment/settlements:
    get:
      tags:
        - Payment Reports
      summary: Get list of settlements
      description: >
        Retrieve a list of settlements with optional filtering


        #### Usage Guidelines

        - If `settled_start_time` and `settled_end_time` are both omitted, the
        API returns the first page of settlements within the default window:
        from one month before today up to today (inclusive).

        - When specifying the date range, both `settled_start_time` and
        `settled_end_time` must be provided. The interval between them must not
        exceed one month, and `settled_end_time` must be greater than or equal
        to `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: List of settlements retrieved successfully
          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: >
        Specifies the sub-account on whose behalf the request is made. This
        should be set to the `account_id`, which can be retrieved via the [List
        Connected
        Accounts](/account-center/v1.6/api-reference/list-connected-accounts).
        If omitted or empty, the request is executed using the master account.

        More information at [Connected
        Accounts](/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: >-
        A unique identifier (UUID) used to maintain operation idempotency,
        ensuring that repeated executions of the same operation do not result in
        unintended effects or duplication. It helps preserve data consistency in
        the face of network errors, retries, or failures.
      example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde
    SETTLEMENT_PaymentIntentId:
      name: payment_intent_id
      in: query
      required: false
      description: The unique ID of a payment intent.
      schema:
        type: string
        example: PI1945730395043532800
    SettlementBatchId:
      name: settlement_batch_id
      in: query
      required: false
      description: Identifier of the settlement batch.
      schema:
        type: string
        example: SB1947180993781698560
    SettledStartTime:
      name: settled_start_time
      in: query
      required: false
      description: >
        Inclusive start date used to filter by settlement_date, in YYYY-MM-DD
        format. Time is based on UTC+8. 


        Example: '2025-07-01' means 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: >
        Inclusive end date used to filter by settlement_date, in YYYY-MM-DD
        format. Time is based on UTC+8. 


        Example: '2025-07-31' means settlement_date ≤ 2025-07-31T23:59:59
        (UTC+8).
      schema:
        type: string
        example: '2025-07-31'
    PageNumber:
      name: page_number
      description: >-
        The page number to retrieve the next set of items. The number has to be
        greater than 1.
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        example: 1
    PageSize:
      name: page_size
      description: >-
        The maximum number of items to return per page. This number can be
        between 1 - 100
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        example: 10
        maximum: 100
  schemas:
    TotalPages:
      type: integer
      example: 10
      description: The total pages of available items.
    TotalItems:
      type: integer
      example: 105
      description: The total counts of available items.
    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: Unique identifier of the settlement (UUID).
      example: ST1945730404245835776
    SETTLEMENT_AccountId:
      type: string
      description: UUID of the account associated with the settlement.
      example: a7b92a19-bfc3-4c8b-8a4f-cfcf74cab345
    SETTLEMENT_AccountName:
      type: string
      description: Name of the account.
      example: UQPAY PTE. LTD.
    SETTLEMENT_SourceType:
      type: string
      description: Source type of the transaction record.
      example: PAYMENT
    SETTLEMENT_TransactionType:
      type: string
      description: Type of transaction.
      example: PAYMENT
    SETTLEMENT_MerchantOrderId:
      $ref: '#/components/schemas/MerchantOrderId'
    SETTLEMENT_PaymentIntentId:
      $ref: '#/components/schemas/PaymentIntentId'
    SETTLEMENT_PaymentMethod:
      type: string
      description: |
        Payment method used for the transaction.
        - `card`: Card payment (Visa, Mastercard, UnionPay).
        - `alipaycn`: Alipay (mainland China).
        - `alipayhk`: AlipayHK (Hong Kong).
        - `unionpay`: UnionPay QR code payment.
        - `wechatpay`: WeChat Pay.
      example: card
      enum:
        - card
        - alipaycn
        - alipayhk
        - unionpay
        - wechatpay
    SETTLEMENT_TransactionCreateDate:
      $ref: '#/components/schemas/DateTime'
      description: Time when the transaction was created (ISO 8601 date-time, UTC).
    SETTLEMENT_TransactionAmount:
      $ref: '#/components/schemas/Amount'
      description: Transaction amount.
      example: '7.77'
    SETTLEMENT_TransactionCurrency:
      $ref: '#/components/schemas/Currency'
      example: SGD
    SETTLEMENT_TransactionDate:
      $ref: '#/components/schemas/DateTime'
      description: Time when the transaction(PaymentIntent or Refund) was completed.
      example: '2025-07-17T14:20:50+08:00'
    SETTLEMENT_SettlementAmount:
      $ref: '#/components/schemas/Amount'
      description: Settlement amount.
      example: '7.77'
    SETTLEMENT_SettlementCurrency:
      $ref: '#/components/schemas/Currency'
      example: SGD
    SETTLEMENT_NetSettlementAmount:
      $ref: '#/components/schemas/Amount'
      description: |
        Net settlement amount.
      example: '8.11'
    SETTLEMENT_ExchangeRate:
      type: string
      description: >-
        Exchange rate applied from `transaction_currency` to
        `settlement_currency`, if applicable.
      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: The status of the settlement. Only `SUCCEEDED` will be returned.
      example: SUCCEEDED
      enum:
        - SUCCEEDED
    SETTLEMENT_SettlementBatchId:
      type: string
      description: Identifier of the settlement batch.
      example: SB1947180993781698560
    SETTLEMENT_SettlementCreateDate:
      $ref: '#/components/schemas/DateTime'
      description: Time when the settlement record was created.
      example: '2025-07-17T14:20:52+08:00'
    SETTLEMENT_SettlementDate:
      $ref: '#/components/schemas/DateTime'
      description: Time when the settlement was completed.
      example: '2025-07-21T14:25:01+08:00'
    MerchantOrderId:
      type: string
      maxLength: 36
      description: >-
        The merchant reference id created in merchant's system that corresponds
        to this PaymentIntent
    PaymentIntentId:
      type: string
      description: The ID of the payment intent.
      example: PI1234567890123456789
    DateTime:
      type: string
      format: date/time
      example: '2024-03-01T00:00:00+08:00'
    Amount:
      type: string
    Currency:
      type: string
      description: Three-letter currency code
    FeeAmount:
      type: string
      description: The fee amount.
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: The API token for login provided by UQPay.

````