API Documentation
bolt Developer Center

RICHMAX TELCOM SERVICES API Documentation

Integrate airtime, data, TV subscription, bill payment and other VTU services with simple endpoints, predictable responses, and secure API key authentication.

vpn_key Get API For Free shield Authentication
Introduction

RICHMAX TELCOM SERVICES API is a simple VTU online and mobile recharge API. With our API you can integrate bill payment, airtime purchase, TV subscription and more on your website.

Before you start, create a free RICHMAX TELCOM SERVICES account. Then we will provide API keys that you can use to make API calls.

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. Keep your API key secret. If you believe your key has been compromised or you want to reset it, you can do so from the dashboard.

Some API requests do not require authentication and can be accessed with simple GET requests to query data.

Category

Use this request to get the list of all categories on our platform.

Endpoint
GET richmaxservices.com//api/category
[
    {
        "displayName": "Electricity Bill",
        "name": "Electricity"
    },
    {
        "displayName": "Airtime",
        "name": "airtime"
    }
]
Subcategory

A valid response from this request returns 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",
        "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. This helps with billing, validation, and dynamic service handling from your backend.

Example and Response: Airtime Purchase Service
GET richmaxservices.com//api/service?service=mtn_vtu
{
    "displayName": "MTN VTU",
    "name": "mtn_vtu",
    "image": "\/\/vtu.com\/uploads\/service\/xxxxxx.jpg",
    "planName": "plan",
    "max": "5000000000",
    "min": "5",
    "fee": "100",
    "feePercentage": true,
    "feeCapped": "3"
}
Fields

This request helps you get the list of available fields 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 gets the list of available plans on a particular service. We use variation for plan in some cases.

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. This helps with customer billing and dynamic information display before or 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 are two types of payment: fixed service payment such as TV subscription and data plan, and flexible service payment such as airtime purchase.

You do not need to know the payment type for every service. You can dynamically request service details such as name, minimum and maximum amount, and product type. Our system detects the payment type automatically.

Parameters for each payment type are described below.

Flexible Payment

Flexible payment is for services like airtime purchase.

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';
$data = array(
    'serviceID'=> "gotv",
    'plan'=> "gotv-plus",
    'amount' =>  1900,
    'customerID' => 111111,
    'phone' => "0703xxxxxxxxxx",
    'email' => "name@example.com",
    'requestID' => time()+mt_rand()
);
$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

Fixed payment is for services where a fixed amount and plan are required.

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 Fixed 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';
$data = array(
    'serviceID'=> "mtn",
    'phone' => "0703xxxxxxxxxx",
    'email' => "name@example.com",
    'amount' =>  1000,
    'requestID' => time()+mt_rand()
);
$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 for Flexible and Fixed Payment

The response for flexible and fixed payment looks similar. Some array or JSON keys may be blank when they are 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 useful after payment. It helps verify whether the payment was successful or failed due to an 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';
$data = array(
    'requestID' => 8755965695964845
);
$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'
);
$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

Below are response codes and their meanings.

'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'
add_shopping_cart