Table of Contents

Overview
Requirements
URL Format
Authentication
Request Method
Response Format
Test API Credentails
Sample Code (PHP)
Check Wallet Balance
Query Transaction Status
Fetch Data Plan List
Query Phone Number Operator
Topup
Fetch Transaction Records

Overview

Mobilevtu.com Topup API is designed for developers to easily and seamlesly integrate mobile data and airtime topup functionality on any application using any software programing technology or development platform

The API allow you to programmatically interact with Mobilevtu.com services such as

Our API attempts to conform to the RESTful design principles. You interact with the resources exposed through the API by accessing resource collection and element URIs using the HTTP POST.

You will likely need access to a web developer or programmer (if you’re not one) to get the most use out of Mobilevtu.com API.

Access to Mobilevtu.com API is Freely available to all Mobilevtu.com customers

Requirements

In order to interact with Mobilevtu.com Topup API, you must fulfil all of the following requirements;

Once you have setup an account, simply Login to Mobilevtu.com Portal, navigate to Developers from the main menu to enable API access on your account and access your API credentials

URL Format

Mobilevtu.com API URL is made up of the base URL, the resource URI and an API key. A complete API URL will look like this; https://api.mobilevtu.com/v1/‹API Key›/‹resource URI›

Authentication

All requests to Mobilevtu.com API requires authentication. Our API Authentication is implemented as HTTP Header Authentication over TLS (HTTPS).

To authenticate your request, you need to pass the following parameters as part of your HTTP request headers;

Api-Token: Your account API token
Request-Id: A unique identifier of your current request (must be unique for each request)

Sample Authentication using CURL

       curl --request POST \
         --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/topup' \
         --header 'Api-Token: 33tdg37egsbxyube' \
         --header 'content-type: application/x-www-form-urlencoded'
                    

Request Method

Mobilevtu.com API accept only Form Encoded HTTP POST requests (Array). Any other request method will not be recognized by our API

Response Format

Mobilevtu.com API response (success or error) is returned in JSON data. Response codes are sent via the normal HTTP Response Code,

Sample Success Response

    {
        "request": "check_balance",
        "status":"success",
        "data":{
                "balance": "123",
                "currency": "NGN"
              }
    }           	
                    

Sample Error Response

    {
        "request":"fetch_data_plans",
        "status":"error",
        "message":"API access not not allowed on this account"
    }
                    

Test API Credentails

The following API credentails can be used for development and test purpose only. Transactions done using these credentails are not treated as live

Test API Key: 8yGf4Ri3UeuwaA44LX1oo0000wDc
Test API Token: HHaBgvjx9gwE88uy66zJjhey8lfd

Sample Code

Below is a PHP example showing how to implement MobileVTU top-up API using cURL. Download Complete Source Code

‹?php
$API_KEY = "your mobile vtu api key";
$API_TOKEN = "your mobile vtu api token";
$body = array('operator'=>'9mobile','type'=>'airtime','value'=>'300','phone'=>'2348012345678');
foreach($body as $key=>$value) { 
	$fields_string .= $key.'='.$value.'&';
}
rtrim($fields_string, '&');
$ch = curl_init();
curl_setopt($ch,CURLOPT_URL,"https://api.mobilevtu.com/v1/".$API_KEY."/topup");
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, false);
$headers = array (
	'Api-Token: '.$API_TOKEN,
	'Request-Id: '.time(),
	'content-type: application/x-www-form-urlencoded'
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$server_output = curl_exec ($ch); error_log($server_output) ;
curl_close ($ch);
$json_output = json_decode($server_output,true);
if($json_output['status']=="success") {
	//topup was successful. 
} else {
	//something went wrong
}
                    

We have put together a couple of sample scripts with explanation to help you get started with integrating MobileVTU API on your application.

This sample scripts are written in PHP and cURL. Click Here to download the sample PHP code

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/check_balance' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'currency=NGN'
                                

                {
                    "request": "check_balance",
                    "status":"success",
                    "data":[
                            {"balance": "123",
                            "currency": "NGN"
                          }
                    ]
                }           	
                                

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/transaction_status' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'transaction_id=DJTIG85859H9H5DUYTWFB7'
                                

                {
                    "request": "transaction_status",
                    "status":"success",
                    "transaction_id": "DJTIG85859H9H5DUYTWFB7",
                    "transaction_status": "ORDER_COMPLETED"
                }           	
                                

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/fetch_data_plans' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'operator=MTN'
                                

                {
                    "request": "fetch_data_plans",
                    "status":"success",
                    "data":[
                            {"plan": "1000",
                            "label": "1GB",
                            "operator": "MTN",
                            "validity": "30",
                            "price": "600",
                            "currency": "NGN"
                          },
                          {"plan": "2000",
                            "label": "2GB",
                            "operator": "MTN",
                            "validity": "30",
                            "price": "1100",
                            "currency": "NGN"
                          }
                          ,
                          {"plan": "10000.01",
                            "label": "10GB",
                            "operator": "MTN",
                            "validity": "30",
                            "price": "2000",
                            "currency": "NGN"
                          }
                    ]
                }           	
                                

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/number_operator' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'phone=2347012345678'
                                

                {
                    "request": "number_operator",
                    "status":"success",
                    "operator_code":"MTN",
                    "operator_name":"MTN Nigeria"
                }           	
                                

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/topup' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'operator=MTN&type=airtime&value=1000&phone=08031234567'
                                

                {
                    "request": "topup",
                    "status":"success",
                    "transaction_id": "DJTIG85859H9H5DUYTWFB7",
                    "transaction_status": "completed"
                }           	
                                

                   curl --request POST \
                     --url 'https://api.mobilevtu.com/v1/GGiet8506Rlglhglbfj7/list_transactions' \
                     --header 'Api-Token: 33tdg37egsbxyube' \
                     --header 'content-type: application/x-www-form-urlencoded'
                     --data 'limit=0'
                                

                {
                    "request": "list_transactions",
                    "status":"success",
                    "data":[
                            {"transaction_id": "TT3036HYTIFJUY82RT",
                            "description": "1GB MTN Data",
                            "datetime": "2024-11-21 06:57:20",
                            "phone": "2348031234567",
                            "operator": "MTN",
                            "status": "completed"
                          },
                          {"transaction_id": "2GH6855RE996W000TR",
                            "description": "2000 Glo Airtime",
                            "datetime": "2024-11-21 06:57:20",
                            "phone": "2345098765432",
                            "operator": "Glo",
                            "status": "failed"
                          }
                    ]
                }