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

# List all refunds

> Retrieve a list of refunds with optional filtering



## OpenAPI

````yaml /global-acquiring/v1.6/payment.yaml get /v2/payment/refunds
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/refunds:
    get:
      tags:
        - Payment Refunds
      summary: List all refunds
      description: Retrieve a list of refunds with optional filtering
      operationId: list-refunds
      parameters:
        - $ref: '#/components/parameters/XClientID'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - name: payment_intent_id
          in: query
          description: The ID of the payment intent to get refunds for
          required: false
          schema:
            type: string
        - name: merchant_order_id
          in: query
          description: >-
            The merchant reference id created in merchant's system that
            corresponds to this PaymentIntent.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of refunds retrieved successfully
          content:
            application/json:
              schema:
                title: PaymentRefundListResponse
                properties:
                  total_pages:
                    $ref: '#/components/schemas/TotalPages'
                  total_items:
                    $ref: '#/components/schemas/TotalItems'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentRefundResponse'
components:
  parameters:
    XClientID:
      in: header
      name: x-client-id
      schema:
        type: string
      required: true
      description: The API client id generated by UQPAY
      example: Up1HIsjiETgON9PMGPXLy7
    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
    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
    StartTime:
      name: start_time
      description: Start time of Transaction. Default time range is 1 months.
      in: query
      required: false
      schema:
        type: string
        example: '2024-03-01T00:00:00+08:00'
    EndTime:
      name: end_time
      description: End time of Transaction. Maximum time range of 3 months.
      in: query
      required: false
      schema:
        type: string
        example: '2024-03-01T00:00:00+08:00'
  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.
    PaymentRefundResponse:
      type: object
      properties:
        payment_refund_id:
          type: string
          description: The unique identifier for the refund
          example: RF123456789
        payment_attempt_id:
          type: string
          description: The ID of the payment attempt that was refunded
          example: PA123456789
        amount:
          type: string
          description: The amount refunded
          example: '10.01'
        currency:
          type: string
          description: The three-letter currency code (ISO 4217)
          example: USD
          format: iso-4217
        refund_status:
          type: string
          description: >
            The current status of the refund.


            - `INITIATED`: The refund has been initiated.

            - `PROCESSING`: The refund is being processed.

            - `SUCCEEDED`: The refund was successfully completed.

            - `FAILED`: The refund attempt failed.

            - `REVERSAL_INITIATED`: The reversal of the refund has been
            initiated.

            - `REVERSAL_PROCESSING`: The reversal of the refund is currently
            being processed.

            - `REVERSAL_SUCCEEDED`: The reversal of the refund was successfully
            completed.
          example: SUCCEEDED
          enum:
            - INITIATED
            - PROCESSING
            - SUCCEEDED
            - FAILED
            - REVERSAL_INITIATED
            - REVERSAL_PROCESSING
            - REVERSAL_SUCCEEDED
        create_time:
          $ref: '#/components/schemas/DateTime'
          description: The time at which this payment refund was created.
        update_time:
          $ref: '#/components/schemas/DateTime'
          description: Last time at which this payment refund was updated or operated on.
        reason:
          type: string
          description: The reason for the refund
          example: Order 1234 has been returned
          maxLength: 100
        metadata:
          type: object
          description: >-
            Additional metadata associated with the refund. User-defined
            key-value pairs.
          additionalProperties:
            type: string
          example:
            customer_id: cust_12345
            order_id: order_6789
          maximum: 3200
    DateTime:
      type: string
      format: date/time
      example: '2024-03-01T00:00:00+08:00'
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: The API token for login provided by UQPay.

````