Skip to main content

Bills Service

The monei.bills service allows you to:
  • Discover available billers
  • Purchase airtime and data
  • Pay electricity bills
  • Subscribe to cable TV
  • Validate customer bill details
  • Retrieve bill payment history
  • Get receipts and transaction details

Initialize

from monei import Monei

monei = Monei(api_key="your-secret-key")

Bill Discovery Service

Discover bill categories and available billers.

Get Biller Items

Retrieve biller items by category and biller name.
items = await monei.bills.discovery.get_biller_items(
    category="electricity",
    biller_name="ikeja-electric"
)

for item in items["data"]:
    print(item["name"])

Get Electricity Distribution Companies

Retrieve all supported electricity distribution companies.
electricity_billlers = await monei.bills.discovery.get_electricity_biller_items()

for disco in electricity_billlers["data"]:
    print(disco["name"])

Bill Payment Service

Make bill payments.

Buy Airtime

response = await monei.bills.pay.buy_airtime({
    "phone_number": "08012345678",
    "network": "MTN",
    "amount": 1000
})

print(response["reference"])
print(response["status"])

Buy Data

response = await monei.bills.pay.buy_data({
    "phone_number": "08012345678",
    "network": "MTN",
    "plan_id": "data-plan-id"
})

print(response["reference"])
print(response["status"])

Pay Electricity Bill

response = await monei.bills.pay.buy_electricity({
    "meter_number": "12345678901",
    "disco": "ikeja-electric",
    "amount": 5000
})

print(response["reference"])
print(response["status"])

Subscribe to Cable TV

response = await monei.bills.pay.subscribe_cable_tv({
    "smartcard_number": "1234567890",
    "provider": "dstv",
    "package_id": "compact"
})

print(response["reference"])
print(response["status"])

Bill Records Service

Retrieve bill payment history and receipts.

Get All Bills

bills = await monei.bills.records.get_bills()

for bill in bills["data"]:
    print(bill["reference"], bill["status"])

Get Bill by Reference

bill = await monei.bills.records.get_bill_by_reference("bill-reference")

print(bill["reference"])
print(bill["status"])

Get Bill Receipt

receipt = await monei.bills.records.get_bill_receipt("transaction-id")

print(receipt)

Bill Validation Service

Validate customer bill information before making payment.

Validate Bill

validated = await monei.bills.validation.validate_bill({
    "biller": "ikeja-electric",
    "customer_id": "12345678901"
})

print(validated["customer_name"])

Error Handling

All Bills operations may raise MoneiAPIError.
from monei.exceptions import MoneiAPIError

try:
    bills = await monei.bills.records.get_bills()
except MoneiAPIError as error:
    print(error.message)

Service Overview

ServiceDescription
discoveryRetrieve available billers and categories
payMake bill payments
recordsRetrieve bill history and receipts
validationValidate customer billing details