BomaVTU API Documentation

Welcome to the official API documentation for BomaVTU. Here you'll find details on how to use the API to integrate with the BomaVTU platform.

API Overview

BomaVTU API provides a platform for developers to interact with the system programmatically. It allows users to make requests for services like user details, top-up, balance inquiries, data bundles, cable subscription, electricity bill, examination pin, bank transfer and other services within the BomaVTU ecosystem.

Authentication

To access the BomaVTU API, you must authenticate using an API key. You can obtain an API key by registering on the BomaVTU portal. Click here to register.

Request Header
Authorization: Bearer <Your_API_Key>
Content-Type: application/json
User-Agent: BomaVTU-api-browser (it is comoulsory to use this user agent and do not change the string)

API Endpoints

1. Get User Details

Endpoint: /portal/api-user

Method: POST

Description: This endpoint allows you to retrieve the current user of the account.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-user',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer xxxxxx',
'Content-Type: application/json',
'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
    "status": 200,
    "data": {
    "username": "James",
    "first_name": "Joe",
    "last_name": "Doe",
    "email": "example@gmail.com",
    "phone": "09060000000",
    "balance": "1000.00",
    "account_name": "BomaVTU-Joe",
    "account_number": "66xxxxxxxx",
    "bank_name": "PalmPay"
    }
}

2. Airtime

Endpoint: /portal/api-airtime

Method: POST

Description: Use this endpoint to top up a user's account.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-airtime',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "network" => network_id,
      "amount" => amount,
      "mobile_number" => phone,
      "Ported_number" => true,
      "airtime_type" => "VTU",
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "description": "MTN Airtime VTU\n09030000000\nChannel: API",
    "date": "2025-01-21 14:15:30",
    "network": "MTN",
    "phone": "09030000000",
    "amount": 100,
    "amount_pay": 98,
    "previous_bal": "156.10",
    "new_bal": 58.10,
    "msg": "Transaction Successful"
  }
}

3. Data Bundle

Endpoint: /portal/api-data

Method: POST

Description: Use this endpoint to procure data bundle.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-data',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "network" => network_id,
      "plan" => plan_id,
      "mobile_number" => phone,
      "Ported_number" => true,
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "description": "MTN SME Data\n09030000000\nChannel: API\n500MB",
    "date": "2025-01-21 14:15:30",
    "network": "MTN",
    "phone": "09030000000",
    "amount": 1000,
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Successful"
  }
}

4. Examination Pins

Endpoint: /portal/api-exam-pins

Method: POST

Description: Use this endpoint to purchase examination pins e.g WAEC and NECO.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-exam-pins',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "exam_name" => WAEC or NECO,
      "quantity" => 1 (maximum is 5),
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "description": "1 WAEC pin purchased",
    "date": "2025-01-21 14:15:30",
    "exam_name": "WAEC",
    "pin": "628728738399027",
    "amount": 1000,
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Successful"
  }
}

5. IUC Validator

Endpoint: /portal/api-iuc-validator

Method: POST

Description: Use this endpoint to validate smart card number.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-iuc-validator',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "smart_card_number" => 123456789,
      "cablename" => "GOTV"
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "customer_name": "Joe Boy",
    "msg": "Validation Successful"
  }
}

6. Cable Subscription

Endpoint: /portal/api-paytv

Method: POST

Description: Use this endpoint to subscribe to GOTV, DSTV and STARTIME.

Charges: N20

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-paytv',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "cablename" => cable_id,
      "cableplan" => cable_plan_id,
      "smart_card_number" => 123456789,
      "customer_name" => "Joe Boy",
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "cablename": "Gotv_Jinja",
    "date": "2025-01-21 14:15:30",
    "smart_card_number": 123456789,
    "amount": 1000,
    "customer_name": "Joe Boy",
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Successful"
  }
}

7. Meter Validator

Endpoint: /portal/api-meter-validator

Method: POST

Description: Use this endpoint to validate Electricity meter.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-meter-validator',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "meternumber" => 38584993839,
      "disconame" => "Ibadan-Electric", //put hyphen in between the disco name to avoid space
      "meterType" => (PREPAID or POSTPAID),
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "customer_name": "Joe Boy",
    "address": "44 Alaba Market, Oshodi",
    "msg": "Validation Successful"
  }
}

8. Electricity Payment

Endpoint: /portal/api-electricity

Method: POST

Description: Use this endpoint to make payment on electricity e.g Ikeja Electric, Abuja Electric, Ibadan Electric etc.

Charges: N20

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-electricity',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "disco_id" => disco_id,
      "disco_name" => "Ibadan-Electric", //put hyphen in between the disco name to avoid space
      "amount" => amount,
      "meter_number" => 38584993839,
      "MeterType" => (PREPAID or POSTPAID),
      "Customer_Phone" => "09000000000",
      "customer_name" => "Joe Boy",
      "customer_address" => "44 Alaba Market, Oshodi",
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "disconame": "Ibadan-Electric",
    "date": "2025-01-21 14:15:30",
    "meter_number": 38584993839,
    "MeterType": "POSTPAID",
    "amount": 1000,
    "customer_name": "Joe Boy",
    "customer_address": "44 Alaba Market, Oshodi",
    "Customer_Phone": "09000000000",
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Successful"
  }
}

9. Bank Account Details Validator

Endpoint: /portal/api-bank-validator

Method: POST

Description: Use this endpoint to resolve bank details.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-bank-validator',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "bank_id" => '044',
      "account_number" => "2372823673"
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "account_name": "Joe Boy",
    "recepient_code": "REC-hcjjjkyee38774933948948",
    "msg": "Validation Successful"
  }
}

10. Bank Transfer

Endpoint: /portal/api-bank-transfer

Method: POST

Description: Use this endpoint to make transfer to any commercial or microfinance bank.

Charges:
N100 - N1,999 = N50 charges
N2,000 - N2,999 = N100 charges
N3,000 and above = N150 charges

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-bank-transfer',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "recepient_code" => "REC-hcjjjkyee38774933948948",
      "amount" => amount,
      "narration" => '', // it can be empty
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "account_number": "2384738367",
    "bank_name": "Access Bank Plc",
    "date": "2025-01-21 14:15:30",
    "amount": 1000,
    "account_name": "Joe Boy",
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Successful"
  }
}

11. Transaction Re-query

Endpoint: /portal/api-transaction-query

Method: POST

Description: Use this endpoint to fetch transaction status.

Example Request:
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://bomavtu.com.ng/portal/api-transaction-query',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
      "reference" => your_unique_reference_id
      )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer xxxxxx',
    'Content-Type: application/json',
    'User-Agent: BomaVTU-api-browser')));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response:

{
  "status": 200,
  "data": {
    "status": "success",
    "reference": "your_unique_reference_id",
    "description": "MTN Airtime VTU 09064572140 Channel: API",
    "username": "Joe",
    "email": "joeboy@gmail.com",
    "date": "2025-01-21 14:15:30",
    "transaction_status": "Completed",
    "amount": 1000,
    "service": "Airtime VTU",
    "previous_bal": "1156.10",
    "new_bal": 56.10,
    "msg": "Transaction Fetched Successfully"
  }
}

12. Pending Transaction Response

Description: incase of network issues, use this response for pending transaction because transaction amount will be debited. Pending transaction can be refunded or processed.

{
  "status": 200,
  "data": {
    "status": "pending",
    "reference": "your_unique_reference_id",
    "msg": "Transaction was processing"
  }
}

Error Codes

Code Description
200 200 Ok - The request transaction was successful.
400 Bad Request - The request was invalid or malformed.
401 Unauthorized - Authentication failed.
404 Not Found - The requested resource does not exist.
500 Internal Server Error - A problem occurred on the server.