INSTANT DELIVERY Fast Bills & Electricity Payment — Guaranteed 24/7 Service
API Documentation Sandbox Environment
Documentation Electricity Services

POST Electricity Token Purchase

Execute live bill payments and generate meter top-up tokens across all supported Nigerian Electricity Distribution Companies (DisCos) with instant token retrieval and automatic wallet deductions[cite: 1, 2, 3].

Endpoint Details

HTTP Method
POST
Route Path
/api/v2/electricity
Base URL
https://app.9jabillz.com.ng
Authentication
HMAC SHA256

Supported DisCo Providers (provider)

DisCo Code Service Provider Name
ikedcIkeja Electric
ekedcEko Electricity
aedcAbuja Electricity
ibedcIbadan Electricity
phedPort Harcourt Electricity
kedcoKano Electricity
eedcEnugu Electricity
jedJos Electricity
kaedcoKaduna Electric
bedcBenin Electricity
yedcYola Electricity

Request Body Parameters

Send request parameters formatted as a raw JSON payload:

Field Type Required Description
provider String Yes Target DisCo code (e.g., ikedc, ekedc, aedc). Alias: service_id.
meter_number String Yes Customer's electricity meter or account number. Alias: billersCode.
amount Number Yes Amount in NGN to fund (Minimum: 500.00).
request_ref String Yes Your system's unique transaction reference for idempotency checking. Alias: reference.
meter_type String Optional Meter classification: prepaid or postpaid (Defaults to prepaid). Alias: type.
phone_number String Optional Recipient mobile number to send token SMS notification. Alias: phone.

Sample Request JSON Payload

Request Body
{
  "provider": "ikedc",
  "meter_number": "1111111111111",
  "meter_type": "prepaid",
  "amount": 1000,
  "request_ref": "PWR_TEST_9JA_001",
  "phone_number": "08012345678"
}

Required Request Headers

Requests require valid HMAC SHA256 security headers generated using your reseller public API key and secret key:

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

HMAC SHA256 Signature Formula (POST Request)

Signature Payload Formula
CanonicalData = METHOD + "\n" + REQUEST_PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(RawJsonBody)
Example       = "POST\n/api/v2/electricity\n1792008086\na1b2c3d4e5\n" + SHA256(RawJsonBody)
Signature     = LOWERCASE_HEX( HMAC_SHA256(CanonicalData, 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/electricity";
$url       = "https://app.9jabillz.com.ng" . $path;
$method    = "POST";
$timestamp = (string) time();$nonce     = bin2hex(random_bytes(8));

$payloadArray = [
    "provider"     => "ikedc",
    "meter_number" => "1111111111111",
    "meter_type"   => "prepaid",
    "amount"       => 1000,
    "request_ref"  => "PWR_" . uniqid(),
    "phone_number" => "08012345678"
];

$rawBody   = json_encode($payloadArray);
$bodyHash  = hash('sha256',$rawBody);

// Construct Canonical String Joined by Newline
$canonicalData = implode("\n", [
    strtoupper($method),
    $path,$timestamp,
    $nonce,$bodyHash
]);

$signature = hash_hmac('sha256', $canonicalData,$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_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS,$rawBody);
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/electricity';
const url       = `https://app.9jabillz.com.ng${path}`;
const method    = 'POST';
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce     = crypto.randomBytes(8).toString('hex');

const requestBody = JSON.stringify({
    provider: "ikedc",
    meter_number: "1111111111111",
    meter_type: "prepaid",
    amount: 1000,
    request_ref: "PWR_" + Date.now(),
    phone_number: "08012345678"
});

const bodyHash = crypto.createHash('sha256').update(requestBody).digest('hex');

const canonicalData = [
    method.toUpperCase(),
    path,
    timestamp,
    nonce,
    bodyHash
].join('\n');

const signature = crypto.createHmac('sha256', secretKey)
                        .update(canonicalData)
                        .digest('hex');

axios.post(url, requestBody, {
    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 json
import requests

api_key    = "YOUR_LIVE_API_KEY"
secret_key = "YOUR_LIVE_SECRET_KEY"

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

payload_data = {
    "provider": "ikedc",
    "meter_number": "1111111111111",
    "meter_type": "prepaid",
    "amount": 1000,
    "request_ref": f"PWR_{int(time.time())}",
    "phone_number": "08012345678"
}

raw_body  = json.dumps(payload_data, separators=(',', ':'))
body_hash = hashlib.sha256(raw_body.encode('utf-8')).hexdigest()

canonical_data = f"{method.upper()}\n{path}\n{timestamp}\n{nonce}\n{body_hash}"
signature = hmac.new(secret_key.encode('utf-8'), canonical_data.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.post(url, data=raw_body, headers=headers)
print(response.json())
// Postman Pre-request Script Tab:
const secretKey = "YOUR_SECRET_KEY";

const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce     = Math.random().toString(36).substring(2, 15);
const method    = pm.request.method.toUpperCase();
const path      = pm.request.url.getPath();
const body      = pm.request.body && pm.request.body.raw ? pm.request.body.raw : "";

const bodyHash  = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);

const canonicalData = [method, path, timestamp, nonce, bodyHash].join("\n");
const signature = CryptoJS.HmacSHA256(canonicalData, 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

HTTP 200 OK (Success Response)

JSON Response Payload
{
    "status": true,
    "message": "Electricity units purchased successfully.",
    "data": {
        "status": "successful",
        "request_ref": "PWR_TEST_9JA_001",
        "reference": "API-ELE-9JABILLZ-904812",
        "amount": 1000.00,
        "cashback_earned": 0.00,
        "meter_number": "1111111111111",
        "meter_type": "PREPAID",
        "token": "4820-1938-2049-5821-3920",
        "units": "14.2 kWh",
        "provider": "IKEDC"
    }
}

Response Field Definitions

Field Type Description
status Boolean Indicates overall operation status (true on success).
message String Human-readable response summary.
data.status String Final transaction status (successful or pending).
data.request_ref String Reseller-provided unique request reference echoed back.
data.reference String System-generated transaction reference (API-ELE-...).
data.amount Number Total amount charged from reseller wallet in NGN.
data.cashback_earned Number Reseller commission/cashback earned on transaction in NGN.
data.meter_number String Recipient electricity meter or account number credited.
data.meter_type String Uppercase meter tariff type (PREPAID or POSTPAID).
data.token String Generated electricity recharge token digits (empty string for postpaid meters).
data.units String Quantity of electrical units allocated in kWh (if provided by DisCo).
data.provider String Uppercase target DisCo code (IKEDC, EKEDC, etc.).

Error Handling

HTTP Code Error Response Message Description
400 Bad Request Required fields missing: provider, meter_number, amount, request_ref. One or more required body parameters are missing.
400 Bad Request Minimum electricity purchase amount is NGN 500.00. Entered purchase amount is below the allowed limit.
400 Bad Request Insufficient API wallet balance. Reseller wallet balance is lower than the transaction amount.
401 Unauthorized Authentication required. Invalid or missing API key or HMAC signature. Header verification failed, timestamp expired, or signature mismatch.
405 Method Not Allowed Method Not Allowed Sent request verb other than POST.
409 Conflict Duplicate request_ref detected. The request_ref has already been processed previously.
502 Bad Gateway Electricity token dispatch failed. DisCo or upstream gateway error; wallet automatically refunded.
500 Internal Error Server error processing API Electricity request. Internal server or database exception.