GN DATA
Developer Portal v1.0

GN Data API Documentation

Automate Airtime recharge, Data bundle top-ups, Cable TV renewals, and Electricity utility payments via clean, high-performance RESTful endpoints.

Base URL http://localhost:8002/api/v1

Getting Started

Follow these simple steps to become an API user and start integrating GN Data services into your application:

1

Register Account

Create a user account on the GN Data website/app.

2

Contact Support

Contact support via WhatsApp or Email (support@gndata.com.ng) to request Developer API access.

3

Generate API Key

Access your Developer API Settings dashboard to generate your Authorization: Bearer <API_KEY> token.

4

Start Requesting

Call our endpoints with your API Key to automate airtime, data, cable, and electricity transactions.

How to Activate your Developer API Account: To become an API reseller/developer user, please reach out to our support team with your registered account email:

Authentication & Headers

GN Data uses standard Bearer token authorization. Pass your API Key in the HTTP Authorization header.

Auto-Detection: The API backend automatically detects whether your Bearer token is a Developer API Key or a User JWT Token. No 4-digit transaction PIN is required for developer API requests.

Required Request Headers

Header Name Type Description
Authorization String REQUIRED Bearer <YOUR_API_KEY>
Idempotency-Key String REQUIRED (POST) Unique UUID string per purchase request to prevent accidental duplicate debits.
Content-Type String REQUIRED Must be application/json.
GET /api/v1/wallet/balance Get User Balance

Fetch your current wallet balance, currency, user ID, email, and virtual account funding details.

Headers Required

Authorization Bearer <API_KEY>
SAMPLE RESPONSE (200 OK) 
{
  "balance": 15450.00,
  "currency": "NGN",
  "user_id": 42,
  "email": "developer@example.com",
  "account_numbers": [
    {
      "bank_name": "Palmpay",
      "account_number": "9912345678",
      "account_name": "GNDATA-Ganiu",
      "provider": "paymentpoint"
    }
  ]
}
GET /api/v1/airtime/services List Airtime Networks

Retrieve all available airtime network providers along with network ID, name, limits, and reseller commission rates.

SAMPLE RESPONSE (200 OK) 
[
  {
    "id": 1,
    "name": "MTN Airtime",
    "image_url": "https://api.gndata.com.ng/static/mtn.png",
    "minimum_amount": 50.0,
    "maximum_amount": 50000.0,
    "available": true,
    "reseller_commission_rate": 2.0
  }
]
POST /api/v1/airtime/purchase Purchase Airtime

Instant airtime recharge to any phone number using the Network ID.

Request Payload Parameters

Field Type Description
phone String REQ Recipient phone number (e.g. 08031234567).
amount Integer REQ Recharge amount in NGN (e.g. 500).
id Integer REQ Network database ID (e.g. 1 for MTN).
REQUEST BODY (JSON) 
{
  "phone": "08031234567",
  "amount": 500,
  "id": 1
}
RESPONSE (200 OK) 
{
  "request_id": "GND_AIR_20260814_10293",
  "status": "success",
  "cost": 490.0,
  "phone": "08031234567",
  "transaction_id": "TX_9981240",
  "message": "Airtime recharge successful"
}
GET /api/v1/data/services List Data Networks

Fetch active data network providers. Pass ?include_plans=true query parameter to nest all available data plans inside each network object.

SAMPLE RESPONSE (200 OK) 
[
  {
    "id": 1,
    "name": "MTN Data",
    "image_url": "https://api.gndata.com.ng/static/mtn.png",
    "minimum_amount": 0.0,
    "maximum_amount": 50000.0,
    "available": true,
    "plans": null
  }
]
GET /api/v1/data/plans/{network_id} Get Data Plans for Network

Retrieve all active data plans for a specific network ID (e.g. network_id = 1 for MTN Data). Prices returned reflect your developer API user rate.

SAMPLE RESPONSE (200 OK) 
[
  {
    "id": 10,
    "name": "MTN SME 1GB - 30 Days",
    "network_id": 1,
    "price": 265.0,
    "duration": "Monthly",
    "type": "SME",
    "total_data": "1GB",
    "available": true
  }
]
POST /api/v1/data/purchase Purchase Data Bundle

Instant data bundle top-up for a specified phone number using network_id and plan_id.

Request Payload Parameters

Field Type Description
phone String REQ Recipient phone number.
network_id Integer REQ Network ID (e.g. 1 for MTN).
plan_id Integer REQ Data plan ID (e.g. 10).
REQUEST BODY (JSON) 
{
  "phone": "08031234567",
  "network_id": 1,
  "plan_id": 10
}
RESPONSE (200 OK) 
{
  "request_id": "GND_DATA_20260814_99214",
  "status": "success",
  "amount": 265.0,
  "phone": "08031234567",
  "network_id": 1,
  "plan_id": 10,
  "transaction_id": "TX_8812903",
  "message": "Data purchase successful"
}

Cable TV Subscriptions

POST /api/v1/tv/verify Verify Smartcard / IUC Number

Verify customer details before subscribing to DSTV, GOTV, Startimes, or Showmax.

Field Type Description
billers_code String REQ Smartcard or IUC number.
service_id String REQ dstv, gotv, startimes, or showmax.
REQUEST BODY 
{
  "billers_code": "7012345678",
  "service_id": "gotv"
}
RESPONSE (200 OK) 
{
  "customer_name": "JOHN DOE",
  "customer_number": "7012345678",
  "status": "Open",
  "due_date": "2026-09-01",
  "balance": "0.00"
}
POST /api/v1/tv/purchase Subscribe Cable TV

Purchase or renew TV subscription packages.

Field Type Description
billers_code String REQ Smartcard or IUC number.
service_id String REQ dstv, gotv, startimes, etc.
variation_code String REQ Package variation code (e.g. gotv-jolli).
amount Integer REQ Package price.
phone String REQ Customer phone number.
REQUEST BODY 
{
  "billers_code": "7012345678",
  "service_id": "gotv",
  "variation_code": "gotv-jolli",
  "amount": 3950,
  "phone": "08031234567"
}

Electricity Utility Bills

POST /api/v1/electricity/verify Verify Meter Number

Verify Prepaid or Postpaid meter number to retrieve customer name & address.

Field Type Description
billers_code String REQ Meter number (e.g. 1111111111111).
service_id String REQ DISCO service code (e.g. ikeja-electric).
type String REQ prepaid or postpaid.
REQUEST BODY 
{
  "billers_code": "1111111111111",
  "service_id": "ikeja-electric",
  "type": "prepaid"
}
RESPONSE (200 OK) 
{
  "customer_name": "JANE DOE",
  "address": "12 ALLEN AVENUE, IKEJA",
  "status": "Open",
  "customer_number": "1111111111111"
}
POST /api/v1/electricity/purchase Buy Electricity Token

Purchase electricity tokens for prepaid meters or pay postpaid bills.

Field Type Description
billers_code String REQ Meter number.
service_id String REQ DISCO service code (e.g. ikeja-electric).
variation_code String REQ prepaid or postpaid.
amount Integer REQ Amount in NGN.
phone String REQ Recipient phone number.
RESPONSE (200 OK) 
{
  "request_id": "GND_ELEC_20260814_88102",
  "status": "success",
  "amount": 2000.0,
  "phone": "08031234567",
  "service_id": "ikeja-electric",
  "variation_code": "prepaid",
  "purchased_code": "1234-5678-9012-3456-7890",
  "transaction_id": "TX_771920",
  "message": "Token generated successfully"
}

Webhooks & Event Notifications

Register your webhook callback URL in the developer dashboard to receive real-time HTTP POST notifications when transactions complete or data plan pricing updates occur.

SAMPLE WEBHOOK PAYLOAD 
{
  "event": "transaction.updated",
  "request_id": "GND_AIR_20260814_10293",
  "status": "success",
  "amount": 500.0,
  "phone": "08031234567",
  "timestamp": "2026-08-14T06:30:00Z"
}

Standard HTTP Error Codes

Status Code Error Description Resolution
400 Bad Request Invalid request parameters or insufficient wallet balance. Check your request payload or fund your API wallet.
401 Unauthorized Missing or invalid Authorization: Bearer <API_KEY> header. Verify your API Key in the developer dashboard.
409 Conflict Duplicate Idempotency-Key in progress. Wait for initial transaction completion or use a new key.
504 Gateway Timeout Upstream provider timeout during processing. Transaction is marked pending for automated sync or admin review.