Skip to main content
Call this endpoint before paying a bill to confirm that the customer ID is valid for the selected service. This prevents failed payments caused by incorrect meter numbers, decoder IDs, or phone numbers.

​
Authentication

x-api-key: your_api_key
x-api-secret: your_api_secret

​
Endpoint

GET https://api.hyparrow.com/api/v1/bills/validate?customerId={id}&serviceId={id}

​
Query parameters

​
customerId
string
required
The customer’s identifier for the service. This varies by biller type:
  • Airtime / data: the phone number (e.g., 08012345678)
  • Electricity: the meter number
  • Cable TV: the smartcard or IUC number
  • Internet: the account number
​
serviceId
string
required
The biller ID for the service you intend to pay. Retrieve this from the List Services endpoint.

​
Response

​
success
boolean
true when the customer is found and the details are valid.
​
data
object
Customer details returned by the biller.
​
error
string
An error message when validation fails. Empty on success.

​
Examples

curl -X GET "https://api.hyparrow.com/api/v1/bills/validate?customerId=45678901234&serviceId=BIL150" \
  -H "x-api-key: your_api_key" \
  -H "x-api-secret: your_api_secret"

​
Success response

{
  "success": true,
  "data": {
    "customerId": "45678901234",
    "customerName": "Ada Okafor",
    "customerAddress": "12 Adeola Odeku Street, Lagos",
    "customerEmail": "",
    "customerPhone": "08012345678",
    "amount": "0"
  },
  "error": ""
}

​
Error response

{
  "success": false,
  "data": null,
  "error": "Invalid customer ID"
}
Always validate a customer before calling Pay Bill. A successful validation response confirms the payment will reach the correct account.