RTEMMY API Documentation

Integrate airtime, data, cable TV, electricity and exam PIN services into your application.

Introduction

Our API is a RESTful interface that enables seamless integration of our services into your application. It uses RESTful endpoints and standard HTTP methods, providing conventional HTTP response codes to signify the success or failure of API requests.

Our data & airtime API endpoints are configured to be compatible with MSORG & ADEX templated websites. Use your API key for authentication on both endpoints. Plan IDs can be found on PLAN/BOUQUET IDs/DISCOs.

API Keys

Pass your API token in the Authorization header of every request sent to our server. The value must be in the format Token your-token, where your-token is the API token found on your settings page.

Keys security

Keep your API token as secret as possible. If you suspect that it has been compromised, log in to your account and generate a new token as fast as possible to invalidate the old one.

API Request

Base URL: https://rtemmy.com.ng

Method: POST

Headers: Content-Type (the content format our server accepts), Accept (the format of the response our server returns) and Authorization.

Body: The request body must be in JSON format. The parameters are listed under each service below. All parameters are compulsory unless stated otherwise.

Sample request code (PHP)

<?php

$postRequest = array(
    'parameter1' => 'value1',
    'parameter2' => 'value2'
);

$xpostRequest = json_encode($postRequest);

$url = 'url-stated-in-each-service-below';
$cURLConnection = curl_init($url);
curl_setopt($cURLConnection, CURLOPT_POST, true);
curl_setopt($cURLConnection, CURLOPT_POSTFIELDS, $xpostRequest);
curl_setopt($cURLConnection, CURLOPT_RETURNTRANSFER, true);

curl_setopt($cURLConnection, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Accept: application/json",
    "Authorization: Token " . $your_token
));

$data = curl_exec($cURLConnection);
curl_close($cURLConnection);

$xdata = json_decode($data, true);
echo $data;
exit;

?>

Responses

For all requests, our API returns standard HTTP response codes in the 200s to 400s range. More details about the response are included in the description key. These are the codes you are likely to receive:

Code	Meaning
200 & 201	You did everything right
400	Not all required parameters were provided
401	Authentication failed
402	Request could not be processed
403	The account cannot perform the request
409	Duplicate request detected
424	Transaction failed
500 & above	Processing: we are not sure of the status. It has possibly been delivered or could still be delivered

It is safer to mark requests that return codes outside the 2xx and 4xx ranges defined above as pending.

You can also track transaction statuses using the Status key in our responses. It can have any of these values: success, failed and pending. Do not set pending to failed. If 'error' key is set, outrightly fail the transaction. The array of values of the 'error' key provides more details.

Fetch Balance

Fetch the user's account details and wallet balance.

POST/api/user/

Parameters

Parameter	Description
none	none

Sample responses (JSON)

Success
{
    "user": {
        "email": "email@your-email.com",
        "phone_number": "08034567890",
        "first_name": "FirstName",
        "surname": "SurName",
        "wallet_balance": 20643.3
    }
}

Failure
{
    "code": "401",
    "description": {
        "errorResponse": "Authentication failed"
    },
    "time": "2024-07-13 20:22:54"
}

Buy Airtime

Purchase airtime for all networks.

POST/api/topup/

Parameters

Parameter	Description
network	The ID of the network to recharge from: `1` for MTN, `2` for Glo, `3` for 9mobile or `4` for Airtel
airtime_type	Type of airtime recharge. It has the value `VTU`
mobile_number	Beneficiary phone number
amount	Amount of airtime to be purchased. Minimum of N50
request-id	Custom user reference ID (optional). Useful when querying transaction status

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "userEmail": "your-email@xyz.com",
        "recipient": "07033333333",
        "narration": "MTN VTU N200",
        "trueResponse": "VTU vending N200.00 for 07033333333",
        "amountCharged": "186.00",
        "ourRef": "202407140837823726ae834d34d",
        "userRef": ""
    },
    "Status": "success",
    "api_response": "You recharge of N100 to 08034567890 was successful.",
    "time": "2024-07-12 16:56:14"
}

Failure
{
    "code": "424",
    "description": {
        "userEmail": "your-email@xyz.com",
        "recipient": "07033333333",
        "narration": "MTN VTU N200",
        "errorResponse": "Invalid phone number",
        "amountCharged": "186.00",
        "ourRef": "202407140837823726ae834d34d",
        "userRef": ""
    },
    "Status": "failed",
    "api_response": "You recharge of N100 to 08034567890 was unsuccessful.",
    "time": "2024-07-12 16:56:14"
}

Or
{
    "code": "403",
    "description": {
        "errorResponse": "User account disabled. Please contact support"
    },
    "time": "2024-07-12 16:56:14"
}

Fetch Data Plans

Returns all data plans currently available for the network provided. If no network is provided, all data plans are returned.

POST/api/fetch_data_plans/

Parameters

Parameter	Description
networkId	The ID of the network whose bundles are to be fetched: `1` for MTN, `2` for Glo, `3` for 9mobile or `4` for Airtel

Sample responses (JSON)

Success
{
    "Status": "success",
    "bundles": [
        {
            "networkName": "MTN",
            "network": "1",
            "planType": "awoof",
            "planName": "1GB 1 Day",
            "planId": "137",
            "networkPrice": "200.00"
        },
        {
            "networkName": "Glo",
            "network": "2",
            "planType": "CG",
            "planName": "3GB 30 Days",
            "planId": "100",
            "networkPrice": ""
        },
        {
            "networkName": "Airtel",
            "network": "4",
            "planType": "gifting",
            "planName": "1.5GB 30 Day",
            "planId": "137",
            "networkPrice": "1500.00"
        }
    ]
}

Failure
{
    "detail": "Invalid token"
}

Buy Data

Purchase data bundles for all networks.

POST/api/data/

Parameters

Parameter	Description
network	The ID of the network to recharge from: `1` for MTN, `2` for Glo, `3` for 9mobile or `4` for Airtel
plan	The ID of the data bundle to be purchased. All plan IDs are on the PLAN/BOUQUET IDs/DISCOs page
mobile_number	Beneficiary phone number
request-id	Custom user reference ID (optional). Useful when querying transaction status

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "userEmail": "your-email@xyz.com",
        "recipient": "07033333333",
        "narration": "MTN SME Data 5GB",
        "trueResponse": "You have successfully gifted 2347033333333 with 5GB of Data. valid till 8/11/2024 12:00:00 PM",
        "amountCharged": "186.00",
        "ourRef": "202407140837823726ae834d34d",
        "userRef": ""
    },
    "Status": "success",
    "api_response": "You have successfully purchased 1GB to 08034567890",
    "time": "2024-07-12 16:56:14"
}

Failure
{
    "code": "424",
    "description": {
        "userEmail": "your-email@xyz.com",
        "recipient": "07033333333",
        "narration": "MTN SME Data 5GB",
        "errorResponse": "Invalid phone number",
        "amountCharged": "186.00",
        "ourRef": "202407140837823726ae834d34d",
        "userRef": ""
    },
    "Status": "failed",
    "api_response": "Your purchase of 500MB to 08034567890 was unsuccessful.",
    "time": "2024-07-12 16:56:14"
}

Or
{
    "code": "403",
    "description": {
        "errorResponse": "User account disabled. Please contact support"
    },
    "error": ["User account disabled. Please contact support"],
    "time": "2024-07-12 16:56:14"
}

Fetch Cable TV Bouquets

Returns all bouquets currently available for the cable type. You can also refer to PLAN/BOUQUET IDs/DISCOs.

POST/api/fetch_cable_tv_bouquets

Parameters

Parameter	Description
cableType	Either `DSTV`, `GOTV` or `STARTIMES`

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "cableType": "DSTV",
        "bouquets": [
            {
                "planName": "DSTV HDPVR/XTRAVIEW_ADDON",
                "planId": "dstv_hdpvrxtraview_addon",
                "providerPrice": "40000.00"
            },
            {
                "planName": "DSTV PADI",
                "planId": "dstv_padi",
                "providerPrice": "45000.00"
            },
            {
                "planName": "DSTV CONFAM",
                "planId": "dstv_confam",
                "providerPrice": "50000.00"
            }
        ]
    }
}

Failure
{
    "code": "424",
    "description": {
        "errorResponse": "No bouquet found"
    }
}

Verify Cable TV Customer Info

Confirm that payment is about to be made to the correct cable TV customer.

POST/api/verify_cabletv_smartno/

Parameters

Parameter	Description
cableType	Either `DSTV`, `GOTV` or `STARTIMES`
smartNo	The smartcard or IUC number of the customer's decoder
bouquetId	The current bouquet of the decoder account. Refer to PLAN/BOUQUET IDs/DISCOs for the bouquet ID

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "smartcard": "7031xxxxxx",
        "customerName": "Customer Name",
        "customerNumber": "",
        "status": ""
    }
}

Failure
{
    "code": "424",
    "description": {
        "narration": "Verification failed"
    }
}

Cable TV Payment

Pay for cable TV subscriptions.

POST/api/cabletv/

Parameters

Parameter	Description
cableType	Either `DSTV`, `GOTV` or `STARTIMES`
custPhone	Customer phone number
bouquetId	The bouquet being paid for. All bouquets have fixed amounts
smartcardNo	The smartcard or IUC number of the customer's decoder
customerName	The customer name as fetched using the Verify Cable TV Customer Info endpoint
request-id	Custom user reference ID (optional). Useful when querying transaction status

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "recipient": "1212121212",
        "narration": "GOTV SUPA PLUS @ 16800",
        "trueResponse": "TRANSACTION SUCCESSFUL",
        "amountCharged": 16716,
        "ourRef": "2026100823286ac8190e6164f"
    },
    "Status": "successful",
    "ident": "2026100823286ac8190e6164f",
    "balance_before": 17673,
    "balance_after": 957,
    "cableId": "gotv",
    "bouquetId": "16",
    "bouquet": "GOTV SUPA PLUS",
    "api_response": "TRANSACTION SUCCESSFUL",
    "amount": 16800,
    "create_date": "2026-10-08 23:28:30"
}

Failure
{
    "code": "424",
    "description": {
        "recipient": "1212121211",
        "narration": "GOTV SUPA PLUS @ 16800",
        "errorResponse": "TRANSACTION FAILED",
        "amountCharged": "0.00",
        "ourRef": "2026100823406ac81bccd11c4"
    },
    "Status": "failed",
    "ident": "2026100823406ac81bccd11c4",
    "balance_before": 20957,
    "balance_after": 20957,
    "cableId": "GOTV",
    "bouquetId": "16",
    "bouquet": "GOTV SUPA PLUS",
    "api_response": "TRANSACTION FAILED",
    "amount": 16800,
    "create_date": "2026-10-08 23:40:12"
}

Verify Electricity Meter Info

Confirm that payment is about to be made to the correct customer.

POST/api/verify_electricity_meterno/

Parameters

Parameter	Description
discoId	For Disco IDs, refer to PLAN/BOUQUET IDs/DISCOs
meterType	`prepaid` or `postpaid`
meterNo	The electricity account number attached to the customer's postpaid or prepaid meter

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "meterNo": "3122XXXXXX",
        "customerName": "Akinjide Akin Flat 4",
        "customerAddress": "102 Akinjide Close USA Avenue Abuja"
    }
}

Failure
{
    "code": "424",
    "description": {
        "narration": "Verification failed"
    }
}

Electricity Bill Payment

Make payments for electricity.

POST/api/electricity/

Parameters

Parameter	Description
discoId	For Disco types and their IDs, refer to PLAN/BOUQUET IDs/DISCOs
meterType	`prepaid` or `postpaid`
meterNo	The electricity account number attached to the customer's postpaid or prepaid meter
amount	Amount to be credited to the meter account. Minimum of N500 and maximum of N1,000,000
phone	Customer's phone number
request-id	Custom user reference ID (optional). Useful when querying transaction status

Sample responses (JSON)

Success (store all data in the trueResponse key)
{
    "code": "200",
    "description": {
        "recipient": "1111111111111",
        "narration": "Ikeja Electric Prepaid N500",
        "trueResponse": {
            "purchased_code": "26362054405982757802",
            "units": "79.9 kWh"
        },
        "amountCharged": 495,
        "ourRef": "2026100817536ac7ca7761978"
    },
    "Status": "successful",
    "ident": "2026100817536ac7ca7761978",
    "balance_before": 18168,
    "discoID": "5",
    "disco_name": "Ikeja Electric Prepaid",
    "balance_after": 17673,
    "api_response": {
        "purchased_code": "26362054405982757802",
        "units": "79.9 kWh"
    },
    "amount": 500,
    "create_date": "2026-10-08 17:53:11"
}

Failure
{
    "code": "424",
    "description": {
        "recipient": "1111111111112",
        "narration": "Ikeja Electric Prepaid N500",
        "errorResponse": "TRANSACTION FAILED",
        "amountCharged": "0.00",
        "ourRef": "2026100818126ac7cef7739c3"
    },
    "Status": "failed",
    "ident": "2026100818126ac7cef7739c3",
    "balance_before": 17673,
    "discoID": "5",
    "disco_name": "Ikeja Electric Prepaid",
    "balance_after": 17673,
    "api_response": "TRANSACTION FAILED",
    "amount": 500,
    "create_date": "2026-10-08 18:12:23"
}

Educational PINs

Purchase examination result checker PINs.

POST/api/education/

Parameters

Parameter	Description
examType	Either `waec`, `neco`, `utme` or `nabteb`
quantity	The number of examination result checker PINs needed
phone	Phone number of the beneficiary
request-id	Custom user reference ID (optional). Useful when querying transaction status

Sample responses (JSON)

Success
{
    "code": "200",
    "description": {
        "userEmail": "your-email@xyz.com",
        "recipient": "07034567890",
        "narration": "2 NECO PIN(s)",
        "trueResponse": [
            {"pin": "857256XXXXXXXXX", "serial_no": "WR37278XXXXXXXXX"},
            {"pin": "857256XXXXXXXXX", "serial_no": "WR37278XXXXXXXXX"}
        ],
        "amountCharged": "1760.00",
        "ourRef": "2026100812086ac779ad8ce79",
        "userRef": ""
    },
    "Status": "success",
    "ident": "2026100812086ac779ad8ce79",
    "paid_amount": "1760.00",
    "mobile_number": "07034567890",
    "quantity": "2",
    "exam_type": "nabteb",
    "balance_before": 22403,
    "balance_after": 20643,
    "api_response": [
        {"pin": "857256XXXXXXXXX", "serial_no": "WR37278XXXXXXXXX"},
        {"pin": "857256XXXXXXXXX", "serial_no": "WR37278XXXXXXXXX"}
    ],
    "create_date": "2026-10-08 12:08:29"
}

Failure
{
    "code": "424",
    "description": {
        "recipient": "07034567890",
        "narration": "2 NABTEB PIN(s)",
        "trueResponse": "Invalid API Key or You Dont have access to make API Request",
        "amountCharged": "0.00",
        "ourRef": "2026100812086ac779ad8ce79"
    },
    "Status": "failed",
    "ident": "2026100812086ac779ad8ce79",
    "paid_amount": "0.00",
    "mobile_number": "07034567890",
    "quantity": "2",
    "exam_type": "nabteb",
    "balance_before": 20643,
    "balance_after": 20643,
    "api_response": "Invalid API Key or You Dont have access to make API Request",
    "create_date": "2026-10-08 12:08:29"
}

Query Transaction

Check transaction status and other details.

POST/api/query_status/

Parameters

Parameter	Description
request-id	The transaction ref that was passed by user along with the transaction request. (Optional)
ident	The transaction reference we returned in the transaction request response. (Optional)
	Either of the two params must be sent.

Sample responses (JSON)

Success
{
    "code":200,
    "description":{
        "recipient":"1212121212",
        "narration":"GOTV SUPA PLUS @ 16800 (API)",
        "trueResponse":"TRANSACTION SUCCESSFUL",
        "amountCharged":16716,
        "ourRef":"2026100823286ac8190e6164f",
        "userRef":"0259221231523375113850"
    },
    "Status":"success",
    "ident":"2026100823286ac8190e6164f",
    "api_response":"TRANSACTION SUCCESSFUL",
    "amount":"16716.00",
    "create_date":"2026-10-08 23:28:30"
}


Failure
{
    "code":"401",
    "description":{
        "errorResponse":"Ident provided not found"
    },
    "status":"fail",
    "message":"Ident provided not found",
    "error":["Ident provided not found"]
}