> ## 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.

# Bills Services

> Discover billers, pay bills, validate bills, and track bill records using the Monei Python SDK

# 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.

```python theme={null}
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.

```python theme={null}
billers = monei.bills_discovery.get_electricity_biller()

print(billers.data)
```

***

## Bill Payments

### Buy Airtime

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
# 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.

***