Bills & Utilities

Our API allows you to automate utility payments for Airtime, Data, Cable TV, and Electricity.

Pricing & Service IDs

Use the /bills/pricing-data and /bills/pricing-cable endpoints to get live rates and the required service_id for each plan.

1. Get Pricing

GET/bills/pricing-airtime

GET/bills/pricing-data

GET/bills/pricing-cable

2. Airtime

POST/bills/airtime

Request Body:

{
                                "network": "mtn",
                                "phone": "08012345678",
                                "amount": 200
                            }

Sample Response:

{
                                "status": "success",
                                "message": "Airtime purchase successful",
                                "data": {
                                    "reference": "176988729834406",
                                    "amount": 200.00,
                                    "recipient": "08012345678",
                                    "service": "airtime",
                                    "network": "mtn",
                                    "balance_before": 5000.00,
                                    "balance_after": 4800.00,
                                    "date": "31-01-2026 20:25:15"
                                }
                            }

3. Data

POST/bills/data

Request Body:

{
                                "network": "mtn",
                                "phone": "08012345678",
                                "service_id": "mtn-sme-1gb"
                            }

Sample Response:

{
                                "status": "success",
                                "message": "Data purchase successful",
                                "data": {
                                    "reference": "FV-DATA-98723",
                                    "amount": 250.00,
                                    "recipient": "08012345678",
                                    "service": "data",
                                    "network": "mtn",
                                    "service_id": "mtn-sme-1gb",
                                    "balance_before": 4800.00,
                                    "balance_after": 4550.00,
                                    "date": "31-01-2026 20:26:10"
                                }
                            }

4. Cable TV

Step 1: Verify Smart Card

POST/bills/verify-cable

{
                                "cable": "gotv",
                                "smart_card_number": "1234567890"
                            }

Sample Response:

{
                            "status": "success",
                            "message": "Validation successful",
                            "customer_name": "JAMES AKOR"
                        }

Step 2: Pay for Plan

POST/bills/pay-cable

{
                                "cable": "gotv",
                                "iucNum": "1234567890",
                                "service_id": "gotv-plus"
                            }

5. Electricity

Step 1: Verify Meter

POST/bills/verify-electricity

{
                                "service_id": "ikeja-electric",
                                "meterno": "12345678901",
                                "meterType": "prepaid",
                                "amount": 2000
                            }

Sample Response:

{
                            "status": "success",
                            "message": "Validation successful",
                            "customer_name": "JOHN DOE",
                            "customer_address": "123 IKEJA ST, LAGOS"
                        }

Step 2: Pay for Electricity

POST/bills/pay-electricity

{
                                "service_id": "ikeja-electric",
                                "companyName": "Ikeja Electric",
                                "meterno": "12345678901",
                                "meterType": "prepaid",
                                "amount": 2000
                            }

Sample Response:

{
                            "status": "success",
                            "message": "Electric payment successful",
                            "data": {
                                "reference": "FV-ELEC-98723",
                                "amount": 2000.0,
                                "recipient": "12345678901",
                                "service": "electricity",
                                "provider": "Ikeja Electric",
                                "meter_type": "prepaid",
                                "token": "1234-5678-9012-3456-7890",
                                "customer_name": "ABAYOMI ADESHINA",
                                "balance_before": 4550.0,
                                "balance_after": 2550.0,
                                "date": "31-01-2026 21:18:20"
                            }
                        }

6. Education (WAEC/NECO Pins)

Step 1: Get Education Pricing

GET/bills/pricing-education

Sample Response:

{
                            "status": "success",
                            "data": [
                                {
                                    "type": "waec",
                                    "service_id": "waec-direct",
                                    "amount": 3500
                                }
                            ]
                        }

Step 2: Purchase Pins

POST/bills/education

{
                                "service_id": "waec-direct",
                                "quantity": 1
                            }

Sample Response:

{
                            "status": "success",
                            "message": "E-pin purchase successful",
                            "data": {
                                "reference": "FV-EDU-7762",
                                "amount": 3500,
                                "pins": "PIN: 1234567890, S/N: SN987654321",
                                "service": "education",
                                "type": "waec",
                                "quantity": 1,
                                "balance_before": 25500.0,
                                "balance_after": 22000.0,
                                "date": "31-01-2026 21:25:40"
                            }
                        }