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

# Get Payment Balances

> Retrieve current pay-in and pay-out balances across every wallet your company holds, broken down by currency and country.

## Overview

`GET /payment/balance` returns the **current** pay-in and pay-out sub-balances for every wallet your company holds, with one entry per `(currency, country)` pair. Use this before initiating a payout to verify funds are available, or to render a balances widget in your dashboard.

## When to use it

* Pre-flight check before [`POST /payment/payout`](/api-reference/endpoint/post-payment-payout) to avoid `400 Insufficient balance`.
* Render a wallet/balance summary on a dashboard.
* Reconcile your local accounting balance against Cartevo.

## Prerequisites

* Authenticated as a company user.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

No query parameters or body.

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "balances": [
      {
        "currency": "XAF",
        "country": "CM",
        "payin_balance": 125000,
        "payout_balance": 50000
      },
      {
        "currency": "XOF",
        "country": "CI",
        "payin_balance": 0,
        "payout_balance": 30000
      },
      {
        "currency": "USD",
        "country": "US",
        "payin_balance": 0,
        "payout_balance": 4250.5
      }
    ],
    "updated_at": "2026-05-09T10:15:00.000Z"
  }
}
```

| Field                            | Type   | Description                                                                                                            |
| -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `data.balances[]`                | array  | One entry per wallet you own. Empty array if you have no wallets yet.                                                  |
| `data.balances[].currency`       | string | ISO 4217 (e.g. `XAF`, `XOF`, `USD`).                                                                                   |
| `data.balances[].country`        | string | ISO 3166-1 alpha-2 (e.g. `CM`, `CI`, `US`).                                                                            |
| `data.balances[].payin_balance`  | number | Pay-in sub-balance — funds collected from end users, not yet moved.                                                    |
| `data.balances[].payout_balance` | number | Pay-out sub-balance — funds available to disburse via `POST /payment/payout`.                                          |
| `data.updated_at`                | string | ISO 8601. The instant Cartevo computed this snapshot. Real-time within \~1 second of any wallet-affecting transaction. |

> **About the two sub-balances:** Each wallet maintains a separate pay-in and pay-out sub-balance. Use [`POST /wallets/{id}/transfer-internal`](/getting-started/glossary#wallet) (currently undocumented; reach out to support) to move funds between them when needed. The USD wallet is also the source-of-funds for card issuance and funding.

### Error responses

| Status | Trigger                          |
| ------ | -------------------------------- |
| `401`  | Missing or expired Bearer token. |

## Code examples

```bash cURL theme={null}
curl https://api.cartevo.co/api/v1/payment/balance \
  -H "Authorization: Bearer $TOKEN"
```

```js Node.js (axios) theme={null}
const { data } = await axios.get(
  "https://api.cartevo.co/api/v1/payment/balance",
  { headers: { Authorization: `Bearer ${token}` } }
);

const xafCM = data.data.balances.find(
  (b) => b.currency === "XAF" && b.country === "CM"
);
if (xafCM && xafCM.payout_balance < 50000) {
  throw new Error("Top up XAF/CM payout wallet before disbursing");
}
```

## Related

* [`POST /payment/payout`](/api-reference/endpoint/post-payment-payout) — uses the `payout_balance` shown here.
* [`POST /payment/collect`](/api-reference/endpoint/post-payment-collect) — credits the `payin_balance`.
* [Glossary → Wallet](/getting-started/glossary#wallet) — pay-in vs pay-out sub-balance explanation.


## OpenAPI

````yaml GET /payment/balance
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /payment/balance:
    get:
      summary: Get Payment Balance
      description: Get balance information including available and pending amounts
      responses:
        '200':
          description: Balance retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Balance retrieved successfully
                  data:
                    $ref: '#/components/schemas/AllBalancesResponse'
components:
  schemas:
    AllBalancesResponse:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/BalanceDto'
        updated_at:
          type: string
          format: date-time
          example: '2025-01-08T12:00:00.000Z'
    BalanceDto:
      type: object
      properties:
        currency:
          type: string
          example: XAF
        country:
          type: string
          example: CM
        payin_balance:
          type: number
          example: 50000
        payout_balance:
          type: number
          example: 30000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````