Use these endpoints to explore the full list of available billers, fetch the payment items (with their PaymentCode values) needed to initiate a payment, search by keyword, or look up a biller by category and name.
Authentication All bill endpoints require API key authentication:
x-api-key: your_api_key x-api-secret: your_api_secret
List all services Returns every biller available on the platform.
Endpoint GET https://api.hyparrow.com/api/v1/bills/services
Response true when the request succeeds.
Array of biller objects. The ID of the biller’s parent category.
The name of the biller’s parent category.
Examples curl -X GET https://api.hyparrow.com/api/v1/bills/services \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "data" : [ { "id" : "BIL119" , "name" : "MTN Airtime" , "categoryId" : "1" , "categoryName" : "Airtime" }, { "id" : "BIL135" , "name" : "DSTV Subscription" , "categoryId" : "3" , "categoryName" : "Cable TV" }, { "id" : "BIL150" , "name" : "Ikeja Electric" , "categoryId" : "2" , "categoryName" : "Electricity" } ], "error" : "" }
Get service options Returns the payment items for a specific biller, including the PaymentCode required when calling Pay Bill . For services with fixed pricing, the item also contains the required amount in kobo.
Endpoint GET https://api.hyparrow.com/api/v1/bills/services/options?serviceId={id}
Query parameters The biller ID to retrieve payment items for. Obtain this from the list services or list categories endpoints.
Response true when the request succeeds.
Array of payment item objects. The code to pass as paymentCode in the Pay Bill request.
Human-readable name of the payment option.
Fixed amount in kobo ("0" means the amount is flexible and must be provided at payment time).
Currency code for this payment option (e.g. "NGN").
Examples curl -X GET "https://api.hyparrow.com/api/v1/bills/services/options?serviceId=BIL119" \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "data" : [ { "PaymentCode" : "04011" , "Name" : "MTN Airtime VTU" , "Amount" : "0" , "CurrencyCode" : "NGN" } ], "error" : "" }
When Amount is "0", the service has flexible pricing. You must supply the amount field (in kobo) when calling Pay Bill . Search billers Search for billers by keyword across all categories.
Endpoint GET https://api.hyparrow.com/api/v1/bills/search?q={query}
Query parameters The search term to match against biller names.
Response true when the request succeeds.
Number of matching billers.
Array of matching biller objects.
Examples curl -X GET "https://api.hyparrow.com/api/v1/bills/search?q=DSTV" \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "count" : 1 , "data" : [ { "id" : "BIL135" , "name" : "DSTV Subscription" , "categoryId" : "3" , "categoryName" : "Cable TV" } ] }
Get biller by category and name Look up a single biller using its exact category name and biller name. Both parameters are required.
Endpoint GET https://api.hyparrow.com/api/v1/bills/biller?category={category}&biller={name}
Query parameters The category name to search within (e.g., Cable TV).
The biller name to look up (e.g., DSTV Subscription).
Response true when the biller is found.
A single biller object matching the category and name provided.
Examples curl -X GET "https://api.hyparrow.com/api/v1/bills/biller?category=Cable%20TV&biller=DSTV%20Subscription" \ -H "x-api-key: your_api_key" \ -H "x-api-secret: your_api_secret"
Success response { "success" : true , "data" : { "id" : "BIL135" , "name" : "DSTV Subscription" , "categoryId" : "3" , "categoryName" : "Cable TV" } }
Error response { "success" : false , "error" : "biller not found" }
