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-categoriesQuery Params
Show optional parameters
Headers
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/billersPath Params
string
The bill category code.
Query Params
Show optional parameters
Headers
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/itemsPath Params
string
The unique identifier for the biller. This is returned as data[i].biller_code
in the get billers response.
Headers
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/validatePath Params
string
The bill item code returned in the get bills response as data[i].item_code
.
Query Params
string
The biller code returned in the get biller response as data[i].biller_code
.
string
The customer identifier for the bill payment.
Headers
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/paymentPath Params
string
The bill item code returned in the get bills response as data[i].item_code
.
string
The biller code returned in the get biller response as data[i].biller_code
.
Body Params
string
The Biller country. Expected values include: NG, GH, KE and ZM.
string
The customer identifier for the bill payment.
int32
The bill amount.
Show optional parameters
Headers
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-billsBody Params
string
The merchant's unique identifier for the bulk payment.
string
Merchant-specific URL for bill payment callbacks.
array of objects
An array containing details on each individual request in the batch.
Headers
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/:referencePath Params
string
The merchant's unique identifier for the payment.
Query Params
Show optional parameters
Headers
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/summaryQuery Params
Show optional parameters
Headers
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/historyQuery Params
Show optional parameters
Headers
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"
}
]
}
{}