Skip to content

Catalogue

Reference data — networks, categories, providers and settings. Most of it is public, so you can load it before a user signs in.

Networks

GET/api/v1/network/

Auth: API key or session.

curl https://api.instapaybill.com/api/v1/network/ \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0"

The canonical list of supported mobile networks, with logos and metadata.

Values to use in purchase requests: MTN, AIRTEL, GLO, T2MOBILE.

Validate a phone number

GET/api/v1/network/validate-number/{phoneNumber}

Public — no credential required.

curl https://api.instapaybill.com/api/v1/network/validate-number/08012345678

Resolves a number to its carrier using the MCD/Sprintcheck operator lookup. Useful in a UI to pre-select the network and to catch a carrier mismatch before the purchase.

The lookup is cached for 24 hours.

Categories

GET/api/v1/category/

Public — no credential required.

curl https://api.instapaybill.com/api/v1/category/

The product tree. A category is the unit that binds a product to a network and to a biller, and it is also the unit the network-health guard acts on.

{
  "msg": "Categories retrieved successfully",
  "data": [
    {
      "_id": "<categoryId>",
      "name": "MTN AIRTIME",
      "product": "<productId>",
      "biller": "<billerId>",
      "billerList": ["<billerId>"],
      "enabler": "enable",
      "networkBad": "disable"
    }
  ]
}
Field Description
enabler enable / disable. A disabled category rejects purchases with 300.
networkBad enable when the network is degraded. Purchases are refused but can be scheduled.
biller The primary provider for this category.
billerList Every provider that can serve this category.

Category names

Airtime categories are named <NETWORK>_AIRTIME (e.g. MTN_AIRTIME). Billers that serve the same product across networks have their own category (e.g. T2MOBILE_AIRTIME) — these are routing labels and never block customers, even when the customer-facing category is flagged.

Startimes plans

GET/api/v1/startime/

Public — no credential required.

curl https://api.instapaybill.com/api/v1/startime/

The Startimes package catalogue.

Startimes purchases go through the cable endpoints

There is no live POST /api/v1/startime/buy. Startimes is bought with POST /api/v1/cables/buy using the STARTIMES cable type. The sandbox does have a dedicated POST /api/v1/sandbox/startimes route.

Settings

GET/api/v1/settings/

Public — no credential required.

curl https://api.instapaybill.com/api/v1/settings/

Platform-wide configuration: commission rates, cashback percentages, funding limits and transfer limits. The commission rates here are the ones used to calculate your earnings.

Use cases

GET/api/v1/usecase/

Public — no credential required.

curl https://api.instapaybill.com/api/v1/usecase/

The feature-flag document. This is the single best endpoint for diagnosing "why is my purchase being rejected with 'Service is currently unavailable'?".

Flag Effect when not enable
apiStatus The whole API channel is switched off
appStatus / webStatus / adminStatus The corresponding channel is switched off
airtime Airtime purchases are refused
data Data purchases are refused
electricity Electricity purchases are refused
cables Cable purchases are refused
education Education purchases are refused
kycRequired When disable, purchases are allowed without KYC
ninBvnRestriction When enable, wallet transfers require KYC on both sides
whatsappBuysEnabled The WhatsApp channel is paused
whatsappPilotMode The WhatsApp channel is restricted to a pilot phone list
airtimeMini / airtimeMax The allowed airtime amount range
minimumFunding / maximumFunding The allowed funding range
transferFundingMini / transferFundingMax / transferFundLimit Transfer limits
duplicateTransactionTimer / duplicateTransactionTimerStatus Duplicate-guard window
registration / login / otpRegistration Account flows
autoFund / microAutoFund Auto-funding behaviour
referralBonus / referralDataPlanBonus Referral rewards
cgStatus Bucket wallet (CG wallet) feature
nightPromoStatus Night promo window
whatsappDailyCap Per-phone daily cap on the WhatsApp channel

Other public endpoints

Method Path Description
GET /api/v1/faqs/ Public FAQ list
GET /api/v1/promo/active Whether a promo widget should be shown
GET /api/v1/giveaway/count Giveaway entries used vs limit
GET /api/v1/voice-assistant/health Voice service health

The full catalogue in one call

If you are building a plan picker, do not fetch each catalogue endpoint separately. Use GET /api/v1/data/agent-data, which returns data plans and cable plans together in a single request.