Bill Payments

Overview

The Bills API lets you browse a catalog of billers, validate a customer (meter, smartcard/IUC, or account) before charging, and pay for airtime, data, cable TV, and electricity. Every successful payment debits your Hyparrow wallet. There are two route families:

/bills/* — the primary catalog-driven flow. You discover billers and payment items from the cache, validate a customer, then pay by paymentCode.
/bills/topup/* — an alternate bill-pay route set that resolves products by catalog ids (network / plan / provider) instead of payment codes, and also supports printable PIN products (exam PINs, recharge-card PINs, data PINs).

Both families ultimately route to the bill provider and the same wallet.

Base URL: https://api.hyparrow.cloud/api/v1Auth: every request requires X-API-Key and X-API-Secret headers.Sandbox: point at https://sandbox.hyparrow.cloud/api/v1 and use your pk_test_ key. In sandbox you can simulate outcomes with magic amounts — an amount ending in .01 forces a failed result, and .99 forces a pending result. Everything else succeeds.

Amount units

Route family	Amount field	Unit
`/bills/pay`	`amount` (string)	Minor units (kobo) — must match the cached payment item amount for fixed-price items
`/bills/topup/*`	`amount` (string)	Kobo — the base price; Hyparrow adds its markup on top before debiting

Discovering billers

The primary flow is driven by a cached catalog. Walk it from categories down to the specific payment item, whose PaymentCode you pass to /bills/pay.

List categories

GET /bills/categories returns the available bill categories (airtime, data, cable TV, electricity, and more).

List billers in a category

GET /bills/category/billers?category=<name|id> returns the billers under a category. You can also browse everything with GET /bills/services.

Get payment options

GET /bills/services/options?serviceId=<id> returns the payment items (plans / packages) for a biller, each carrying the PaymentCode and Amount you need to pay.

Find a specific biller (optional)

GET /bills/search?q=<term> free-text searches the catalog, and GET /bills/biller?category=<name>&biller=<name> returns a single biller matched by category + biller name.

List categories

curl https://api.hyparrow.cloud/api/v1/bills/categories \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Response

{
  "success": true,
  "count": 6,
  "data": [
    { "Id": "1", "Name": "Airtime" },
    { "Id": "2", "Name": "Mobile Data" },
    { "Id": "4", "Name": "Cable TV" },
    { "Id": "5", "Name": "Utility Bills" }
  ],
  "error": ""
}

Validate before you pay

For services tied to a customer account — electricity meters and cable smartcards/IUCs — validate the customer first. This confirms the beneficiary name and that the account is payable before any money leaves the wallet.

Validate a customer

curl -X POST https://api.hyparrow.cloud/api/v1/bills/validate \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "0123456789",
    "paymentCode": "10401"
  }'

Response

{
  "success": true,
  "data": {
    "CustomerId": "0123456789",
    "FullName": "JANE DOE",
    "Amount": "0",
    "AmountType": "OPEN"
  },
  "error": ""
}

/bills/validate accepts both the flat shape above and an array shape ({ "customers": [{ "CustomerId": "...", "PaymentCode": "..." }] }). Both customerId and paymentCode are required.

Paying a bill

POST /bills/pay charges the wallet and submits the payment. The amount is in kobo and, for fixed-price payment items, must exactly match the cached item amount — otherwise the request is rejected with the required amount. For flexible-price items you supply the amount; if you omit it on a fixed-price item, Hyparrow auto-fills it from the catalog.

Resolve the payment item

From the catalog, take the PaymentCode (and Amount for fixed items).

Validate (metered/cable services)

Confirm the beneficiary with /bills/validate.

Pay

Call /bills/pay. The wallet is debited and the payment is submitted to the bill provider in one call.

Confirm

Poll /bills/status?reference=<ref> to confirm the final outcome.

Pay a bill

curl -X POST https://api.hyparrow.cloud/api/v1/bills/pay \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCode": "10401",
    "customerId": "0123456789",
    "amount": "150000",
    "requestRef": "ORDER-2026-0001"
  }'

Response

{
  "success": true,
  "data": {
    "TransactionRef": "MBP1719772800000000000",
    "Amount": "150000",
    "ResponseCode": "90000",
    "ResponseMessage": "Successful"
  },
  "error": ""
}

The data.TransactionRef (or your own requestRef) is what you use to check status later.

Examples by category

{
  "paymentCode": "<airtime payment code>",
  "customerId": "08030000000",
  "amount": "50000"
}

{
  "paymentCode": "<data plan payment code>",
  "customerId": "08030000000",
  "amount": "100000"
}

{
  "paymentCode": "<bouquet payment code>",
  "customerId": "1234567890",
  "amount": "650000"
}

{
  "paymentCode": "<meter payment code>",
  "customerId": "0123456789",
  "amount": "500000"
}

Checking status

GET /bills/status?reference=<ref> returns the latest status for a bill transaction. Pass either the provider TransactionRef returned by /bills/pay or your own requestRef.

Response

{
  "success": true,
  "data": {
    "TransactionRef": "MBP1719772800000000000",
    "Status": "COMPLETED",
    "ResponseCode": "90000"
  },
  "error": ""
}

In sandbox, use the magic amounts to exercise status handling: an amount ending in .99 (e.g. "19999" for ₦199.99) lands in pending so you can test polling, and .01 lands in failed.

Edge cases

Wrong amount for a fixed-price item. If a payment item has a fixed price and your amount does not match it, the request is rejected before any charge:

{
  "success": false,
  "error": "Invalid amount. This service requires exactly ₦1,500.00"
}

Insufficient wallet balance. If the wallet cannot cover the amount, the deduction fails and the payment is never submitted:

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

Validation service unavailable. If the upstream customer-validation lookup times out, /bills/validate returns 503 with a retry-friendly message. Retry shortly; do not attempt to pay an unvalidated metered/cable customer.

Alternate route set — `/bills/topup`

/bills/topup/* is an alternate bill-pay route set. Instead of payment codes it resolves products by catalog ids (network, plan, provider), and it adds printable PIN products that the primary routes don’t cover. Hyparrow prices each category server-side and debits the result; if the provider declines or errors, the wallet deduction is automatically refunded.

Airtime costs less than face value. It carries no markup — Hyparrow passes part of its wholesale discount back to you, so chargeKobo is below the amount you sent: 1.5% off MTN and Airtel, 2% off GLO and 9mobile. ₦100 of MTN debits ₦98.50 and your customer still receives ₦100. Every other category adds a markup instead. Always trust the returned chargeKobo.

Resolve catalog ids

GET /bills/topup/services?service=<type> returns the catalog you need to build a request. Valid service values include network, data, cabletv, cable-provider, electricity, exampin, datapin, and recharge-card.

Fetch data plans

curl "https://api.hyparrow.cloud/api/v1/bills/topup/services?service=data" \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Validate (cable / electricity)

POST /bills/topup/validate resolves the customer name for a cable IUC or an electricity meter. Airtime and data have nothing to validate.

Validate a meter

curl -X POST https://api.hyparrow.cloud/api/v1/bills/topup/validate \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "electricity",
    "customerId": "45010101010",
    "provider": "<disco provider id>",
    "meterType": "prepaid"
  }'

Response

{
  "success": true,
  "data": {
    "customerName": "JANE DOE",
    "providerResponse": { "Customer_Name": "JANE DOE" }
  },
  "error": ""
}

Pay (airtime / data / TV / electricity)

POST /bills/topup pays a bill resolved by catalog ids. service is one of airtime, data, tv, electricity. amount is the base price in kobo — the value your customer receives. Hyparrow prices it before debiting: a markup on most categories, a cashback on airtime.

{
  "service": "airtime",
  "customerId": "08030000000",
  "amount": "50000",
  "network": "<network id>"
}

{
  "service": "data",
  "customerId": "08030000000",
  "amount": "100000",
  "network": "<network id>",
  "plan": "<plan id>"
}

{
  "service": "tv",
  "customerId": "1234567890",
  "amount": "650000",
  "provider": "<cable provider id>",
  "plan": "<bouquet id>",
  "subType": "renew",
  "phone": "08030000000"
}

{
  "service": "electricity",
  "customerId": "45010101010",
  "amount": "500000",
  "provider": "<disco provider id>",
  "meterType": "prepaid",
  "phone": "08030000000"
}

Response

{
  "success": true,
  "data": {
    "service": "data",
    "description": "Data bundle",
    "reference": "TPM1719772800000000000",
    "TransactionRef": "TPM1719772800000000000",
    "baseKobo": 100000,
    "markupKobo": 25000,
    "chargeKobo": 125000,
    "status": "successful",
    "message": "Transaction successful",
    "providerResponse": { }
  },
  "error": ""
}

The response exposes the full charge breakdown: baseKobo (what you sent), markupKobo (Hyparrow’s markup), cashbackKobo (the discount off face value, airtime only) and chargeKobo (what the wallet was debited). markupKobo and cashbackKobo are never both non-zero — a category is priced one way or the other.

Airtime response — charged below face value

{
  "success": true,
  "data": {
    "service": "airtime",
    "baseKobo": 10000,
    "markupKobo": 0,
    "cashbackKobo": 150,
    "chargeKobo": 9850
  },
  "error": ""
}

Declined purchase is refunded. If the bill provider declines (e.g. invalid plan), the endpoint returns success: false with the provider message, and the wallet deduction is refunded automatically:

{
  "success": false,
  "error": "Invalid plan selected",
  "data": {
    "reference": "TPM1719772800000000000",
    "providerResponse": { }
  }
}

PIN products

These routes generate printable PINs. The amount you send is the base total price in kobo (unit price × quantity); the wallet is charged the base plus the category markup, and a declined purchase is refunded.

curl -X POST https://api.hyparrow.cloud/api/v1/bills/topup/exampin \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "1",
    "quantity": "2",
    "amount": "700000"
  }'

curl -X POST https://api.hyparrow.cloud/api/v1/bills/topup/rechargepin \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "<network id>",
    "quantity": "10",
    "plan": "<denomination id>",
    "businessName": "Acme Stores",
    "amount": "100000"
  }'

curl -X POST https://api.hyparrow.cloud/api/v1/bills/topup/datapin \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "<network id>",
    "quantity": "5",
    "dataPlan": "<data pin plan id>",
    "businessName": "Acme Stores",
    "amount": "250000"
  }'

Response

{
  "success": true,
  "data": {
    "service": "Exam PIN",
    "reference": "TPM1719772800000000000",
    "TransactionRef": "TPM1719772800000000000",
    "baseKobo": 700000,
    "markupKobo": 35000,
    "chargeKobo": 735000,
    "status": "successful",
    "message": "Transaction successful",
    "providerResponse": { }
  },
  "error": ""
}

Route	Required fields	Notes
`POST /bills/topup/exampin`	`provider`, `quantity`	WAEC / NECO / NABTEB exam PINs
`POST /bills/topup/rechargepin`	`network`, `quantity`, `plan`	Printable airtime recharge-card PINs (no markup, pass-through)
`POST /bills/topup/datapin`	`network`, `quantity`, `dataPlan`	Printable data PINs

Status for /bills/topup/* payments is available through the same GET /bills/status?reference=<ref> endpoint, using the reference returned by the payment call.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

Amount units

Discovering billers

Validate before you pay

Paying a bill

Examples by category

Checking status

Edge cases

Alternate route set — `/bills/topup`

Resolve catalog ids

Validate (cable / electricity)

Pay (airtime / data / TV / electricity)

PIN products

​Overview

​Amount units

​Discovering billers

​Validate before you pay

​Paying a bill

​Examples by category

​Checking status

​Edge cases

​Alternate route set — /bills/topup

​Resolve catalog ids

​Validate (cable / electricity)

​Pay (airtime / data / TV / electricity)

​PIN products

Overview

Amount units

Discovering billers

Validate before you pay

Paying a bill

Examples by category

Checking status

Edge cases

Alternate route set — `/bills/topup`

Resolve catalog ids

Validate (cable / electricity)

Pay (airtime / data / TV / electricity)

PIN products