Use the Kuda Business API to sell or pay supported bills such as airtime, data, electricity, TV subscriptions, betting, education, transport, and other bill categories.

Recommended flow:

Discover billers and bill items.
Verify the customer reference when required.
Purchase the bill.
Confirm the final outcome with BILL_TSQ when needed.

Service types

`serviceType`	Purpose
`GET_BILLERS`	Returns a broad biller list.
`GET_BILLERS_BY_TYPE`	Returns billers and purchasable `billItems` for one category.
`VERIFY_BILL_CUSTOMER`	Validates a meter number, smartcard number, phone number, or other customer reference.
`ADMIN_PURCHASE_BILL`	Executes the bill payment from the business account.
`BILL_TSQ`	Checks bill payment status and may return PIN or token details.

Step 1: Discover billers

Use GET_BILLERS_BY_TYPE when you need purchasable products.

{
  "serviceType": "GET_BILLERS_BY_TYPE",
  "requestRef": "CAT20260603001",
  "data": {
    "BillTypeName": "electricity"
  }
}

The selected bill item should include a kudaIdentifier. Use that value in verification and purchase requests.

Common BillTypeName values include:

airtime
internet data
electricity
cabletv
betting
education
transport
tax
solar
esim

Validate against the current catalog before going live because billers and categories can change.

Step 2: Verify the customer

Some billers require customer verification before purchase.

{
  "serviceType": "VERIFY_BILL_CUSTOMER",
  "requestRef": "VER20260603001",
  "data": {
    "KudaBillItemIdentifier": "KUD-ELE-AEDC-001",
    "CustomerIdentification": "46432634278"
  }
}

Always verify against the same bill item you intend to purchase.

Step 3: Purchase the bill

Use a short, unique, alphanumeric requestRef for purchase calls.

{
  "serviceType": "ADMIN_PURCHASE_BILL",
  "requestRef": "BILL20260603001",
  "data": {
    "CustomerFirstName": "Test",
    "CustomerIdentifier": "07030000000",
    "PhoneNumber": "07030000000",
    "BillItemIdentifier": "KD-VTU-MTNNG",
    "Amount": "10000"
  }
}

Store:

your original requestRef
returned bill request reference
returned bill response reference
any PIN, token, or instructions
the selected bill item identifier
the customer identifier

Step 4: Confirm bill status

Use BILL_TSQ when:

the purchase response is pending
the purchase response is unclear
the response returns K00 or k00
you need a final PIN or token
a webhook is delayed

{
  "serviceType": "BILL_TSQ",
  "requestRef": "BTSQ20260603001",
  "data": {
    "billResponseReference": "BMfoobar",
    "BillRequestRef": "BILL20260603001"
  }
}

Use both billResponseReference and BillRequestRef when available.

Reading bill status

Important TSQ fields include:

Field	Meaning
`finalStatus`	Human-readable outcome when available.
`transactionStatus`	Numeric transaction state.
`postingStatus`	Ledger or posting state.
`billerAggregatorStatus`	Downstream biller or aggregator code.
`pin`	Token, PIN, or instructions when applicable.
`hasBeenReversed`	Reversal status when relevant.

transactionStatus: 3 means completed. transactionStatus: 1 means pending.

Important response-code notes

K00 or k00 can mean the bill request was received, not that downstream fulfillment is final.
K12 means aggregator pending. Check again with BILL_TSQ.
For bill payments that return a PIN or token, TSQ may be the most reliable place to retrieve final fulfillment details.