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

# Get Balance

> Fetch wallet balances for the authenticated product (collections, payouts, etc.). Filter by currency or fetch all.

Fetch wallet balances associated with the **product tied to your token** (e.g., *Collections*, *Payouts*). Optionally filter by a specific `currency` (e.g., `KES`). If omitted, **all balances** for the product are returned.

***

## Environments

| Environment | Base URL                 |
| ----------- | ------------------------ |
| Sandbox     | `https://dev.waftpay.io` |
| Production  | `https://waftpay.io`     |

***

## Endpoint

```http theme={null}
GET /tsq/api/v1/wallet-balances?currency={CURRENCY}
```

***

## Full URLs

| Environment | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| Sandbox     | `https://dev.waftpay.io/tsq/api/v1/wallet-balances?currency=KES` |
| Production  | `https://waftpay.io/tsq/api/v1/wallet-balances?currency=KES`     |

***

## Example request

<Tabs>
  <Tab title="Sandbox">
    ```bash theme={null}
    curl -X GET \
      'https://dev.waftpay.io/tsq/api/v1/wallet-balances?currency=KES' \
      -H 'Authorization: Bearer <access_token>'
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    curl -X GET \
      'https://waftpay.io/tsq/api/v1/wallet-balances?currency=KES' \
      -H 'Authorization: Bearer <access_token>'
    ```
  </Tab>
</Tabs>

***

## Authentication

This endpoint **requires** a Bearer token that is **scoped to the product** you are querying (e.g., a *Collections* token can only view Collections balances; a *Payouts* token can only view Payouts balances).

```http theme={null}
Authorization: Bearer <access_token>
```

If the token is invalid, expired, or not authorized for the requested product, you'll receive `401 Unauthorized`.

***

## Query parameters

| Name       | In    | Type   | Required | Description                                                                                                  |
| ---------- | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `currency` | query | string | No       | ISO currency code (e.g., `KES`, `UGX`). If omitted, returns all balances for the product tied to your token. |

***

## Successful responses

### 200 OK - All balances (no filter)

```json theme={null}
{
  "code": 200,
  "status": "SUCCESS",
  "description": "Request processed successfully",
  "results": [
    {
      "currency": "KES",
      "actual_balance": 10010110.0,
      "available_balance": 10010110.0,
      "alert_limit": 0.0,
      "status": "ACTIVE"
    }
  ]
}
```

### 200 OK - Specific currency present

```json theme={null}
{
  "code": 200,
  "status": "SUCCESS",
  "description": "Request processed successfully",
  "results": [
    {
      "currency": "UGX",
      "actual_balance": 12345.0,
      "available_balance": 12345.0,
      "alert_limit": 0.0,
      "status": "ACTIVE"
    }
  ]
}
```

<Note>
  <ul>
    <li><code>actual\_balance</code> is the total ledger balance.</li>
    <li><code>available\_balance</code> is the spendable amount after holds/reserves.</li>
    <li><code>alert\_limit</code> is your configured low-balance threshold, if any.</li>
    <li><code>status</code> reflects wallet state, for example <code>ACTIVE</code>, <code>INACTIVE</code>, or <code>SUSPENDED</code>.</li>
  </ul>
</Note>

***

## Error responses

### 404 Not Found - Currency not provisioned for this product

```json theme={null}
{
  "code": 404,
  "status": "FAILED",
  "description": "Balances not found",
  "results": {}
}
```

### 401 Unauthorized - Bad/expired token or wrong scope

```json theme={null}
{
  "code": 401,
  "status": "FAILED",
  "description": "Unauthorized",
  "results": {}
}
```

***

## Behavior & constraints

* **Product scoping:** The Bearer token determines which product’s wallets are visible (e.g., Collections vs Payouts).
* **Filtering:** `currency` is optional; when omitted, all provisioned wallets for the token’s product are returned.
* **Idempotency:** This is a `GET` and does not change state; no idempotency key required.
* **Caching:** Avoid caching balances client-side if you need real-time accuracy.
* **Rate limits:** Standard platform rate limits apply. Handle `429` with retries and backoff.
* **Currency codes:** Must be ISO 4217 uppercase; unrecognized codes return `404` or an empty list depending on provisioning.


## OpenAPI

````yaml GET /tsq/api/v1/wallet-balances
openapi: 3.1.0
info:
  title: Waftpay Payments API
  description: >-
    Process payments, collect funds, and remit payouts with Waftpay. Includes
    Authentication Token, idempotency, webhooks, and sandbox support.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://dev.waftpay.io
    description: Sandbox (dev)
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Obtain and manage access tokens
  - name: Payments
    description: Charge a customer and track status
  - name: Collections
    description: Customer-initiated payments and hosted checkouts
  - name: Checkout
    description: >-
      Hosted checkout flow for customer payments.


      Flow:

      1. Ensure the Collections service is enabled for your account.

      2. Use `consumer_key` and `consumer_secret` to generate a Bearer token via
      **Get Authentication Token**.

      3. Cache the token and refresh only on expiry.

      4. Call **Create Checkout Request** with customer details, amount, and
      redirect URLs.

      5. Use the returned `checkout_url` for redirect or iframe.

      6. The `callback_url` receives a payload matching the `CheckoutCallback`
      schema.
  - name: Remittance
    description: Send payouts to mobile wallets and bank accounts
  - name: Webhooks
    description: Receive asynchronous notifications
  - name: Utilities
    description: Common utilities (idempotency, health)
paths:
  /tsq/api/v1/wallet-balances:
    get:
      tags:
        - Balances
      summary: Get wallet balances
      description: >-
        Fetch wallet balances for the authenticated product (collections,
        payouts, etc.). Optionally filter by currency (ISO code). If omitted,
        all balances for the product are returned.
      operationId: getWalletBalances
      parameters:
        - in: query
          name: currency
          required: false
          schema:
            type: string
            example: KES
          description: ISO currency code to filter the balance (e.g., KES, UGX, USD).
      responses:
        '200':
          description: Balances fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
              examples:
                success:
                  value:
                    code: 200
                    status: SUCCESS
                    description: Request processed successfully
                    results:
                      - {}
        '401':
          description: Unauthorized (invalid/expired token or wrong product scope)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Balances not found for provided currency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  value:
                    code: 404
                    status: FAILED
                    description: Balances not found
                    results: {}
      security:
        - bearerAuth: []
components:
  schemas:
    BalanceListResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        status:
          type: string
          example: SUCCESS
        description:
          type: string
          example: Request processed successfully
        results:
          type: array
          items:
            $ref: '#/components/schemas/WalletBalance'
      required:
        - code
        - status
        - description
        - results
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 404
        status:
          type: string
          example: FAILED
        description:
          type: string
          example: Balances not found
        results:
          description: Error payload or empty object.
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
          example: {}
      required:
        - code
        - status
        - description
        - results
    WalletBalance:
      type: object
      properties:
        currency:
          type: string
          description: ISO currency code.
          example: KES
        actual_balance:
          type: number
          format: double
          description: Total ledger balance.
          example: 1010100
        available_balance:
          type: number
          format: double
          description: Spendable amount after holds/reserves.
          example: 910100
        alert_limit:
          type: number
          format: double
          description: Configured low-balance alert threshold.
          example: 0
        status:
          type: string
          description: Wallet status.
          example: ACTIVE
          enum:
            - ACTIVE
            - INACTIVE
            - SUSPENDED
      required:
        - currency
        - actual_balance
        - available_balance
        - alert_limit
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````