Bill categories group related billers together — for example, airtime, electricity, cable TV, and internet. Use these endpoints to discover what categories are available and which billers belong to each one.
Authentication All bill endpoints require API key authentication. Include both headers on every request:
x-api-key: your_api_key x-api-secret: your_api_secret
List all categories Returns every available bill payment category with its ID and name.
Endpoint GET https://api.hyparrow.com/api/v1/bills/categories
Response true when the request succeeds.
Total number of categories returned.
Array of category objects. Unique identifier for the category.
Display name of the category (e.g., Airtime, Electricity, Cable TV).
Examples curl -X GET https://api.hyparrow.com/api/v1/bills/categories \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "count" : 5 , "data" : [ { "id" : "1" , "name" : "Airtime" }, { "id" : "2" , "name" : "Electricity" }, { "id" : "3" , "name" : "Cable TV" }, { "id" : "4" , "name" : "Internet" }, { "id" : "5" , "name" : "Water" } ], "error" : "" }
List billers by category Returns all billers that belong to a specific category. You can identify the category by its name or its ID.
Endpoint GET https://api.hyparrow.com/api/v1/bills/category/billers?category={name or id}
Query parameters The category name (e.g., Airtime) or category ID (e.g., 1). The lookup is case-insensitive for names.
Response true when the request succeeds.
Total number of billers returned.
Array of biller objects belonging to the requested category. Unique biller identifier.
The ID of the parent category.
The name of the parent category.
Examples curl (by name)
curl (by id)
curl -X GET "https://api.hyparrow.com/api/v1/bills/category/billers?category=Airtime" \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "count" : 4 , "data" : [ { "id" : "BIL119" , "name" : "MTN Airtime" , "categoryId" : "1" , "categoryName" : "Airtime" }, { "id" : "BIL120" , "name" : "Airtel Airtime" , "categoryId" : "1" , "categoryName" : "Airtime" }, { "id" : "BIL121" , "name" : "Glo Airtime" , "categoryId" : "1" , "categoryName" : "Airtime" }, { "id" : "BIL122" , "name" : "9mobile Airtime" , "categoryId" : "1" , "categoryName" : "Airtime" } ] }
Error response { "success" : false , "error" : "category not found" }
