API Sections
Overview & Architecture
The Bills & Utilities REST API allows third-party developers, fintech platforms, and agencies to automate Airtime recharge, Direct & SME Internet Data bundles, Cable TV subscription renewals (DSTV, GOTV, Startimes, Showmax), and Prepaid/Postpaid Electricity token generation across all 11 licensed Nigerian electricity distribution companies (Discos).
https://irust.ng/api/v1/bills
Authentication & Standard Headers
Pass your developer API key in the Authorization header using the Bearer scheme.
| Header | Value | Requirement | Description |
|---|---|---|---|
| Authorization | Bearer YOUR_API_TOKEN | Required | Your personal secret API token generated from Profile Settings. |
| Accept | application/json | Required | Expects JSON responses from the server. |
| Content-Type | application/json | Required | Format for all POST request bodies. |
/api/v1/bills/airtime/purchase
Top up airtime directly to any Nigerian mobile phone number across MTN, Airtel, Glo, and 9mobile.
Request Body (JSON)
| Field | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
| network | string | Yes | mtn, airtel, glo, etisalat |
Operator slug (use etisalat for 9mobile). |
| mobileno | string | Yes | 11 digits (e.g. 08012345678) |
Recipient mobile phone number. |
| amount | number | Yes | Min: 50, Max: 50000 |
Recharge face value in Naira (₦). |
{
"network": "mtn",
"mobileno": "08031234567",
"amount": 1000
}{
"status": "success",
"message": "Airtime delivery successful",
"data": {
"reference": "AIR_20261001123456_A1B2C3",
"network": "MTN",
"phone": "08031234567",
"amount": 1000,
"balance_after": 24000.00,
"created_at": "2026-10-01T12:34:56.000000Z"
}
}/api/v1/bills/data/purchase
Purchase standard data bundles (Daily, Weekly, Monthly) directly from telecom operators.
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| network | string | Yes | Network service ID (e.g. mtn-data, airtel-data, glo-data, etisalat-data). |
| bundle | string | Yes | Bundle plan variation code from the list endpoint. |
| mobileno | string | Yes | Recipient 11-digit phone number. |
Retrieve all available data plan codes and pricing.
/api/v1/bills/sme-data/purchase
Purchase heavily discounted SME and Corporate Gifting bundles with instant activation.
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| plan_id | string | Yes | SME Plan ID (e.g. 215 for MTN 1.0GB SME, 283 for Airtel 10.0GB). |
| mobileno | string | Yes | Recipient 11-digit phone number. |
Query real-time SME packages, size, validity, and wholesale price.
/api/v1/bills/cable/purchase
Renew or upgrade bouquets for DSTV, GOTV, Startimes, and Showmax.
Pre-validate the smartcard / IUC number before initiating payment.
Purchase Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| service_id | string | Yes | dstv, gotv, startimes, showmax |
| billersCode | string | Yes | Smartcard or IUC number. |
| subscription_type | string | Yes | renew or change |
| amount | number | Yes | Subscription amount in Naira. |
| phone | string | Yes | Customer phone number for notification. |
| variation_code | string | Optional | Required if subscription_type is change. |
/api/v1/bills/electricity/purchase
Purchase prepaid tokens or pay postpaid bills across all 11 Nigerian Electricity Distribution Companies (IKEDC, EKEDC, AEDC, KEDCO, PHED, JEDplc, KAEDCO, EEDC, BEDC, IBEDC, YEDC).
Verify meter number, registered name, and service address before charging.
Purchase Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| service_id | string | Yes | Disco slug (e.g. ikeja-electric, abuja-electric, kano-electric). |
| meter_number | string | Yes | Prepaid or Postpaid meter account number. |
| meter_type | string | Yes | prepaid or postpaid |
| amount | number | Yes | Minimum ₦500. |
| phone | string | Yes | Recipient mobile number (token SMS will be delivered here). |
{
"status": "success",
"message": "Electricity payment completed",
"data": {
"reference": "ELC_20261001124500_B8F2A1",
"disco": "ikeja-electric",
"meter_number": "01234567890",
"meter_type": "prepaid",
"token": "4820-1928-3849-2019-4829",
"amount": 5000,
"balance_after": 19000.00,
"created_at": "2026-10-01T12:45:00.000000Z"
}
}/api/v1/bills/status/{reference?}
Query the status and receipt of any bill payment by passing the transaction reference in the URL path, as a query parameter (?reference=...), or in a JSON body.
Multi-Language Code Examples
curl -X POST "https://irust.ng/api/v1/bills/airtime/purchase" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"network": "mtn",
"mobileno": "08031234567",
"amount": 1000
}'HTTP Status & Error Codes
| HTTP Code | Meaning | Description |
|---|---|---|
| 200 OK | Success | The bill payment or lookup was completed successfully. |
| 400 Bad Request | Provider Error / Insufficient Balance | Wallet deficit or downstream telecom / disco delivery rejection. Wallet is auto-refunded. |
| 401 Unauthorized | Invalid Token | Missing or invalid Bearer API token. |
| 404 Not Found | Not Found | The specified transaction reference was not found on your account. |
| 422 Unprocessable | Validation Error | Required parameters missing, phone number not 11 digits, or invalid amount. |
