Africa Fintech FoundryDeveloper Portal
Get API keys
Wallet · Partner API

Bills & airtime

Browse the biller catalogue, verify the customer behind a meter or smartcard, then pay — electricity, TV, airtime and data from the wallet balance.

GET

Biller groups

/Bills/getBillerGroups
The top of the catalogue. Each group’s slug is the key for the package lookup below.
// response · 200
{
  "succeeded": true,
  "code": 200,
  "message": "Successful",
  "data": {
    "response_code": "00",
    "response_message": "Successful",
    "response_data": [
      {
        "id": "BLR-0001",
        "name": "Ikeja Electric",
        "slug": "ikeja-electric"
      },
      {
        "id": "BLR-0002",
        "name": "Airtime & data",
        "slug": "airtime"
      },
      {
        "id": "BLR-0003",
        "name": "TV",
        "slug": "tv"
      }
    ]
  },
  "errors": []
}
POST

Biller by id

/Bills/getBillerById
One biller’s configuration. Note skipValidation — when it is “true” the lookup step below is optional for that biller.
Query parameters
idstringrequiredThe biller id from getBillerGroups. Sent as a query string on a POST.
// query string — a POST with no body
id=BLR-0001
POST

Biller packages

/Bills/getBillerPackageBySlug
The packages a biller sells — prepaid or postpaid power, bouquet tiers, and so on. The chosen package’s slug goes into the payment request.
// response · 200
{
  "succeeded": true,
  "code": 200,
  "message": "Successful",
  "data": {
    "response_code": "00",
    "response_message": "Successful",
    "response_data": [
      {
        "id": "PKG-0001",
        "name": "Prepaid",
        "slug": "prepaid"
      },
      {
        "id": "PKG-0002",
        "name": "Postpaid",
        "slug": "postpaid"
      }
    ]
  },
  "errors": []
}
POST

Customer lookup

/Bills/customerBillLookup
The check that stops money going to a stranger’s meter. Show customerName and make the payer confirm; respect canVend and minPayableAmount before you charge.
Parameters
customerIdstringrequiredThe meter or smartcard number to resolve.
// request
{
  "customerId": "45021987651"
}
POST

Pay a bill

/Bills/processBillPayment
Debits the wallet and vends the bill. The token or receipt detail arrives with the biller’s own delivery (SMS for most electricity vends), not in this response.
Parameters
customerIdstringrequiredThe meter, smartcard or phone number being paid for.
paymentReferencestringrequiredYour unique reference for this payment.
packageSlugstringrequiredThe package being bought, from getBillerPackageBySlug.
amountnumberrequiredAmount in naira.
accountNumberstringrequiredThe wallet NUBAN paying for it.
// request
{
  "customerId": "45021987651",
  "paymentReference": "BIL-20260715-0019",
  "packageSlug": "prepaid",
  "amount": 5000,
  "accountNumber": "9012345678"
}
POST

Airtime operators & products

/Bills/getAirtimeOperatorProduct
The airtime and data catalogue, flat: operator and product in one row, with the slug the payment expects.
// response · 200
{
  "succeeded": true,
  "code": 200,
  "message": "Successful",
  "data": {
    "response_code": "00",
    "response_message": "Successful",
    "response_data": [
      {
        "id": "MTN-AIR",
        "name": "MTN airtime",
        "slug": "mtn-airtime"
      },
      {
        "id": "MTN-DAT",
        "name": "MTN data",
        "slug": "mtn-data"
      },
      {
        "id": "ATL-AIR",
        "name": "Airtel airtime",
        "slug": "airtel-airtime"
      },
      {
        "id": "GLO-AIR",
        "name": "Glo airtime",
        "slug": "glo-airtime"
      }
    ]
  },
  "errors": []
}
POST

Buy airtime or data

/Bills/processAirtimePayment
Same request model as a bill payment — customerId carries the phone number and there is no lookup step; the number is taken as given.
Parameters
customerIdstringrequiredThe meter, smartcard or phone number being paid for.
paymentReferencestringrequiredYour unique reference for this payment.
packageSlugstringrequiredThe package being bought, from getBillerPackageBySlug.
amountnumberrequiredAmount in naira.
accountNumberstringrequiredThe wallet NUBAN paying for it.
// request — customerId is the phone number here
{
  "customerId": "08012345678",
  "paymentReference": "BIL-20260715-0020",
  "packageSlug": "mtn-airtime",
  "amount": 1000,
  "accountNumber": "9012345678"
}