Skip to main content
Use this endpoint to pay a bill. The payment amount is deducted from your Hyparrow wallet. A webhook notification is sent to your configured webhook URL when the payment succeeds.

​
Authentication

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

​
Endpoint

POST https://api.hyparrow.com/api/v1/bills/pay

​
Request body

​
paymentCode
string
required
The payment code identifying the specific payment option. Retrieve this from the Get Service Options endpoint (PaymentCode field).
​
customerId
string
required
The customer’s identifier for the biller. For airtime, this is the phone number (e.g., 08012345678). For electricity, this is the meter number. For cable TV, this is the smartcard or IUC number.
​
amount
string
required
The payment amount in kobo. ₦100 = "10000". For services with a fixed price, this must match the exact amount returned by the service options endpoint.
​
requestRef
string
required
A unique reference for this transaction. Must be exactly 13 digits. Store this value — you can use it to query payment status later.
​
customerEmail
string
The customer’s email address. Optional but recommended for receipt delivery.
​
customerMobile
string
The customer’s mobile number. Optional.

​
Response

​
success
boolean
true when the payment is processed successfully.
​
data
object
Payment result returned by the billing provider.
​
error
string
Error message when the payment fails. Empty on success.

​
Examples

curl -X POST https://api.hyparrow.com/api/v1/bills/pay \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -H "x-api-secret: your_api_secret" \
  -d '{
    "paymentCode": "04011",
    "customerId": "08012345678",
    "amount": "50000",
    "requestRef": "1234567890123",
    "customerEmail": "ada.okafor@example.com",
    "customerMobile": "08012345678"
  }'

​
Success response

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

​
Success response (prepaid electricity)

{
  "success": true,
  "data": {
    "responseCode": "00",
    "responseDescription": "Approved",
    "transactionRef": "ISW-TXN-20240115-001235",
    "requestRef": "9876543210987",
    "amount": "500000",
    "customerId": "45678901234",
    "customerName": "ADA OKAFOR",
    "token": "3141-5926-5358-9793"
  },
  "error": ""
}

​
Error response (insufficient balance)

{
  "success": false,
  "error": "insufficient wallet balance"
}

​
Error response (invalid amount)

{
  "success": false,
  "error": "Invalid amount. This service requires exactly ₦500.00"
}
Bill payments deduct from your Hyparrow wallet balance before the payment is forwarded to the provider. Ensure your wallet has sufficient funds before calling this endpoint.
Generate your requestRef as a 13-digit numeric string using a timestamp or UUID-derived value. Keep a record of it — you can use it to check the payment status via the Payment Status endpoint.