> For the complete documentation index, see [llms.txt](https://tembo.gitbook.io/tembo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tembo.gitbook.io/tembo/merchant-accounts-api/api-reference/get-account-balance.md).

# Get Account Balance

Retrieves the current balance of a specific merchant collection account. Returns both available and booked balances, along with basic account details for monitoring your incoming collections.

### Endpoint

```
GET /account/{account_number}/balance
```

### Request

#### **Headers**

* **`Content-Type`**<mark style="color:red;">\*</mark> — Must be `application/json`
* **`Authorization`**<mark style="color:red;">\*</mark> — Bearer token (`Bearer YOUR_API_TOKEN`)
* **`x-request-id`**<mark style="color:red;">\*</mark> — Unique UUID per request for tracing

#### **Body Parameters**

* **`account_number`**<mark style="color:red;">\*</mark> *(string)* — The account number of the merchant collection account

### Responses

<details>

<summary><code>200</code> OK</summary>

#### Response Format

```json
{
  "success": true,
  "statusCode": "SUCCESS",
  "timestamp": "2025-09-11T10:20:09+03:00",
  "result": {
    "accountNo": "XXXXXXXX",
    "accountName": "TEMBOPLUS COMPANY LIMITED",
    "branchCode": "R79",
    "currency": "TZS",
    "status": "ACTIVE",
    "availableBalance": 5000,
    "currentBalance": 5000
  }
}
```

#### Response Fields

* **`accountNo`** *(string)* — The account number queried
* **`accountName`** *(string)* — The name registered to the account
* **`branchCode`** *(string)* — Bank branch code where the account is domiciled
* **`currency`** *(string)* — The currency in which the account is maintained (e.g., `TZS`)
* **`status`** *(string)* — Current status of the account (e.g., `ACTIVE`)
* **`availableBalance`** *(string)* — Funds currently available for withdrawal
* **`bookedBalance`** *(string)* — Total balance including pending transactions

</details>

<details>

<summary><code>400</code> BAD REQUEST</summary>

This error occurs when the request contains missing or invalid parameters. The API validates all required fields and data formats before processing your request.

#### Common Causes

* `accountNo` field is empty, missing, or invalid
* Invalid JSON syntax in the request body
* Missing `Content-Type: application/json` header

#### Error Format

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Validation Error",
  "details": {
    "accountNo": "\"accountNo\" is required"
  }
}
```

#### Resolution

Verify all required fields (`accountNo`) are included and properly formatted before sending the request.

</details>

<details>

<summary><code>401</code> UNAUTHORIZED</summary>

This error indicates authentication failure. The API could not verify your identity using the provided credentials.

#### **Common Causes:**

* Missing `Authorization` header in the request
* Invalid bearer token format (should be `Bearer YOUR_TOKEN`)
* Expired or revoked API token
* Incorrect API token value

#### **Error Format**

```json
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}
```

#### **Resolution**

Ensure your request includes the correct authorization header:\
`Authorization: Bearer YOUR_API_TOKEN`&#x20;

</details>

<details>

<summary><code>404</code> NOT FOUND</summary>

This error indicates that the specified account number does not exist or is not accessible with your current credentials.

#### Why This Happens

* Account number does not exist in your allocated pool
* Typo in the account number
* Account was never successfully allocated

#### Error Format

HTTP `404 Not Found` status with no response body.

#### Resolution

* Verify the account number is correct and properly formatted
* Confirm the account was successfully allocated using the **allocate** endpoint

</details>

<details>

<summary><code>500</code> INTERNAL SERVER ERROR</summary>

This error indicates a temporary server-side issue that prevented the request from being processed. These are typically transient problems that resolve automatically.

#### **Common causes:**

* Temporary banking system connectivity issues
* Server maintenance or updates in progress
* Third-party service temporary unavailability

#### **Error format**

```json
{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Something went wrong"
}
```

#### **Resolution:**

* Wait 1-2 minutes and retry the request
* Contact support with your `x-request-id` if the issue persists beyond 10 minutes

**Note:** These errors are usually temporary and resolve within a few minutes.

</details>