Skip to main content

Get Balance API

Retrieves the current balance for all supported currencies in your account.

  • URL: /v1/payment/balance

  • Method: GET

  • Auth Required: Yes

  • Success Response:

    {
      "status": 200,
      "message": "Balance fetched successfully",
      "data": [
          {
              "id": 1,
              "asset_code": "UGX",
              "asset_issuer": "issuer_ugx",
              "currency": "UGX",
              "balance": "4621.0000000"
          },
          {
              "id": 2,
              "asset_code": "KES",
              "asset_issuer": "issuer_kes",
              "currency": "KES",
              "balance": "0"
          },
          {
              "id": 3,
              "asset_code": "TZS",
              "asset_issuer": "issuer_tzs",
              "currency": "TZS",
              "balance": "0"
          },
          {
              "id": 4,
              "asset_code": "cUGX",
              "asset_issuer": "issuer_ugx",
              "currency": "UGX",
              "balance": "650.0000000"
          },
          {
              "id": 5,
              "asset_code": "cKES",
              "asset_issuer": "issuer_kes",
              "currency": "KES",
              "balance": "0"
          },
          {
              "id": 6,
              "asset_code": "cTZS",
              "asset_issuer": "issuer_tzs",
              "currency": "TZS",
              "balance": "0"
          }
      ]
    }

  • Error Response:

    {
      "status": 400,
      "message": "Failed to fetch balances",
      "data": null
    }

Response Fields​

  • id: Unique identifier for the balance record
  • asset_code: The code representing the currency or asset (e.g., UGX, KES, TZS)
  • asset_issuer: The issuer of the asset
  • currency: The currency code
  • balance: The current balance amount with precision up to 7 decimal places

Supported Currencies​

The API supports the following currencies:

  • UGX (Uganda Shillings)
  • KES (Kenyan Shillings)
  • TZS (Tanzanian Shillings)

Each currency also has a corresponding collateral version prefixed with 'c' (e.g., cUGX, cKES, cTZS).

Client Errors​

  • 400 Bad Request: The server could not understand the request due to invalid syntax.
  • 401 Unauthorized: Authentication is required or has failed.
  • 403 Forbidden: The client does not have access rights to the content.
  • 404 Not Found: The server could not find the requested resource.
  • 429 Too Many Requests: The client has sent too many requests in a given amount of time (rate limiting).

Example error response:

{
  "status": 404,
  "message": "Resource not found",
  "data": null
}

Server Errors​

  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
  • 502 Bad Gateway: The server received an invalid response from the upstream server.
  • 503 Service Unavailable: The server is not ready to handle the request, often due to maintenance or overload.
  • 504 Gateway Timeout: The server did not receive a timely response from the upstream server.

Example server error response:

{
  "status": 500,
  "message": "An unexpected error occurred",
  "data": null
}