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)

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:
- BillerItemsResponseDto
- ElectricityBillerResponseDto
- PaginatedBillResponseDto
- BillResponseDto
- AirtimePurchaseDto
- DataPurchaseDto
- ElectricityPaymentDto
- CableTvPaymentDto
- BillPaymentResponseDto
- ValidateBillDto
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.

​Overview

​Bill Discovery

​Get Biller Items

​Get Electricity Billers

​Bill Payments

​Buy Airtime

​Buy Mobile Data

​Buy Electricity

​Subscribe to Cable TV

​Bill Validation

​Bill Records Service

​Get All Bills

​Get Bill by Reference

​Generate Receipt

​Working with Response Objects

​Notes