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* — Must be application/json

• Authorization* — Bearer token (Bearer YOUR_API_TOKEN)

• x-request-id* — Unique UUID per request for tracing

Body Parameters

• account_number* (string) — The account number of the merchant collection account

Responses

200 OK

Response Format

{
  "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

400 BAD REQUEST

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

{
  "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.

401 UNAUTHORIZED

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

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

Resolution

Ensure your request includes the correct authorization header: Authorization: Bearer YOUR_API_TOKEN

404 NOT FOUND

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

500 INTERNAL SERVER ERROR

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

{
  "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.