SUBZID API Documentation

Content

Introduction
Authentication
Requests
Responses
Fetch Balance
Buy Airtime
Fetch Data Bundles
Buy Data
Fetch Cable TV Bouquets
Verify Cable TV Customer Info
Cable TV Payment
Verify Electricity Meter Info
Electricity Bill Payment
Educational PINs
KYC Slips

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.

Authentication

API Token

You are to pass your API token via the header 'Authorization' key for every request sent to our server. The value should be in the format "Token your-token" (where your-token is your API token).

Basic Authentication (Only applicable to data bundles fetch & purchase)

Phone Number or Email (as username) & password can be passed as a concatenated string into the header 'Authentication' key using base64 encode like this "Basic ".base64_encode('username:password')

Credentials Security

We advise that you keep your API token and account login credentials as secret as possible. If you suspect that your API token or account login credentials have been compromised, login to your account, change your password oand generate another API token as fast as possibe to render the former token and password invalid.

API Request

URL: They are stated in the latter part of this documentation

Method: POST

Header: It contains the 'Content-Type' (content format our server accepts), 'Accept' (format of response our server pushes back) and 'Authorization' key (Token your-api-token).

Body/Content: The request body must be in json format. The fields/parameters are stated in the latter part of this documentation. All parameters are compulsory except stated otherwise.

Sample Request Code (PHP)

                
                
        <?php

            $postRequest = array(
                  'parameter1' => 'value1',
                  'parameter' => 'value1');
        
            $xpostRequest=json_encode($postRequest);
            
            $url= 'url-stated-in-each-service-below';
            $cURLConnection = curl_init($url);
            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 ranging from 200s-400s (2** to 4**). More details of response returned are included in the 'description' key. Below are the various codes you are likely to recieve and what they mean.

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 delivered or it could still deliver

It is safer to mark requests that return error codes outside 2** and 4** clearly defined above as pending!

Fetch Balance

This is used to fetch user wallet balance. Works for Msorg, Adex & Vicoms websites

URL: https://subzid.com/api/user/

Parameters:

Parameter	Description
none	none

Sample Responses (JSON)

                
    Success

    {
        "code":"200",
        "description": {
            "balance":"373,500.0",
        }
        "Status":"successful",
        "status":"success",
        "balance":"373,500.0",
        "wallet":"373,500.0",
        "user": {
            "wallet_balance":"373,500.0",
            "wallet":"373,500.0"
        }
    }

    Failure

    {
        "code":"403",
        "description": {
            "errorResponse":"Authorization not set",
        }
        "status":"fail",
        "message":"Authorization not set",
        "error":{
            "Authorization not set"
        }
    }

Buy Airtime

This is used to purchase airtime for all networks.

URL: https://subzid.com/api/airtime

Parameters:

Parameter	Description
networkId	The ID of the network to recharge from. It can be either '1' for MTN, '2' for Airtel, '3' for Glo or '4' for 9mobile
type	Type of airtime recharge. It has the value 'VTU'
phone	Beneficiary phone number
amount	Amount of airtime to be purchased. A minimum of N50
ref	Custom user reference ID (optional)

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":"",
        },
        "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":""
        },
        "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 Bundles

This returns all data bundles currently available.

URL: https://subzid.com/api/data/fetch_all_data_bundles

Parameters:

Parameter	Description
networkId	The ID of the network whose bundles are to be fetched. It can be either '1' for MTN, '2' for Glo, '3' for 9mobile or '4' for Airtel (Optional)
data_type	SME, CG, AWOOF or GIFTING (Optional)

Sample Responses (JSON)

                
    Success

    {
        "code": "200",
        "Status": "success",
        "bundles": [
            {
                "Network Name": "MTN",
                "Plan Type": "DIRECT-GIFTING",
                "Plan Name": "75 MB Daily Plan@75 valid for 1 day",
                "Plan ID": "52",
                "Network Price": "75.00"
            },
            {
                "Network Name": "MTN",
                "Plan Type": "DIRECT-GIFTING",
                "Plan Name": "110 MB Daily Plan@100 valid for 1 day",
                "Plan ID": "53",
                "Network Price": "100.00"
            },
            {
                "Network Name": "MTN",
                "Plan Type": "DIRECT-GIFTING",
                "Plan Name": "200MB Social Daily Plan@100 valid for 1 day",
                "Plan ID": "54",
                "Network Price": "100.00"
            },
            {
                "Network Name": "MTN",
                "Plan Type": "DIRECT-GIFTING",
                "Plan Name": "230 MB Daily Plan@200 valid for 1 day",
                "Plan ID": "55",
                "Network Price": "200.00"
            },
            {
                "Network Name": "MTN",
                "Plan Type": "DIRECT-GIFTING",
                "Plan Name": "500MB Daily Plan@350 valid for 1 day",
                "Plan ID": "56",
                "Network Price": "350.00"
            }
        ]
    }

    Failure

    {
        "code":"424",
        "Status":"success",
        "bundles":"No bundles found"
    }

Buy Data

(Adapted for MSORG, ADEX & VICOM)

This is used to purchase data bundles for all networks. For Msorg, Adex & Vicom, please use their respective authentication modes, parameters and responses as preconfigured on your website admin area.

URL: https://subzid.com/api/data/

Parameters:

Parameter	Description
network	The ID of the network to recharge from. For MSORG, MTN= 1, Glo= 2, 9mobile= 3 & Airtel= 4 For Adex & Vicom, MTN= 1, Airtel= 2, Glo= 3 & 9mobile= 4
plan data_plan (ADEX & VICOM)	This is the plan ID of the data bundle to be purchased. Please click PLAN/BOUQUET IDs/DISCOs for the IDs
mobile_number phone (ADEX & VICOM)	Beneficiary phone number
ref request-id (ADEX & VICOM)	Custom user reference ID (optional)

Sample Responses (JSON)

                
    Success

    {
        "code":"200",
        "description": {
            "recipient":"07033333333",
            "narration":"MTN SME Data 1GB",
            "trueResponse":"You have successfully gifted 2347033333333 with 1GB of Data. valid till 20/07/2024 12:00:00 PM",
            "amountCharged":"500.00",
            "ourRef":"202606200837823726ae834d34d"
        },
        "Status":"successful",
        "ident":"202606200837823726ae834d34d",
        "network":"1",
        "balance_before":"5532.00",
        "plan_type":"SME",
        "balance_after":"5032.00",
        "mobile_number":"07033333333",
        "plan":"7",
        "api_response":"You have successfully gifted 2347033333333 with 1GB of Data. valid till 20/07/2026 12:00:00 PM",
        "plan_network":"MTN",
        "plan_name":"1GB",
        "plan_amount":"500.00",
        "create_date":"2026-06-20 08:37:14"
    }

    Processing

    {
        "code":"501",
        "description": {
            "recipient":"07033333333",
            "narration":"MTN SME Data 1GB",
            "trueResponse":"Your request is currently being processed. Please do not retry!",
            "amountCharged":"500.00",
            "ourRef":"202606200837823726ae834d34d"
        },
        "Status":"processing",
        "ident":"202606200837823726ae834d34d",
        "network":"1",
        "balance_before":"5532.00",
        "plan_type":"SME",
        "balance_after":"5032.00",
        "mobile_number":"07033333333",
        "plan":"7",
        "api_response":"Your request is currently being processed. Please do not retry!",
        "plan_network":"MTN",
        "plan_name":"1GB",
        "plan_amount":"500.00",
        "create_date":"2026-06-20 08:37:14"
    }

    Failure

    {
        "code":"424",
        "description": {
            "recipient":"07033333333",
            "narration":"MTN SME Data 1GB",
            "errorResponse":"Invalid phone number",
            "amountCharged":"0.00",
            "ourRef":"202606200837823726ae834d34d",
        },
        "Status":"failed",
        "ident":"202606200837823726ae834d34d",
        "network":"1",
        "balance_before":"5532.00",
        "plan_type":"SME",
        "balance_after":"5532.00",
        "mobile_number":"07033333333",
        "plan":"7",
        "api_response":"Invalid phone number",
        "plan_network":"MTN",
        "plan_name":"1GB",
        "plan_amount":"500.00",
        "create_date":"2026-06-20 08:37:14"
    }


    OR

    {
        "code":"403",
        "description": {
            "errorResponse":"User account disabled. Please contact support"
        },
        "error":"User account disabled. Please contact support"
    }

Fetch Cable TV Bouquets

This returns all bouquets currently available for the cableType. You can also refer to PLAN/BOUQUET IDs/DISCOs

URL: https://subzid.com/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

This is used to ensure that payment is about to be made to the correct Cable TV customer.

URL: https://subzid.com/api/verify_cable_tv_customer

Parameters:

Parameter	Description
cableType	Either 'DSTV', 'GOTV' or 'STARTIMES'
smartcardNo	The smartcard or IUC number of the customer's decoder

Sample Responses (JSON)

                
    Success

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

    Failure

    {
        "code":"424",
        "description": {
            "errorResponse":"Verification failed"
        }
    }

Cable TV Payment

This is used pay for cable tv subscriptions.

URL: https://subzid.com/api/cabletv

Parameters:

Parameter	Description
cableType	Either 'DSTV', 'GOTV' or 'STARTIMES'
bouquetId	This is the bouquet being paid for. All the bouquets have fixed amounts.
smartcardNo	The smartcard or IUC number of the customer's decoder
amount	Amount to be credited to the decoder account (leave empty if bouquet selected is not 'Topup')
ref	Custom user reference ID (optional)

Sample Responses (JSON)

                
    Success

    {
        "code":"200",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"7031xxxxxx",
            "narration":"DSTV Yanga @ 5000",
            "trueResponse":"Payment successful",
            "amountCharged":"4950.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":"",
        },
        "time":"2024-07-17 15:22:42"
    }

    Failure

    {
        "code":"424",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"07033333333",
            "narration":"DSTV Yanga @ 5000",
            "errorResponse":"Payment failed",
            "amountCharged":"4900.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":""
        },
        "time":"2024-07-17 15:22:42"
    }

Verify Electricity Meter Info

This is used to ensure that payment is about to be made to the correct customer.

URL: https://subzid.com/api/verify_electricity_meterno

Parameters:

Parameter	Description
discoId	For Disco IDs, please refer to PLAN/BOUQUET IDs/DISCOs
meterNo	This is 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": {
            "errorResponse":"Verification failed"
        }
    }

Electricity Bill Payment

This is used to make payments for electricity.

URL: https://subzid.com/api/electricity

Parameters:

Parameter	Description
discoId	For Disco types and their IDs, please refer to PLAN/BOUQUET IDs/DISCOs
meterNo	This is the electricity account number attached to the customer's postpaid or prepaid meter.
amount	Amount to be credited to the meter account
ref	Custom user reference ID (optional)

Sample Responses (JSON)

                
    Success (Store all data in trueResponse key)

    {
        "code":"200",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"3122XXXXXX",
            "narration":"ENUGU ELECTRIC PREPAID N5000",
            "trueResponse": {
                "meterNo":"3122XXXXXX",
                "customerNumber":"25113291196"
                "customerName":"Testmeter1",
                "token":"82376716826361231"
                },
            "amountCharged":"5000.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":"",
        },
        "time":"2024-07-17 15:22:42"
    }

    Failure

    {
        "code":"424",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"3122XXXXXX",
            "narration":"EEDC PREPAID N5000",
            "errorResponse":"TRANSACTION FAILED",
            "amountCharged":"5000.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":""
        },
        "time":"2024-07-17 15:22:42"
    }

Educational PINs

This is used to purchase examination result checker PINs.

URL: https://subzid.com/api/educational-pins

Parameters:

Parameter	Description
examType	This can be either 'waec_pin', 'neco_pin', 'utme_pin' or 'nabteb_pin'
quantity	The number of examination result checker PINs needed.
phone	Phone number of the beneficiary
ref	Custom user reference ID (optional)

Sample Responses (JSON)

                
    Success

    {
        "code":"200",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"07035XXXXXX",
            "narration":"3 NECO PIN(s)",
            "trueResponse": [
                {"pin":"857256XXXXXXXXX","serial_no":"WR37278XXXXXXXXX"},
                {"pin":"857256XXXXXXXXX","serial_no":"WR37278XXXXXXXXX"}
                ],
            "amountCharged":"2400.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":"",
        },
        "time":"2024-07-17 15:22:42"
    }

    Failure

    {
        "code":"424",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"07035XXXXXX",
            "narration":"3 NECO PIN(s)",
            "errorResponse":"Payment failed",
            "amountCharged":"2400.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":""
        },
        "time":"2024-07-17 15:22:42"
    }

KYC (BVN & NIN) Slips

This is used to generate BVN & NIN slips (PNG/JPG) returned in base64 formats. You are expected to convert the 'base64' value to image.

URL: https://subzid.com/api/kyc-slip

All parameters descriptions:

Parameter	Description
idType	It can either be 'nin' or 'bvn'
slipType	The type of slip you wish to generate. * For NIN, it can either be 'nin long slip', 'nin basic slip', 'nin premium slip' or 'nin improved slip'. * For BVN, it can either be 'bvn slip', 'bvn slip 2' or 'bvn card'
searchCriteria	* For NIN, the value can either be 'nin', 'phone' or 'demographics'. * For BVN, the value can only be 'bvn'.
nin	NIN number to be queried. This is only applicable to NIN slips generation using 'nin' as searchCriteria
bvn	BVN numbr to be queried. This is only applicable to BVN slips generation using 'bvn' as searchCriteria.
phone	Phone number attached to NIN to be queried. This is only applicable to NIN slips generation using 'nin' as searchCriteria
surName	Surname on the NIN to be queried. This is only applicable to NIN slips generation using 'demographics' as searchCriteria.
firstName	First name on the NIN to be queried. This is only applicable to NIN slips generation using 'demographics' as searchCriteria.
gender	Gender on the NIN to be queried. It can either be 'male' or 'female'. This is only applicable to NIN slips generation using 'demographics' as searchCriteria.
dateOfBirth	Date of birth on the NIN to be queried. This is only applicable to NIN slips generation using 'demographics' as searchCriteria.
ref	Custom user reference ID (optional)

Params required for each searchCriteria:

idType	searchCriteria	Required Params
nin	nin	idType, searchCriteria, slipType, nin, ref (optional)
nin	phone	idType, searchCriteria, slipType, phone, ref (optional)
nin	demographics	idType, searchCriteria, slipType, surName, firstName, dateOfBirth, gender, ref (optional)
bvn	bvn	idType, searchCriteria, slipType, bvn, ref (optional)

Sample Responses (JSON)

                
    Success

    {
        "code":"200",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"07035XXXXXX",
            "narration":"Nin Basic Slip",
            "trueResponse": "Slip generated successfully!",
            "base64": "iVBORw0KGgoAAAANSUhEUgAACWwAAAQMCAIAAACH8............",
            "amountCharged":"1000.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":"",
        },
        "time":"2024-07-17 15:22:42"
    }

    Failure

    {
        "code":"424",
        "description": {
            "userEmail":"your-email@xyz.com",
            "recipient":"07035XXXXXX",
            "narration":"Nin Basic Slip",
            "errorResponse":"valid 11 digit nin is required for search by nin",
            "amountCharged":"0.00",
            "ourRef":"202407171522426934ae834d34d",
            "userRef":"0231009712021012"
        },
        "time":"2024-07-17 15:22:42"
    }