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

# Retrieve Balance

> Retrieve the details of the specific individual currency account balance



## OpenAPI

````yaml /global-acquiring/v1.6/payment.yaml get /v2/payment/balances/{currency}
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/balances/{currency}:
    get:
      tags:
        - Payment Balances
      summary: Retrieve Balance
      description: Retrieve the details of the specific individual currency account balance
      operationId: retrieve-balance
      parameters:
        - $ref: '#/components/parameters/XOnBehalfOf'
        - $ref: '#/components/parameters/XIdempotencyKey'
        - $ref: '#/components/parameters/BalanceCurrency'
      responses:
        '200':
          description: Balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
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
    BalanceCurrency:
      name: currency
      in: path
      required: true
      description: Currency code for the balance query
      schema:
        type: string
        example: SGD
  schemas:
    BalanceResponse:
      type: object
      required:
        - balance_id
        - currency
        - available_balance
        - payable_balance
        - pending_balance
        - reserved_balance
        - margin_balance
        - frozen_balance
      properties:
        balance_id:
          type: string
          description: Account balance ID
          example: 4a2dd9f0-bfe9-432b-be2e-4d5af5d0b448
        currency:
          type: string
          description: Currency of the account balance
          example: SGD
          format: iso-4217
        available_balance:
          type: string
          description: Current available balance
          example: '1000.00'
        payable_balance:
          type: string
          description: Payable account balance
          example: '950.00'
        pending_balance:
          type: string
          description: Pending balance
          example: '50.00'
        reserved_balance:
          type: string
          description: Reserved balance
          example: '0.00'
        margin_balance:
          type: string
          description: Margin balance
          example: '0.00'
        frozen_balance:
          type: string
          description: Frozen funds
          example: '0.00'
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: The API token for login provided by UQPay.

````