REST API v2.0 • Production Ready

Developer API Documentation

Seamlessly integrate Airtime, SME & Gifting Data, Cable TV, Electricity, Data Pins, and Exam Checkers directly into your application, web portal, or custom VTU software.

API Topics

1 Overview & General Architecture

The BREMAVTU REST API allows API users to automate top-ups and subscriptions. All endpoints receive and respond with application/json.

Base URL: https://www.bremasub.nutrihconsult.com/api

Content-Type: application/json

Accept: application/json

Rate Limits: 60 requests / minute

2 Authentication Protocol

All private API endpoints require your Secret API Key. Pass your key in either the X-API-KEY header or as a Bearer token.

Header	Type	Value Example	Description
X-API-KEY	String	brm_live_7f8a9b2c3d4e...	Recommended header for custom integrations
Authorization	String	Bearer brm_live_7f8a9b...	Standard HTTP Authorization format

Security & Transaction PIN

For financial safety, purchase requests require authorization via your transaction PIN. You may provide either:

Raw 4-digit PIN: "transaction_pin": "1234"
Or SHA-256 Hashed PIN: "transaction_pin_hash": "03ac674216f3e15c..."

GET

/wallet/balance

Query your current available API wallet balance.

# cURL
curl -X GET "https://www.bremasub.nutrihconsult.com/api/wallet/balance" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"

Response (200 OK)

{
  "status": "success",
  "message": "Wallet balance retrieved successfully",
  "data": {
    "balance": 25400.50,
    "currency": "NGN"
  }
}

POST

/airtime/purchase

Dispatches VTU or Share & Sell airtime instantly to any Nigerian network.

Field	Type	Required	Description
network	string	Yes	`mtn`, `airtel`, `glo`, or `9mobile`
amount	number	Yes	Minimum ₦50.00
phone	string	Yes	Recipient phone number (e.g. `08031234567`)
transaction_pin	string	Yes*	Your 4-digit PIN (or provide `transaction_pin_hash`)

Payload Example

{
  "network": "mtn",
  "amount": 500,
  "phone": "08031234567",
  "transaction_pin": "1234"
}

GET

/data/plans

List all cataloged data plans and their unique id. Pass optional query ?network=mtn to filter.

Response Sample

{
  "status": "success",
  "message": "Data plans retrieved successfully",
  "data": [
    {
      "id": 1,
      "network": "MTN",
      "name": "1.0GB SME",
      "data_type": "SME",
      "price": 285.00,
      "duration": "30 DAYS"
    }
  ]
}

POST

/data/purchase

Subscribe data to a target recipient using the plan's plan_id.

Request Body

{
  "plan_id": 1,
  "phone": "08031234567",
  "transaction_pin": "1234"
}

Response (200 OK)

{
  "status": "success",
  "message": "Data purchase successful",
  "data": {
    "reference": "DATA_6AD9D9C33B88D",
    "network": "MTN",
    "plan_name": "1.0GB SME",
    "phone": "08031234567",
    "amount": 285.00,
    "status": "successful"
  }
}

7 Cable TV Subscriptions (DSTV, GOTV, Startimes)

Step 1: Retrieve plans from GET /cable/plans.

Step 2: Validate customer IUC smartcard with POST /cable/verify.

Step 3: Recharge subscription via POST /cable/purchase.

Purchase Request Body

{
  "plan_id": 12,
  "smartcard_number": "1023456789",
  "transaction_pin": "1234"
}

8 Electricity Bill & Prepaid Token

Verify meter number with POST /electricity/verify.

Purchase prepaid token with POST /electricity/purchase.

Purchase Request Body

{
  "provider": "ikeja-electric",
  "meter_number": "01234567891",
  "meter_type": "prepaid",
  "amount": 2000,
  "transaction_pin": "1234"
}

POST

/exams/purchase

Generate WAEC, NECO, and NABTEB scratch pin codes.

Request Body

{
  "provider_id": "waec",
  "quantity": 1,
  "transaction_pin": "1234"
}

10 HTTP Status Codes & Error Envelope

Code	Status	Reason
200	OK	Request completed successfully.
400	Bad Request	Invalid parameters, insufficient wallet balance, or invalid PIN.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	User is not an active API User.
500	Server Error	Provider communication failure or upstream timeout.