Skip to main content

​
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:
    • 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.