Airtime and Bill Purchase

Overview

This guide will help you get set up in making purchases and payments for airtime, data and utilities.

Currently, you can make airtime and data purchase for the following telecommunication services providers in Nigeria

MTN
Airtel
Glo
9Mobile

Payments for utilities can be done for the following services

Cable services
Electricity

For cable services. You can pay for the following services providers

GoTV subscriptions
DSTV subscriptions

For electricity services. The following distribution companies are supported

AEDC (Abuja Electricity Distribution Company)
Ikeja Electric
Eko Disco
JED (Jos Electricity Distribution company)
Kaduna Electricity Distribution company
KEDCO (Kano Electricity Distribution Company)
Ibadan Disco
Enugu Electric
Port Harcourt Electric

Using The API

🚧
Compliance Check
For live transactions ensure that you have an approved compliance for your business before using the API. Businesses without compliance submitted will get a "compliance not approved" error message.

To make actual purchase on the airtime and bills API, you will need to make a PUT request to this endpoint

https://api-sandbox.gladefinance.co/bills

Steps in consuming the API

The following options will guide you towards consuming the bills API.

Pull the list of bills

To pull the list of bills you'll need to pass an action with value "pull" to request body.

{
    "action": "pull"
}

The Response

{
  "data": {
    "categories": [
      {
        "name": "Airtime",
        "code": "airtime"
      },
      {
        "name": "Electricity Tokens",
        "code": "electricity"
      },
      {
        "name": "Internet Services",
        "code": "internet"
      }
    ],
    "bills": [
      {
        "id": 1,
        "name": "MTN Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 3,
        "name": "Glo Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 4,
        "name": "9Mobile Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 5,
        "name": "Airtel Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 6,
        "name": "AEDC",
        "reference": "Meter Number",
        "category": "electricity"
      }
    ],
    "items": [
      {
        "name": "TopUp",
        "bills_id": 1,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "cHwBhPniYesycir",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 3,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "6rHQCyP0252mg0J",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 4,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "jhMIV5j3K8SmPAy",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 5,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "Alhdu86riyoyHg0",
        "require_name_query": 0
      },
      {
        "name": "AEDC Prepaid",
        "bills_id": 6,
        "amount": "0",
        "discount": 0,
        "fee": 70,
        "paycode": "lAApm6OBmRmp3cQ",
        "require_name_query": 1
      }
    ]
  }
}

The categories contains the list of services (airtime, bills e.t.c) that are being supported by the API.

Every category has a list of bills belonging to billers (services providers). Example of billers are MTN or Airtel for airtime category.

Bills have items e.g Topup for MTN. Items are associated with bills using the bill_id.

Filter bills by category

Get the list of bills in a category. Adding a category to the request payload will fetch the the various items for that categories.

The Request

A sample request for the Airtime category is given below.

{
  "action": "pull",
  "category": "airtime"
}

The Response

{
    "data": {
        "categories": [
            {
                "name": "Airtime",
                "code": "airtime"
            }
        ],
        "bills": [
            {
                "id": 1,
                "name": "MTN Prepaid Topup",
                "reference": "Phone Number",
                "category": "airtime"
            },
            {
                "id": 2,
                "name": "Glo Prepaid Topup",
                "reference": "Phone Number",
                "category": "airtime"
            },
            {
                "id": 3,
                "name": "9Mobile Prepaid Topup",
                "reference": "Phone Number",
                "category": "airtime"
            },
            {
                "id": 4,
                "name": "Airtel Prepaid Topup",
                "reference": "Phone Number",
                "category": "airtime"
            }
        ],
        "items": [
            {
                "name": "TopUp",
                "bills_id": 1,
                "amount": "0.00",
                "paycode": "cHwBhPniYesycir",
                "require_name_query": 0
            },
            {
                "name": "TopUp",
                "bills_id": 2,
                "amount": "0.00",
                "paycode": "6rHQCyP0252mg0J",
                "require_name_query": 0
            },
            {
                "name": "TopUp",
                "bills_id": 3,
                "amount": "0.00",
                "paycode": "jhMIV5j3K8SmPAy",
                "require_name_query": 0
            },
            {
                "name": "TopUp",
                "bills_id": 4,
                "amount": "0.00",
                "paycode": "Alhdu86riyoyHg0",
                "require_name_query": 0
            }
        ]
    }
}

Filter bills by Bill ID

You can also filter bills using their bill_ids.

A sample Request is shown below

{
  "action": "pull",
  "bills_id": 6
}

The response is still the same format as that of filtering by category.

Bill Resolution

For certain bill payments, such as electricity and some subscription-based services, you might need to confirm the details (resolve the bill).

For example, resolving a meter number to be sure that it matches the meter that you want to pay for.

To resolve a bill you would need to pass in the reference. This reference would be the meter number for an electricity payment or the smart card number for a decoder payment or any unique ID that is being used for that service.

The action for bill resolution is resolve.
The paycode is gotten from the list of items being pulled.

Request

{
    "action": "resolve",
    "paycode": "lAApm6OBmRmp3cQ",
    "reference": "0000000001"
}

Response

{
    "status": 200,
    "message": "Resolved",
    "custName": "Sten Mockett"
}

Making Airtime and Bill Payments

To make bills payment pass the paycode and reference that is required by the biller. The reference will be the SmartCard Number, Meter Number or phone number for airtime purchase etc

paycode must be retrieved from the items list when you retrieved the list of available bills.

The action for this request is pay.

🚧
Note
Paycode of bills could change pull the updated list of bills at least once a day.

Request

{
    "action": "pay",
    "paycode": "lAApm6OBmRmp3cQ",
    "reference": "08123456789",
    "amount": "100",
    "orderRef": "xxcd"
}

Response

{
    "txnRef": "G|BL|2022021617P620d0ee8e5647331811981",
    "bill_item_id": 1,
    "bill_id": 1,
    "category": "airtime",
    "bill_reference": "08123456789",
    "amount_charged": "100.00",
    "fee_charged": "0.00",
    "status": "successful",
    "remark": "Payment for TopUp - G|BL|2022021617P620d0ee8e5647331811981 successful",
    "created_at": "2022-02-16 14:49:14",
}

Verify Bills Payment

After payment is made you might want to verify the status of a transaction. To verify the status of a transaction use txnRef gotten from the payment response.

Request

{
    "action": "verify",
    "txnRef": "GP|BP|987555815|20190115N"
}