How to buy data bundles on Flutterwave

Amongst other things, Flutterwave makes it possible for you to pay bills like Airtime purchase, Cable subscriptions (DSTv, GoTv etc), Data bundles etc. In this tutorial, we will take you through the process of buying data bundles using Flutterwave.

Prerequisites —

To follow along in this tutorial, you need:

A Flutterwave account, create one here
Postman, install it here

Step 1 — Get bill categories

Flutterwave exposes a bill categories endpoint that returns all the bills available on Flutterwave and their respective categories (biller_codes). Calling this endpoint will return the entire list of over 2,000 records. From the response, you can search/filter the list to retrieve the information about the particular bill you are interested in.

To be precise, let's focus our interest on MTN Data bundles for instance. BIL108 is the biller_code for all MTN data bundles. Now if we loop through the response object and filter out all the data with that biller_code, we will get the data below:

{
        "id": 365,
        "biller_code": "BIL108",
        "name": "MTN 200 MB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 200 MB DATA BUNDLE",
        "item_code": "MD142",
        "short_name": "MTN 200 MB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 200
    },
    {
        "id": 366,
        "biller_code": "BIL108",
        "name": "MTN 750MB data top-up service",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 750MB data top-up service",
        "item_code": "MD143",
        "short_name": "MTN 750MB data top-up service",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 500
    },
    {
        "id": 367,
        "biller_code": "BIL108",
        "name": "MTN 1.5 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 1.5 GB DATA BUNDLE",
        "item_code": "MD144",
        "short_name": "MTN 1.5 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 1000
    },
    {
        "id": 368,
        "biller_code": "BIL108",
        "name": "MTN 4.5 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 4.5 GB DATA BUNDLE",
        "item_code": "MD145",
        "short_name": "MTN 4.5 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 2000
    },
    {
        "id": 369,
        "biller_code": "BIL108",
        "name": "MTN 10 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 10 GB DATA BUNDLE",
        "item_code": "MD255",
        "short_name": "MTN 10 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 3500
    },
    {
        "id": 370,
        "biller_code": "BIL108",
        "name": "MTN 15 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 15 GB DATA BUNDLE",
        "item_code": "MD256",
        "short_name": "MTN 15 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 5000
    },
    {
        "id": 371,
        "biller_code": "BIL108",
        "name": "MTN 40 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 40 GB DATA BUNDLE",
        "item_code": "MD257",
        "short_name": "MTN 40 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 10000
    },
    {
        "id": 372,
        "biller_code": "BIL108",
        "name": "MTN 75 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 75 GB DATA BUNDLE",
        "item_code": "MD258",
        "short_name": "MTN 75 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 20000
    },
    {
        "id": 373,
        "biller_code": "BIL108",
        "name": "MTN 120 GB DATA BUNDLE",
        "default_commission": 0.03,
        "date_added": "2020-02-11T11:16:42.727Z",
        "country": "NG",
        "is_airtime": false,
        "biller_name": "MTN 120 GB DATA BUNDLE",
        "item_code": "MD259",
        "short_name": "MTN 120 GB DATA BUNDLE",
        "fee": 0,
        "commission_on_fee": false,
        "label_name": "Mobile Number",
        "amount": 50000
    }

These are all the available MTN Data bundles on Flutterwave. From here, you can decide which of the bundles you want to buy. For the sake of completeness, let's buy the MTN 750MB data top-up service which is the first object in the response above.

Step 2 — Buy bundle

Now that we've retrieved the biller name for the MTN data bundle we want to buy, in this case (MTN 750MB data top-up service), we can go ahead and call the Create bill payment endpoint to buy this bill.

The create bill payment endpoint payload looks like this:

{
        "country": "NG",
        "customer": "+23490803840303",
        "amount": 500,
        "recurrence": "ONCE",
        "type": "MTN 750MB data top-up service",
        "reference": "9300049404444"
    }

According to the payload above, we are trying to buy a one time 750 MB DATA bundle from MTN.

📘
Note that you can always change the type value to suit the data bundle you want to buy. For example, if you want to buy an MTN 1.5 GB data, you can update your request payload to look like this:
{
    "country": "NG",
    "customer": "+23490803840303",
    "amount": 1000,
    "recurrence": "ONCE",
    "type": "MTN 1.5 GB DATA BUNDLE",
    "reference": "930004940442344"
 }
The payload above will buy the 1.5 GB data bundle for you.

Parameter definitions

Parameter	Description	Default
country	This is the country attached to the service being bought e.g. So if you are buying this bundle for a Nigerian MTN line, you would pass `NG` as the value for country	NG
type	This identifies the particular data bundle you want to buy. This is where you pass the `biller_name` from the bill categories data. i.e `MTN 200 MB DATA BUNDLE`. See more here	MTN 1.5 GB DATA BUNDLE
customer	This is the customer identifier. For buying data bundle, the value must be the customer's phone number. Or the phone number you want to fund with the data bundle you are buying.	+23490803840303
amount	This is the amount for the bundle you would like to buy. Every data bundle has an associated `amount` field that tells you the cost for that bill.	1000
recurrence	This determines how often you want to buy this bundle. Possible values: ONCE - I'm buying this bundle just once, for now. HOURLY - Charge me for this bundle every hour. DAILY - I'm buying this bundle every day. WEEKLY - Charge me every week for this bundle. MONTHLY - I'm buying this bundle on a monthly basis. It defaults to ONCE when the value is not provided	ONCE
reference	This is a unique reference passed by the developer to identify transactions on their end	930004940442344

Sample response

When you make the request and it goes successfully, you will get the response below:

{
        "status": "success",
        "message": "Bill payment successful",
        "data": {
            "phone_number": "+2347033950328",
            "amount": 500,
            "network": "MTN 750MB data top-up service",
            "flw_ref": "CF-FLYAPI-20200831020615921000",
            "reference": "BP15988827786255304967"
        }
    }

Conclusion

In this tutorial, we've shown you how to buy MTN data bundles on Flutterwave. The same process applies to any other network e.g (GLO, Airtel etc). The basic understanding is that you need to know the type for every bundle you want to buy. To get the value for type, you need to call the bill categories endpoint and filter the response using the biller codes documented here. That will return only the data associated with a particular network (MTN, GLO, etc).

Next steps, we are working on this endpoint to make it possible for you to pass query parameters to it and return only the data you want. Hence you can filter the endpoint for data bundles alone or for DSTv subscriptions. This feature will be available in a few weeks.