Documentation Index
Fetch the complete documentation index at: https://docs.monei.cc/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Bills Services provides a full suite of methods to manage bill payments:
Included services:
- Discovery: available billers and biller items
- Payment: for airtime, mobile data, electricity, and cable TV
- Validation: Validate customer bill details before payment
- Records: Retrieve bill payment records and generate receipts
All services require a properly configured MoneiClient instance.
Note: All methods return response objects with attributes accessible via dot notation (e.g., response.status, response.data).
Bill Discovery
Get Biller Items
Retrieve available biller items based on bill category and biller name.
category = "electricity" # e.g. electricity, airtime, data
biller_name = "ikeja-electric"
items = monei.bills_discovery.get_biller(category, biller_name)
print(items.data)
Get Electricity Billers
Retrieve a list of available electricity billers.
billers = monei.bills_discovery.get_electricity_biller()
print(billers.data)
Bill Payments
Buy Airtime
airtime_data = {
"phone_number": "+2348012345678",
"amount": 1000,
"network": "mtn"
}
response = monei.bills_pay.buy_airtime(airtime_data)
print(response.reference)
print(response.status)
print(response.message)
Buy Mobile Data
data_data = {
"phone_number": "+2348012345678",
"amount": 2000,
"network": "glo",
"data_plan": "2GB"
}
response = monei.bills_pay.buy_mobile_data(data_data)
print(response.transaction_id)
print(response.amount)
Buy Electricity
electricity_data = {
"meter_number": "1234567890",
"amount": 5000,
"meter_type": "prepaid",
"service_provider": "ikeja-electric"
}
response = monei.bills_pay.buy_electricity(electricity_data)
print(response.reference)
print(response.units_purchased)
Subscribe to Cable TV
cable_data = {
"smart_card_number": "1234567890",
"bouquet": "dstv-padi",
"service_provider": "dstv"
}
response = monei.bills_pay.subscribe_cable_tv(cable_data)
print(response.reference)
print(response.expiration_date)
Bill Validation
Validate customer bill information before making a payment.
validate_data = {
"customer_id": "1234567890",
"biller_code": "ikeja-electric",
"amount": 5000
}
response = monei.bills_validation.validate(validate_data)
print(response.customer_name)
print(response.customer_address)
print(response.due_date)
Bill Records Service
Retrieve bill payment history and receipts.
Get All Bills
Retrieve a paginated list of bill payment records.
bills = monei.bills_record.get_bills()
# Access paginated response
transactions = bills.data.transactions
pagination = bills.data.pagination
for bill in transactions:
print(bill.reference, bill.amount, bill.status)
print(f"Page {pagination.page} of {pagination.total_pages}")
Get Bill by Reference
Retrieve a bill record using a unique reference.
reference = "TXN-123456"
bill = monei.bills_record.get_bill_by_reference(reference)
print(bill.reference)
print(bill.amount)
print(bill.status)
print(bill.created_at)
Generate Receipt
Generate a receipt for a specific bill transaction.
transaction_id = "transaction-id"
receipt = monei.bills_record.generate_receipt(transaction_id)
print(receipt.receipt_url)
print(receipt.receipt_pdf)
Working with Response Objects
Since all methods return objects with attributes, here’s how to access the data:
# Successful payment response
response = monei.bills_pay.buy_airtime(airtime_data)
# Access attributes using .
if response.status == "success":
reference = response.reference
amount = response.amount
print(f"Payment successful! Reference: {reference}, Amount: {amount}")
# Access nested data
bills = monei.bills_record.get_bills()
transactions = bills.data.transactions
for transaction in transactions:
print(transaction.reference, transaction.amount)
# Handle optional attributes
units = getattr(response, "units_purchased", 0)
Notes
- All methods require a properly configured
MoneiClient instance with authentication.
- DTOs used by the SDK include:
BillerItemsResponseDtoElectricityBillerResponseDtoPaginatedBillResponseDtoBillResponseDtoAirtimePurchaseDtoDataPurchaseDtoElectricityPaymentDtoCableTvPaymentDtoBillPaymentResponseDtoValidateBillDto
- Validate bills before payment to avoid failed or incorrect transactions.
- All responses are strongly typed objects with attribute access, and some may include nested objects depending on the biller.
