Skip to main content
Use this endpoint to query the current status of a bill payment. Pass the requestRef you submitted when calling Pay Bill.

​
Authentication

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

​
Endpoint

GET https://api.hyparrow.com/api/v1/bills/status?reference={requestRef}

​
Query parameters

​
reference
string
required
The requestRef you provided when the payment was initiated. This is the unique 13-digit reference generated on your side.

​
Response

​
success
boolean
true when the status check request succeeds.
​
data
object
Status details for the referenced payment.
​
error
string
Error message if the lookup fails. Empty on success.

​
Examples

curl -X GET "https://api.hyparrow.com/api/v1/bills/status?reference=1234567890123" \
  -H "x-api-key: your_api_key" \
  -H "x-api-secret: your_api_secret"

​
Success response

{
  "success": true,
  "data": {
    "responseCode": "00",
    "responseDescription": "Approved",
    "transactionRef": "ISW-TXN-20240115-001234",
    "requestRef": "1234567890123",
    "amount": "50000",
    "customerId": "08012345678",
    "customerName": "ADA OKAFOR"
  },
  "error": ""
}

​
Error response

{
  "success": false,
  "data": null,
  "error": "transaction not found"
}