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

# Get account balance

> Retrieve the balance for a specific account using accountNo. Requests without accountNo are invalid and return 400 (including requests with no query parameters or only the legacy account parameter). If both accountNo and legacy account are provided, accountNo takes precedence.



## OpenAPI

````yaml api-reference/openapi.json get /v1/balance
openapi: 3.1.0
info:
  title: Fingo Pay API
  description: >-
    Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C
    disbursements, B2B transfers, bank transfers, account balances, and
    transactions.
  version: 1.0.0
servers:
  - url: https://api.fingopay.io
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Receive payments from customers
  - name: Payouts
    description: Send payments to recipients
  - name: Accounts
    description: Account balances and management
  - name: Transactions
    description: Transaction history and lookup
  - name: Verification
    description: Pre-transaction verification and lookup
  - name: Webhooks
    description: Webhook event notifications
paths:
  /v1/balance:
    get:
      tags:
        - Accounts
      summary: Get account balance
      description: >-
        Retrieve the balance for a specific account using accountNo. Requests
        without accountNo are invalid and return 400 (including requests with no
        query parameters or only the legacy account parameter). If both
        accountNo and legacy account are provided, accountNo takes precedence.
      operationId: getBalance
      parameters:
        - name: accountNo
          in: query
          required: true
          description: >-
            Specific account number to get balance for. This is the supported
            selector for balance lookup.
          schema:
            type: string
      responses:
        '200':
          description: Balance fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '400':
          description: >-
            Invalid request. accountNo is required. Requests with no query
            parameters or only legacy account are rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    BalanceResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Balance fetched
        data:
          type: object
          properties:
            account:
              type: string
              example: collections
              description: Account type
            accountNo:
              type:
                - string
                - 'null'
              example: ACC-123456
              description: Account number if applicable
            balance:
              type: integer
              example: 9876543
              description: Current available balance in smallest currency unit
            currency:
              type: string
              example: KES
            available:
              type: integer
              example: 9876543
              description: Available balance
            pending:
              type: integer
              example: 0
              description: Pending balance
            updatedAt:
              type: string
              format: date-time
              example: '2025-08-15T12:05:00Z'
          required:
            - account
            - balance
            - currency
            - available
            - pending
            - updatedAt
      required:
        - status
        - message
        - data
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - rate_limit_error
                - api_error
                - idempotency_error
                - not_found_error
                - conflict_error
              description: Error category
            code:
              type: string
              enum:
                - missing_parameter
                - invalid_parameter
                - unauthorized
                - forbidden
                - too_many_requests
                - internal_error
                - duplicate
                - resource_not_found
                - missing_header
                - validation_error
              description: Specific error code
            message:
              type: string
              description: Human-readable error message
            param:
              type:
                - string
                - 'null'
              description: The parameter that caused the error, if applicable
            requestId:
              type: string
              description: Request ID for support reference
          required:
            - type
            - code
            - message
      required:
        - error
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your API key as a Bearer token. Example: Authorization: Bearer
        sk_live_...

````