API Documentation
Introduction

GSUBZ API:- is one of the best and simple VTU online/mobile recharge api, with our API you can easily integrate Bill Payment, Airtime Purchase, TV Subscription e.t.c, on your website but before you do anything, you should create a free GSUBZ Account. Then we will provide you with API Keys that you can use to make API calls and also upgrade you.

REGISTER TO GET API FOR FREE

Authentication

Authenticate your API calls by including your API KEY in the Authorization header of every request for purchase and subscription. You can manage your API keys from the dashboard. Your API KEY should be kept secret, If for any reason you believe your secret key has been compromised or you wish to reset them, you can do so from the dashboard. But you don't need authentication to access some part of our API. You can simply make GET Request to query Data.

Category

Use this request to get the list of all Category in our platform.

Endpoints - Category
GET: gsubz.com/api/category 
		

        [
    {
        "displayName": "Electricity Billl",
        "name": "electricity"
    },
    {
        "displayName": "TV Subscriptions",
        "name": "tv"
    },
    {
        "displayName": "Data Subscription",
        "name": "data"
    },
    {
        "displayName": "Airtime",
        "name": "artime"
    },
    {
        "displayName": "Transfer",
        "name": "transfer"
    }
]
Service

Request the details of a particular Service including Name, Logo, Amount, Convenience Fee, Product Type, Minimum and Maximum Amount Allowed, it helps in billing customer and payment validation during transactions, with this, you don't necessary need to get all the details of the service from the User End you can dynamically query each service from your Back end.

Example and Response: Services under Airtime Purchase
GET: gsubz.com/api/service?service=mtn 
		

    {
    "service": "MTN Airtime",
    "field": [
        {
            "displayName": "system-load-setup",
            "name": "system-load-setup",
            "type": "text",
            "description": "",
            "regExp": "",
            "required": false
        }
    ]
}
Fields

This request helps to get the list of available field on a particular service.

Example and Response: fields under etisalat
GET: gsubz.com/api/fields?service=mtn 
		

 {
    "service": "mtn",
    "field": [
        {
            "displayName": "Amount",
            "name": "amount",
            "type": "number",
            "description": "",
            "regExp": "[0-9]+",
            "required": true
        },
        {
            "displayName": "Email",
            "name": "email",
            "type": "email",
            "description": "",
            "regExp": "",
            "required": false
        },
        {
            "displayName": "Phone",
            "name": "phone",
            "type": "text",
            "description": "This is the description",
            "regExp": "[0-9]+",
            "required": true
        },
        {
            "displayName": "Recharge Time",
            "name": "Date",
            "type": "date",
            "description": "",
            "regExp": "",
            "required": false
        }
    ]
}
Plans

This request helps to get the list of available plans on a particular service. We are using the Variation for Plan in some case ( Variation is a change or slight difference in condition, amount, or level, typically within certain limits )

Example and Response: Plans under Glo Data Subscription
GET: gsubz.com/api/plans?service=mtn_cg 
		

{
    "service": "MTN-Coperate-Gifting-Data(*460*260#)",
    "PlanName": "plan",
    "fixedPrice": true,
    "plans": [
        {
            "displayName": "10GB - 30days",
            "value": "257",
            "price": "2450"
        },
        {
            "displayName": "15GB - 30days",
            "value": "259",
            "price": "3675"
        },
        {
            "displayName": "1GB - 30days",
            "value": "213",
            "price": "245"
        },
        {
            "displayName": "20GB - 30days",
            "value": "258",
            "price": "4900"
        },
        {
            "displayName": "2GB - 30days",
            "value": "215",
            "price": "490"
        },
        {
            "displayName": "3GB - 30days",
            "value": "216",
            "price": "735"
        },
        {
            "displayName": "500MB - 30 Days",
            "value": "225",
            "price": "125"
        },
        {
            "displayName": "5GB - 30days",
            "value": "217",
            "price": "1225"
        }
    ]
}
Variation Detail

Query the details of a particular variation including Amount, Variation Name and value, it helps in billing customer, display information Dynamic before/after Payment

Example and Response: gotv as a service and gotv-plus as a plan.
GET: gsubz.com/api/variation?service=gotv&value=gotv-plus 
		

{
    "service": "GoTV",
    "PlanName": "gotv-plan",
    "fixedPrice": true,
    "plans": [
        {
            "displayName": "gotv Plus",
            "value": "gotv-plus",
            "price": "100"
        }
    ]
}
Making Payment

For testing payment use: gsubz.com/api/testpay

There two types of payment, the payment for FIX Service (TV Subscription, Data Plan) which has a fixed amount and plan and the payment for Flexible services like Airtime Purchase.

You don't need to know the type of payment for each service, you can dynamically request a service details like Name, Minimum and Maximum Amount Allowed and the type as well with our API. The good news is that our system successfully detect your payment type automatically.

Parameter for each type of payment are describe below.

Flexible Payment

Flexible payment is the payment for service like Airtime Purchase and bellow are the parameter for Flexible payment.

Field Type Description
api key

(Required) Your API Authetification to access your account
requestID Interger

(Required). A unique code for every transaction
serviceID String

serviceID (Required). Merchants or Operator ID ( gotv, glo, mtm-data, airtel etc)
amount Float

Amount (Required). Amount paying without Chargers
phone string

Phone Number (Required without country code).
email String

 Email Address (Optional)
Request Flexible Payment (POST REQUEST)
		

	

    $host = 'gsubz.com/pay';
	$refer= (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https" : "http") . "://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";
	$api =  'ap_xxxxxxxxxxxxxxxxxxx'; //Your API Key
	$data = array(
	'serviceID'=> "gotv", //Merchants or Operator ID ( gotv, airtel, dstv, glo-data etc)
	'plan'=> "gotv-plus", //The plan Subscribing for (gotv-plus, gotv-value etc)
	'amount' =>  1900, // (Required) Amount to pay 
	'customerID' => 111111, // (e.g Dstv SmartCard Number) (Optional).
	'phone' => "0703xxxxxxxxxx", //without country code
	'email' => "name@example.com", //string
	'requestID' => time()+mt_rand() // unique for every transaction
	);  
	$curl       = curl_init();
	curl_setopt_array($curl, array(
	CURLOPT_URL => $host,
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_POST => true,
	CURLOPT_ENCODING => "",
	CURLOPT_POSTFIELDS => $data,
	CURLOPT_REFERER => $refer,
	CURLOPT_HTTPHEADER => array("Authorization: Bearer $api"),
	CURLOPT_FOLLOWLOCATION=> true,
	CURLOPT_MAXREDIRS => 10,   
	CURLOPT_POSTREDIR => 3,   
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "POST",
	));
	$r =  curl_exec($curl); 
	curl_close($curl);
	print_r(json_decode($r,true));
FIX Payment

Flexible payment is the payment for service like Airtime Purchase and bellow are the parameter for Flexible payment.

Parameter

Field Type Description
api key

(Required) Your API Authetification to access your account
requestID Interger

(Required). A unique code for every transaction
serviceID String

serviceID (Required). Merchants or Operator ID ( gotv, glo, mtm-data, airtel etc)
plan String

The plan Subscribing for (gotv-plus, gotv-value etc)
amount Float

Amount (Required). Amount paying without Chargers
customerID String

(e.g Dstv SmartCard Number) (Required). 
phone string

Phone Number (Required without country code).
email String

 Email Address (Optional)
Request Flexible Payment (POST REQUEST)
		


    $host = 'gsubz.com/api/pay';
	$refer= (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https" : "http") . "://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";
	$api =  'ap_xxxxxxxxxxxxxxxxxxxx'; //Your API Key
	$data = array(
	'serviceID'=> "mtn", //Merchants or Operator ID ( gotv, airtel, dstv, glo-data etc)
	'phone' => "0703xxxxxxxxxx", //integer
	'email' => "name@example.com", //string 
	'amount' =>  1000, // (Required) Amount to pay 
	'requestID' => time()+mt_rand() // unique for every transaction
	);  
	$curl       = curl_init();
	curl_setopt_array($curl, array(
	CURLOPT_URL => $host,
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_POST => true,
	CURLOPT_ENCODING => "",
	CURLOPT_POSTFIELDS => $data,
	CURLOPT_REFERER => $refer,
	CURLOPT_HTTPHEADER => array("Authorization: Bearer $api"),
	CURLOPT_FOLLOWLOCATION=> true,
	CURLOPT_MAXREDIRS => 10,   
	CURLOPT_POSTREDIR => 3,   
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "POST",
	));
	$r =  curl_exec($curl); 
	curl_close($curl);
	print_r(json_decode($r,true));





	 
	   

	   
	   
Response Both Flexible and FIX

	   
The response for Flexible and Fix look similar, just that some Array or json key are left blank if not applicable to the service

		

Array
(
    [code] => 200
    [status] => TRANSACTION_SUCCESSFUL
    [description] => TRANSACTION_SUCCESSFUL
    [content] => Array
        (
            [transactionID] => 189584034893843
            [requestID] => 897439437848
            [amount] => 2
            [phone] => 0703xxxxxxxxxxx
            [serviceID] => mtn
            [email] => name@example.com
            [customerID] => 
            [plan] => 
            [image] => gsubz.com/uploads/XXXXXXXX.jpg
            [convinience_fee] => 0
            [productType] => flexible
            [serviceName] => MTN Airtime VTU
            [status] => TRANSACTION_SUCCESSFUL
            [code] => 000
            [description] => TRANSACTION_SUCCESSFUL
            [date] => 2019-03-22T11:16:05+01:00
        )

    [gateway] => Array
        (
            [referrer] => gsubz.com/xxxxxxxx.html
            [host] => recharge.lajela.com
            [ip] => 185.2.168.39
        )

)
Payment Verification

This is actually useful after Payment, it helps to verify the status of payment, (if the payment was successfully or not due to unforeseen circumstance).

Use this link to verify testing payment https://gsubz.com/api/testverfy

Example and Response: GoTV Payment.
	  

	$host = 'https://gsubz.com/api/verify';
	$api =  'API KEY'; //Your API Key
	$data = array(
	'requestID' => 8755965695964845 // For the transaction
	);  
	$curl = curl_init();
	curl_setopt_array($curl, array(
	CURLOPT_URL => $host,
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_POST => true,
	CURLOPT_ENCODING => "",
	CURLOPT_POSTFIELDS => $data,
	CURLOPT_HTTPHEADER => array("Authorization: Bearer $api"),
	CURLOPT_FOLLOWLOCATION=> true,
	CURLOPT_MAXREDIRS => 10,   
	CURLOPT_POSTREDIR => 3,   
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "POST",
	));
	$response =  curl_exec($curl); 
	print_r(json_decode($response,true));
Response
		

Array
(
    [code] => 402
    [status] => TRANSACTION_FAILED
    [description] => INSUFFICIENT_BALANCE
    [content] => Array
        (
            [transactionID] => 8585405894594
            [requestID] => 3414793352
            [amount] => 2
            [phone] => 090xxxxxxxxxxx
            [serviceID] => gotv
            [email] => user@example.com
            [customerID] => 7017725579
            [plan] => gotv-plus
            [image] => gsubz.com/images/products/200X200/Gotv-Payment.jpg
            [convinience_fee] => 100
            [productType] => fix
            [serviceName] => Gotv Payment
            [status] => TRANSACTION_FAILED
            [code] => 016
            [description] => INSUFFICIENT_BALANCE
            [date] => 2019-03-22T11:16:05+01:00
        )

    [gateway] => Array
        (
            [referrer] => gsubz.com/xxxxxxxx.html
            [host] => recharge.lajela.com
            [ip] => 185.2.168.39
        )

)
Available Balance on Your Account

Get Your Available Balance.

Example and Response: Available balance
		

	  
		$host = 'gsubz.com/api/balance';
		$data = array(
		  'api' => 'ap_xxxxxxxxxxxxxxxxxxx' // API KEY
		);
		$curl       = curl_init();
		curl_setopt_array($curl, array(
		CURLOPT_URL => $host,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_ENCODING => "",
			CURLOPT_MAXREDIRS => 10,
			CURLOPT_USERPWD => $username.":" .$password,
			CURLOPT_TIMEOUT => 30,
			CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
			CURLOPT_CUSTOMREQUEST => "POST",
			CURLOPT_POSTFIELDS => $data,
		));
		echo curl_exec($curl);
			
		
	  
	   

	
 


  {
  "response_description": "000",
  "content": {
  "balance": "841"
   }
   }
  }
Response Code

Bellow are list of Response Code and their respective meaning.

	

	'200':'TRANSACTION_SUCCESSFUL',
	'204':'REQUIRED_CONTENT_NOT_SENT', 
	'206':'INVALID_CONTENT',
        '401':'AUTHORIZATION_FAILED', 
        '402':'ERROR_IN_PAYMENT',
        '404':'CONTENT_NOT_FOUND',
	'405':'REQUEST_METHOD_NOT_IN_POST' 
        '406':'NOT_ALLOWED', 
        '502':'GATEWAY_ERROR'