Bills Payments

Pay for Airtime, Data subscription, Electricity and other supported bills. Check here for a step-wise guide to bill payments.

Get supported bill categories

Query supported bill categories by country.

get https://api.flutterwave.com/v3/top-bill-categories

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/top-bill-categories?country=NG' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
    "status": "success",
    "message": "Categories fetched successfully",
    "data": [
        {
            "id": 1,
            "name": "Airtime",
            "code": "AIRTIME",
            "description": "Airtime",
            "country_code": "NG"
        },
        {
            "id": 2,
            "name": "Mobile Data Service",
            "code": "MOBILEDATA",
            "description": "Mobile Data Service",
            "country_code": "NG"
        },
        {
            "id": 3,
            "name": "Cable Bill Payment",
            "code": "CABLEBILLS",
            "description": "Cable Bill Payment",
            "country_code": "NG"
        },
        {
            "id": 4,
            "name": "Internet Service",
            "code": "INTSERVICE",
            "description": "Internet Service",
            "country_code": "NG"
        },
        {
            "id": 5,
            "name": "Utility Bills",
            "code": "UTILITYBILLS",
            "description": "Utility Bills",
            "country_code": "NG"
        },
        {
            "id": 6,
            "name": "Tax Payment",
            "code": "TAX",
            "description": "Tax Payment",
            "country_code": "NG"
        },
        {
            "id": 7,
            "name": "Donations",
            "code": "DONATIONS",
            "description": "Donations",
            "country_code": "NG"
        },
        {
            "id": 8,
            "name": "Transport and Logistics",
            "code": "TRANSLOG",
            "description": "Transport and Logistics",
            "country_code": "NG"
        },
        {
            "id": 9,
            "name": "Dealer Payments",
            "code": "DEALPAY",
            "description": "Dealer Payments",
            "country_code": "NG"
        },
        {
            "id": 10,
            "name": "Airtime",
            "code": "AIRTIME",
            "description": "Airtime",
            "country_code": "GH"
        },
        {
            "id": 11,
            "name": "Mobile Money",
            "code": "MOBILEMONEY",
            "description": "Mobile Money",
            "country_code": "GH"
        },
        {
            "id": 12,
            "name": "Airtime",
            "code": "AIRTIME",
            "description": "Airtime",
            "country_code": "KE"
        },
        {
            "id": 13,
            "name": "Cable Bill Payment",
            "code": "CABLEBILLS",
            "description": "Cable Bill Payment",
            "country_code": "KE"
        },
        {
            "id": 14,
            "name": "Utility Bills",
            "code": "UTILITYBILLS",
            "description": "Utility Bills",
            "country_code": "KE"
        },
        {
            "id": 15,
            "name": "Mobile Money",
            "code": "MOBILEMONEY",
            "description": "Mobile Money",
            "country_code": "ZM"
        },
        {
            "id": 16,
            "name": "Airtime",
            "code": "Airtime",
            "description": "Airtime",
            "country_code": "ZM"
        },
        {
            "id": 17,
            "name": "Religious Institutions",
            "code": "RELINST",
            "description": "Religious Institutions",
            "country_code": "NG"
        },
        {
            "id": 18,
            "name": "Schools & Professional Bodies",
            "code": "SCHPB",
            "description": "Schools & Professional Bodies",
            "country_code": "NG"
        }
    ]
}
{
    "status": "error",
    "message": "Country not supported at this time",
    "data": null
}

Get biller information

Query supported billers by country.

get https://api.flutterwave.com/v3/bills/:category/billers

Path Params

category string

The bill category code.

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/bills/CABLEBILLS/billers?country=NG' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
    "status": "success",
    "message": "Billers fetched successfully",
    "data": [
        {
            "id": 66,
            "name": "DSTV",
            "logo": null,
            "description": "DSTV",
            "short_name": "DSTV",
            "biller_code": "BIL119",
            "country_code": "NG"
        },
        {
            "id": 67,
            "name": "GOTV",
            "logo": null,
            "description": "GOTV",
            "short_name": "GOTV",
            "biller_code": "BIL120",
            "country_code": "NG"
        },
        {
            "id": 68,
            "name": "DAARSAT Communications",
            "logo": null,
            "description": "DAARSAT Communications",
            "short_name": "DAARSAT Communications",
            "biller_code": "BIL123",
            "country_code": "NG"
        },
        {
            "id": 69,
            "name": "DSTV BOX OFFICE",
            "logo": null,
            "description": "DSTV BOX OFFICE",
            "short_name": "DSTV BOX OFFICE",
            "biller_code": "BIL125",
            "country_code": "NG"
        },
        {
            "id": 70,
            "name": "MyTV",
            "logo": null,
            "description": "MyTV",
            "short_name": "MyTV",
            "biller_code": "BIL128",
            "country_code": "NG"
        },
        {
            "id": 71,
            "name": "HiTV",
            "logo": null,
            "description": "HiTV",
            "short_name": "HiTV",
            "biller_code": "BIL129",
            "country_code": "NG"
        },
        {
            "id": 91,
            "name": "STARTIMES",
            "logo": null,
            "description": "STARTIMES",
            "short_name": "STARTIMES",
            "biller_code": "BIL123",
            "country_code": "NG"
        }
    ]
}
{
    "status": "error",
    "message": "Invalid category code",
    "data": null
}

Get bill information

Retrieve bill details provided by billers.

get https://api.flutterwave.com/v3/billers/:biller_code/items

Path Params

biller_code string

The unique identifier for the biller. This is returned as data[i].biller_code in the get billers response.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/billers/BIL119/items' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
    "status": "success",
    "message": "Bill items fetched successfully",
    "data": [
        {
            "id": 34,
            "biller_code": "BIL119",
            "name": "DSTV Payment",
            "default_commission": 0.1,
            "date_added": "2020-09-17T15:56:58.057Z",
            "country": "NG",
            "is_airtime": false,
            "biller_name": "DSTV Payment",
            "item_code": "CB140",
            "short_name": "DSTV Premium",
            "fee": 100,
            "commission_on_fee": true,
            "reg_expression": "^[0-9]+$",
            "label_name": "SmartCard Number",
            "amount": 14600,
            "is_resolvable": true,
            "group_name": "DSTV",
            "category_name": "Cable Bill Payment",
            "is_data": null,
            "default_commission_on_amount": null,
            "commission_on_fee_or_amount": null,
            "validity_period": null
        },
        {
            "id": 35,
            "biller_code": "BIL119",
            "name": "DSTV",
            "default_commission": 0.1,
            "date_added": "2020-09-17T15:56:58.057Z",
            "country": "NG",
            "is_airtime": false,
            "biller_name": "DSTV Access",
            "item_code": "CB141",
            "short_name": "DSTV Access",
            "fee": 100,
            "commission_on_fee": true,
            "reg_expression": "^[0-9]+$",
            "label_name": "SmartCard Number",
            "amount": 1800,
            "is_resolvable": true,
            "group_name": "DSTV",
            "category_name": "Cable Bill Payment",
            "is_data": null,
            "default_commission_on_amount": null,
            "commission_on_fee_or_amount": null,
            "validity_period": null
        },
        {
            "id": 91,
            "biller_code": "BIL119",
            "name": "DSTV",
            "default_commission": 0.1,
            "date_added": "2020-09-17T15:56:58.057Z",
            "country": "NG",
            "is_airtime": false,
            "biller_name": "DSTV Premium",
            "item_code": "CB140",
            "short_name": "DSTV",
            "fee": 100,
            "commission_on_fee": true,
            "reg_expression": "^[0-9]+$",
            "label_name": "SmartCard Number",
            "amount": 14600,
            "is_resolvable": true,
            "group_name": "Cable Bill Payment",
            "category_name": "Cable Bill Payment",
            "is_data": null,
            "default_commission_on_amount": null,
            "commission_on_fee_or_amount": null,
            "validity_period": null
        }
    ]
}
{
    "status": "error",
    "message": "Invalid Biller code",
    "data": null
}

Validate customer details

Validate your customer's information. Supported input include: meter number, smartcard number, internet account number, etc.

get https://api.flutterwave.com/v3/bill-items/:item_code/validate

Path Params

item_code string

The bill item code returned in the get bills response as data[i].item_code.

Query Params

code string

The biller code returned in the get biller response as data[i].biller_code.

customer string

The customer identifier for the bill payment.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/bill-items/CB141/validate?code=BIL119&customer=0025401100' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
  "status": "success",
  "message": "Item validated successfully",
  "data": {
      "response_code": "00",
      "address": null,
      "response_message": "Successful",
      "name": "Test DSTV Account",
      "biller_code": "BIL119",
      "customer": "0025401100",
      "product_code": "CB141",
      "email": null,
      "fee": 0,
      "maximum": 0,
      "minimum": 0
  }
}
{
    "status": "error",
    "data": null
}

Create bill payments

Initiate your bill payments.

post https://api.flutterwave.com/v3/billers/:biller_code/items/:item_code/payment

Path Params

item_code string

The bill item code returned in the get bills response as data[i].item_code.

biller_code string

The biller code returned in the get biller response as data[i].biller_code.

Body Params

country string

The Biller country. Expected values include: NG, GH, KE and ZM.

customer_id string

The customer identifier for the bill payment.

amount int32

The bill amount.

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

{
  "country": "NG",
  "customer_id": "0025401100",
  "reference": "d7a004b1-a581-4cd9-89ae-a1f0934",
  "amount": 1800.0,
  "callback_url": "https://webhook.site/#!/view/df95cc29-1556-4e39-85ff-180fae09f3e8"
}
{
  "status": "success",
  "message": "Bill payment successful",
  "data": {
      "phone_number": "0025401100",
      "amount": 1800,
      "network": "DSTV Access",
      "code": "200",
      "tx_ref": "CF-FLYAPI-20240311124623867907",
      "reference": "247891569224",
      "batch_reference": null,
      "recharge_token": null,
      "fee": 100
  }
}
{
  "status": "error",
  "message": "Amount must be 1900.0",
  "data": null
}
{
  "status": "error",
  "message": "Duplicate transaction reference",
  "data": null
}
{
  "status": "error",
  "message": "amount is required",
  "data": null
}

Create bulk bill payments

This document shows you how to create bulk bills payment

post https://api.flutterwave.com/v3/bulk-bills

Body Params

bulk_reference string

The merchant's unique identifier for the bulk payment.

callback_url string

Merchant-specific URL for bill payment callbacks.

bulk_data array of objects

An array containing details on each individual request in the batch.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

{
   "bulk_reference":"edf-12de5223d2f32",
   "callback_url":"https://webhook.site/5f9a659a-11a2-4925-89cf-8a59ea6a019a",
   "bulk_data":[
      {
         "country":"NG",
         "customer":"+23490803840303",
         "amount":500,
         "recurrence":"WEEKLY",
         "type":"AIRTIME",
         "reference":"930049200929"
      },
      {
         "country":"NG",
         "customer":"+23490803840304",
         "amount":500,
         "recurrence":"WEEKLY",
         "type":"AIRTIME",
         "reference":"930004912332"
      }
   ]
}
{
  "status": "success",
  "message": "Bulk bill Payment was queued for processing",
  "data": {
    "batch_reference": "CF-BATCH-FLY-API-20200310042210201008"
  }
}
{}

Get a payment's status

This document shows you how to get the status of a bill purchase.

get https://api.flutterwave.com/v3/bills/:reference

Path Params

reference string

The merchant's unique identifier for the payment.

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/bills/CF-FLYAPI-20240308035516465263?verbose=1' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
  "status": "success",
  "message": "Bill status fetch successful",
  "data": {
      "currency": "NGN",
      "customer_id": "07065657658",
      "frequency": "One Time",
      "amount": "11.0000",
      "fee": 0,
      "product": "AIRTIME",
      "product_name": null,
      "commission": 0,
      "transaction_date": "2024-03-08T15:55:16.963Z",
      "customer_reference": "d7a004b1-a581-4cd9-89ae-a1ff89c45c9a",
      "country": "NG",
      "flw_ref": "BPUSSD1709913319189093",
      "tx_ref": "CF-FLYAPI-20240308035516465263",
      "batch_id": 3387836,
      "extra": null,
      "product_details": "FLY-API-NG-AIRTIME",
      "status": "successful",
      "code": "200"
  }
}
{
  "status": "error",
  "message": "Transaction not found",
  "data": null
}

Get bill payments summary

Fetch summary report for bill payment.

get https://api.flutterwave.com/v3/bills/summary

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/bills/summary?from=2024-03-01&to=2024-03-11' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
    "status": "success",
    "message": "Bill summary fetched successfully",
    "data": [
        {
            "currency": "NGN",
            "sum_bills": 2037,
            "sum_commission": 20,
            "sum_dstv": 2000,
            "sum_airtime": 37,
            "sum_ikedc": 0,
            "sum_firs": 0,
            "sum_ekedc": 0,
            "sum_benindisco": 0,
            "sum_kadunadisco": 0,
            "sum_data": 0,
            "count_dstv": 2,
            "count_airtime": 3,
            "count_ikedc": 0,
            "count_ekedc": 0,
            "count_benindisco": 0,
            "count_kadunadisco": 0,
            "count_firs": 0,
            "count_data": 0
        }
    ]
}
{}

Get bill payments history

get https://api.flutterwave.com/v3/bills/history

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call.

curl --location 'https://api.flutterwave.com/v3/bills/history?status=Successful&from=2024-03-01&to=2024-03-11' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'
{
  "status": "success",
  "message": "Bill history fetched successfully",
  "meta": {
    "page_info": {
      "total": 4,
      "total_pages": 1,
      "current_page": 1
    }
  },
  "data": [
    {
      "id": 5494170,
      "currency": "NGN",
      "customer_id": "0025401100",
      "frequency": "One Time",
      "amount": "200.00",
      "category": "Cable Bill Payment",
      "recurring_payment_id": null,
      "product": "DSTV Payment",
      "product_name": "DSTV Payment",
      "commission": "10.00",
      "transaction_date": "2024-03-08T16:40:00.547Z",
      "tx_id": 5494170,
      "customer_reference": "b3a67b4e-6fae-46b8-bfc4-9003e0939e8e",
      "country": "NG",
      "flw_ref": "247846329168",
      "tx_ref": "CF-FLYAPI-20240308044000296166",
      "batch_id": 3387852,
      "extra": null,
      "product_details": "FLY-API-NG-DSTV Payment",
      "status": "Successful"
    },
    {
      "id": 5494155,
      "currency": "NGN",
      "customer_id": "07065657658",
      "frequency": "One Time",
      "amount": "13.00",
      "category": "Airtime",
      "recurring_payment_id": null,
      "product": "AIRTIME",
      "product_name": null,
      "commission": "0.00",
      "transaction_date": "2024-03-08T15:57:12.97Z",
      "tx_id": 5494155,
      "customer_reference": "be3c7984-fe0c-4cb7-81c2-d3734f1dbd48",
      "country": "NG",
      "flw_ref": "BPUSSD1709913436071081",
      "tx_ref": "CF-FLYAPI-20240308035712257603",
      "batch_id": 3387837,
      "extra": null,
      "product_details": "FLY-API-NG-AIRTIME",
      "status": "Successful"
    },
    {
      "id": 5494154,
      "currency": "NGN",
      "customer_id": "07065657658",
      "frequency": "One Time",
      "amount": "11.00",
      "category": "Airtime",
      "recurring_payment_id": null,
      "product": "AIRTIME",
      "product_name": null,
      "commission": "0.00",
      "transaction_date": "2024-03-08T15:55:16.963Z",
      "tx_id": 5494154,
      "customer_reference": "d7a004b1-a581-4cd9-89ae-a1ff89c45c9a",
      "country": "NG",
      "flw_ref": "BPUSSD1709913319189093",
      "tx_ref": "CF-FLYAPI-20240308035516465263",
      "batch_id": 3387836,
      "extra": null,
      "product_details": "FLY-API-NG-AIRTIME",
      "status": "Successful"
    },
    {
      "id": 5469189,
      "currency": "NGN",
      "customer_id": "07065657658",
      "frequency": "One Time",
      "amount": "13.00",
      "category": "Airtime",
      "recurring_payment_id": null,
      "product": "AIRTIME",
      "product_name": null,
      "commission": "0.00",
      "transaction_date": "2024-03-01T14:41:02.493Z",
      "tx_id": 5469189,
      "customer_reference": "7fc8279d-e04f-409d-841a-bfd5279d4970",
      "country": "NG",
      "flw_ref": "BPUSSD1709304064772808",
      "tx_ref": "CF-FLYAPI-20240301024102687583",
      "batch_id": 3361900,
      "extra": null,
      "product_details": "FLY-API-NG-AIRTIME",
      "status": "Successful"
    }
  ]
}
{}
Loading...