API Documentation

Introduction

RICHMAX TELCOM SERVICES 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 RICHMAX TELCOM SERVICES Account account. Then we will provide you with API Keys that you can use to make API calls.

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.

Endpoints - Category

GET: richmaxservices.com//api/category

		
        [
            {
                "displayName": "Electricity Bill",
                "name": "electricity"
            },
            {
                "displayName": "Mobile VTU",
                "name": "mobile_vtu"
            }
        ]

Subcategory

A valid response of this request will get the list of all services in a particular Category.

Example and Response: Services under Airtime Purchase

GET: richmaxservices.com//api/sub-category?category=mobile_vtu

		
[
    {
        "displayName": "MTN VTU",
        "name": "mtn_vtu",
        "image": "\/\/vtu.com\/uploads\/service\/xxxxx.jpg",
        "max": "5000000000",
        "min": "5",
        "fee": "100",
        "planName": "plan", //ignored when not available
        "feePercentage": true,
        "feeCapped": "3"
    }
]

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: richmaxservices.com//api/service?service=mtn_vtu

		
    {
        "displayName": "MTN VTU",
        "name": "mtn_vtu",
        "image": "\/\/vtu.com\/uploads\/service\/xxxxxx.jpg",
        "planName": "plan", //ignored when not available
        "max": "5000000000", 
        "min": "5",
        "fee": "100",
        "feePercentage": true,
        "feeCapped": "3"
    }

Fields

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

Example and Response: fields under 9Mobile

GET: richmaxservices.com//api/fields?service=9mobile

		
 {
    "service": "9mobile",
    "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: richmaxservices.com//api/plans?service=glo-data

		
{
    "service": "Glo Data",
    "PlanName": "plan",
    "fixedPrice": true,
    "plans": [
        {
            "displayName": "10000 mb for USD10",
            "value": "10000-mb",
            "price": "100"
        },
        {
            "displayName": "1month unlimited for 30USD",
            "value": "1mon-unlimited",
            "price": "30"
        },
        {
            "displayName": "1 year unlimited for 200USD",
            "value": "1yr-unlimited",
            "price": "200"
        }
    ]
}

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: richmaxservices.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: richmaxservices.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 = 'richmaxservices.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 = 'richmaxservices.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] => richmaxservices.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] => richmaxservices.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://richmaxservices.com//api/testverfy

Example and Response: GoTV Payment.

	  
	$host = 'https://richmaxservices.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] => richmaxservices.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] => richmaxservices.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 = 'richmaxservices.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'