Get API Wallet Balance | 9jaBillz Developer Documentation

Endpoint Details

HTTP Method

GET

Route Path

/api/v2/wallet-balance

Base URL

https://app.9jabillz.com.ng

Authentication

HMAC SHA256

Alternative Alias Route

You can also call /api/reseller/balance interchangeably. Both routes accept identical signature payloads and security headers.

Required Request Headers

Pass all 6 security headers with every request. Requests with missing headers or signature drift $> 300\text{s}$ will fail with a 401 Unauthorized status.

Header Name	Type	Description
`Content-Type`	String	Must be set to `application/json`
`Accept`	String	Must be set to `application/json`
`X-API-KEY`	String	Your public API key (`9ja_live_pk_...`)
`X-API-SIGNATURE`	String	Lowercase hex-encoded HMAC SHA256 cryptographic signature.
`X-API-TIMESTAMP`	String	Current Unix timestamp in seconds (`time()`). Max skew: 300s.
`X-API-NONCE`	String	Unique random alphanumeric string per request.

HMAC SHA256 Signature Formula (GET Request)

Because GET requests contain no request body payload, set REQUEST_BODY to an empty string "":

Signature Payload String

Payload = TIMESTAMP + NONCE + HTTP_METHOD + REQUEST_PATH + REQUEST_BODY
Example = "1792008086" + "a1b2c3d4e5" + "GET" + "/api/v2/wallet-balance" + ""
Signature = LOWERCASE_HEX( HMAC_SHA256(Payload, YOUR_SECRET_KEY) )

Integration Code Examples

Select your programming language below to view production-ready implementation snippets:

<?php
$apiKey    = "YOUR_LIVE_API_KEY";
$secretKey = "YOUR_LIVE_SECRET_KEY";

$path      = "/api/v2/wallet-balance";
$url       = "https://app.9jabillz.com.ng" . $path;
$method    = "GET";
$timestamp = (string) time();
$nonce     = bin2hex(random_bytes(8));$body      = ""; // Empty body for GET

// Construct Pre-hash Payload String
$payload   =$timestamp . $nonce .$method . $path .$body;
$signature = hash_hmac('sha256', $payload,$secretKey);

$headers = [
    "Content-Type: application/json",
    "Accept: application/json",
    "X-API-KEY: " . $apiKey,
    "X-API-SIGNATURE: " . $signature,
    "X-API-TIMESTAMP: " . $timestamp,
    "X-API-NONCE: " . $nonce
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,$headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

const axios = require('axios');
const crypto = require('crypto');

const apiKey    = 'YOUR_LIVE_API_KEY';
const secretKey = 'YOUR_LIVE_SECRET_KEY';

const path      = '/api/v2/wallet-balance';
const url       = `https://app.9jabillz.com.ng${path}`;
const method    = 'GET';
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce     = crypto.randomBytes(8).toString('hex');
const body      = '';

const payload   = timestamp + nonce + method + path + body;
const signature = crypto.createHmac('sha256', secretKey)
                        .update(payload)
                        .digest('hex');

axios.get(url, {
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'X-API-KEY': apiKey,
        'X-API-SIGNATURE': signature,
        'X-API-TIMESTAMP': timestamp,
        'X-API-NONCE': nonce
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error.response ? error.response.data : error.message));

import time
import secrets
import hmac
import hashlib
import requests

api_key    = "YOUR_LIVE_API_KEY"
secret_key = "YOUR_LIVE_SECRET_KEY"

path      = "/api/v2/wallet-balance"
url       = f"https://app.9jabillz.com.ng{path}"
method    = "GET"
timestamp = str(int(time.time()))
nonce     = secrets.token_hex(8)
body      = ""

payload   = f"{timestamp}{nonce}{method}{path}{body}"
signature = hmac.new(secret_key.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": api_key,
    "X-API-SIGNATURE": signature,
    "X-API-TIMESTAMP": timestamp,
    "X-API-NONCE": nonce
}

response = requests.get(url, headers=headers)
print(response.json())

// Postman Pre-request Script Tab:
const secretKey = "YOUR_LIVE_SECRET_KEY";

const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = Math.random().toString(36).substring(2, 15);
const method = "GET";
const path = "/api/v2/wallet-balance";
const body = "";

const payload = timestamp + nonce + method + path + body;
const signature = CryptoJS.HmacSHA256(payload, secretKey).toString(CryptoJS.enc.Hex);

pm.variables.set("X-API-TIMESTAMP", timestamp);
pm.variables.set("X-API-NONCE", nonce);
pm.variables.set("X-API-SIGNATURE", signature);

Response Schema

Success Response (200 OK)

JSON Response Payload

{
    "status": true,
    "message": "Wallet balance retrieved successfully.",
    "data": {
        "reseller_id": 1001,
        "balance": 19247.40,
        "currency": "NGN",
        "user_type": "Reseller",
        "api_mode": "live"
    }
}

Field Definitions

Property	Type	Description
`status`	Boolean	`true` when request execution succeeds.
`message`	String	Human-readable outcome summary.
`data.reseller_id`	Integer	Unique identifier assigned to the merchant reseller account.
`data.balance`	Float	Current available funds in Nigerian Naira (NGN).
`data.currency`	String	ISO-4217 Currency Code (`NGN`).
`data.user_type`	String	Account privilege tier (`Reseller`).
`data.api_mode`	String	Current API environment mode (`live` or `test`).

Error Handling

HTTP Code	Reason	Example Response Payload
`401 Unauthorized`	Invalid API Key or HMAC Signature	`{"status": false, "message": "Invalid HMAC cryptographic signature or API key."}`
`400 Bad Request`	Expired Timestamp (> 300s skew)	`{"status": false, "message": "Request timestamp skew exceeds limit."}`
`403 Forbidden`	API Access Disabled	`{"status": false, "message": "Reseller API access disabled on this account."}`

GET Get API Wallet Balance