Endpoint Details
HTTP Method
POST
Route Path
/api/v2/cable-tv/validate
Base URL
https://app.9jabillz.com.ng
Authentication
HMAC SHA256
Request Body Parameters
Send request parameters formatted as a raw JSON payload:
| Field | Type | Required | Description |
|---|---|---|---|
provider |
String | Yes | Target cable provider code (dstv, gotv, startimes, showmax). Alias: service_id. |
smartcard_number |
String | Yes | Customer's Smartcard or IUC number. Alias: iuc_number. |
Sample Request JSON Payload
Request Body
{
"provider": "gotv",
"smartcard_number": "7024163821"
}
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/cable-tv/validate\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/cable-tv/validate";
$url = "https://app.9jabillz.com.ng" . $path;
$method = "POST";
$timestamp = (string) time();$nonce = bin2hex(random_bytes(8));
$payloadArray = [
"provider" => "gotv",
"smartcard_number" => "7024163821"
];
$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/cable-tv/validate';
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: "gotv",
smartcard_number: "7024163821"
});
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/cable-tv/validate"
url = f"https://app.9jabillz.com.ng{path}"
method = "POST"
timestamp = str(int(time.time()))
nonce = secrets.token_hex(8)
payload_data = {
"provider": "gotv",
"smartcard_number": "7024163821"
}
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": "Smartcard validated successfully.",
"data": {
"status": "success",
"service_id": "gotv",
"smartcard_number": "7024163821",
"customer_name": "JOHN DOE",
"customer_number": "20394821",
"current_bouquet": "GOtv Jolli",
"renewal_amount": 4850
}
}
Response Field Definitions
| Field | Type | Description |
|---|---|---|
status |
Boolean | Indicates operation status (true on success). |
message |
String | Human-readable response summary. |
data.status |
String | Provider validation status (success). |
data.service_id |
String | Normalized provider code (dstv, gotv, startimes). |
data.smartcard_number |
String | Validated Smartcard or IUC number. |
data.customer_name |
String | Full registered name on the decoder account. |
data.customer_number |
String | Provider-assigned customer account number. |
data.current_bouquet |
String | Current or last active subscription package name. |
data.renewal_amount |
Number | Renewal cost for the current active package in NGN. |
Error Handling
| HTTP Code | Error Response Message | Description |
|---|---|---|
400 Bad Request |
Required fields missing: service_id, smartcard_number. | Missing required fields in JSON request body. |
400 Bad Request |
Invalid Smartcard or IUC number. | Smartcard number not found on provider system. |
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. |
500 Internal Error |
Failed to validate smartcard number. | Server or provider gateway communication exception. |