DEV Community: brian ambeyi

How I Built M-Pesa Payment Auto-Reconciliation in Django (Daraja API)

brian ambeyi — Wed, 15 Jul 2026 16:33:54 +0000

In Kenya, 90%+ of rent payments come through M-Pesa. If you're building any SaaS that handles recurring payments in East Africa, you'll hit the reconciliation problem fast.

Here's how I solved it for HomeManager — a property management platform where tenants pay rent via M-Pesa Paybill, and the system auto-matches each payment to the correct tenant and invoice.

The Problem

A 40-unit building receives ~40 M-Pesa transactions on rent day. Each transaction has:

Phone number (MSISDN)
Amount
Account reference (what the tenant typed)
Transaction ID
Timestamp

The landlord needs to know: who paid, how much, and does it match what they owe?

Manually: 3 hours in Excel. With automation: 0 seconds.

Architecture Overview

Tenant pays via M-Pesa Paybill
        ↓
Safaricom Daraja API sends C2B callback
        ↓
Django webhook endpoint receives payment
        ↓
Matching engine identifies tenant
        ↓
Payment applied to invoice → balance updated
        ↓
SMS receipt sent to tenant via Africa's Talking

Step 1: Daraja API C2B Registration

First, register your confirmation and validation URLs with Safaricom:

# mpesa/services.py
import requests
from django.conf import settings

def register_c2b_urls():
    url = f"{settings.MPESA_BASE_URL}/mpesa/c2b/v1/registerurl"
    headers = {"Authorization": f"Bearer {get_access_token()}"}
    payload = {
        "ShortCode": settings.MPESA_SHORTCODE,
        "ResponseType": "Completed",
        "ConfirmationURL": f"{settings.BASE_URL}/api/mpesa/confirmation/",
        "ValidationURL": f"{settings.BASE_URL}/api/mpesa/validation/",
    }
    return requests.post(url, json=payload, headers=headers)

Step 2: The Confirmation Webhook

This is where payments land:

# mpesa/views.py
from rest_framework.views import APIView
from rest_framework.response import Response

class MpesaConfirmationView(APIView):
    permission_classes = []  # Safaricom doesn't send auth headers

    def post(self, request):
        data = request.data

        transaction = MpesaTransaction.objects.create(
            transaction_id=data.get("TransID"),
            amount=Decimal(data.get("TransAmount", "0")),
            msisdn=data.get("MSISDN"),
            account_reference=data.get("BillRefNumber", "").strip(),
            transaction_time=parse_mpesa_timestamp(data.get("TransTime")),
            raw_payload=data,
        )

        # Trigger async matching
        match_payment_to_tenant.delay(transaction.id)

        return Response({"ResultCode": 0, "ResultDesc": "Accepted"})

Step 3: The Matching Engine (The Hard Part)

Tenants type account references inconsistently:

"A3" vs "a3" vs "A 3" vs "unit a3" vs "apt A3"
Some type their name instead
Some type nothing at all

The matching logic cascades through strategies:

# payments/matching.py
from celery import shared_task

@shared_task
def match_payment_to_tenant(transaction_id):
    txn = MpesaTransaction.objects.get(id=transaction_id)

    # Strategy 1: Exact account reference match
    tenant = match_by_account_ref(txn.account_reference)

    # Strategy 2: Fuzzy account reference
    if not tenant:
        tenant = match_by_fuzzy_ref(txn.account_reference)

    # Strategy 3: Phone number match
    if not tenant:
        tenant = match_by_phone(txn.msisdn)

    # Strategy 4: Amount + timing heuristic
    if not tenant:
        tenant = match_by_amount_timing(txn.amount, txn.transaction_time)

    if tenant:
        apply_payment(txn, tenant)
    else:
        flag_for_manual_review(txn)


def match_by_account_ref(ref):
    normalized = ref.upper().strip().replace(" ", "")
    for prefix in ["UNIT", "APT", "HOUSE", "HSE", "ROOM", "RM"]:
        normalized = normalized.replace(prefix, "")

    return Tenant.objects.filter(
        unit__unit_number__iexact=normalized,
        lease__is_active=True
    ).first()


def match_by_phone(msisdn):
    phone = normalize_phone(msisdn)
    return Tenant.objects.filter(
        phone_number=phone,
        lease__is_active=True
    ).first()

Step 4: Apply Payment to Invoice

def apply_payment(transaction, tenant):
    invoice = Invoice.objects.filter(
        tenant=tenant,
        status__in=["unpaid", "partial"],
    ).order_by("due_date").first()

    if not invoice:
        create_credit(tenant, transaction.amount)
        return

    payment = Payment.objects.create(
        tenant=tenant,
        invoice=invoice,
        amount=transaction.amount,
        mpesa_transaction=transaction,
        payment_method="mpesa",
    )

    invoice.amount_paid += transaction.amount
    if invoice.amount_paid >= invoice.total_amount:
        invoice.status = "paid"
    else:
        invoice.status = "partial"
    invoice.save()

    send_receipt_sms.delay(payment.id)

Real-World Edge Cases

After months in production:

Duplicate callbacks — Safaricom sometimes sends the same transaction twice. Always check TransID uniqueness.
Partial payments — Tenant owes KES 25,000, sends 10,000 then 15,000. Handle split payments against a single invoice.
Wrong Paybill — Occasionally a payment meant for a different business lands on yours. Flag unmatched.
Phone number changes — Tenant pays from spouse's phone. Phone-based matching fails.
Zero account reference — ~15% of tenants leave it blank. Phone number becomes your only signal.

Match Rate Results

After tuning the cascade:

85% matched instantly (account reference)
10% matched by phone number
3% matched by amount/timing heuristic
2% flagged for manual review

98% auto-reconciliation. The landlord deals with 1 out of 50 payments manually instead of all 50.

The Stack

Backend: Django + Django REST Framework
Task queue: Celery + Redis
M-Pesa: Safaricom Daraja API (C2B, STK Push, B2C)
SMS: Africa's Talking
Database: PostgreSQL
Hosting: AWS (EC2, RDS, S3)

Try It

Daraja API docs: developer.safaricom.co.ke

See it in action for property management: homemanager.buniva.co.ke

Full comparison of property management software in Kenya: buniva.co.ke/blog/best-property-management-software-kenya.html

I'm Brian, founder of Buniva Technologies. Building property management software for East Africa. Connect on LinkedIn.

Automating M-Pesa Rent Collection in Kenya: The Technical Architecture

brian ambeyi — Mon, 13 Jul 2026 07:02:55 +0000

M-Pesa handles over 90% of rent payments in Kenya. But most landlords still reconcile these payments manually — downloading statements, matching transactions to tenants line by line in Excel. We automated this entire flow.

Here is how we built the M-Pesa rent collection system inside HomeManager, our property management platform for East Africa.

The Problem

A landlord with 50 tenants receives 50+ M-Pesa transactions every month. Each transaction has:

Sender phone number
Amount
Account reference (if Paybill)
Transaction ID
Timestamp

To reconcile manually:

Download M-Pesa statement from Safaricom portal
Open tenant spreadsheet
Match each transaction to a tenant
Mark as paid
Send receipt manually
Identify who has not paid
Send reminders individually

For 50 tenants, this takes 4-8 hours monthly. For 200 tenants, it is a full-time job.

The Architecture

We use Safaricom's Daraja API (M-Pesa API) with a Django backend.

Payment Flow

Tenant opens phone
    → Selects Lipa na M-Pesa → Paybill
    → Enters business number (landlord's Paybill)
    → Enters account number (their unit number, e.g., "A3")
    → Enters amount
    → Confirms with PIN

Safaricom processes payment
    → Sends IPN callback to our server
    → Our server receives transaction data

Our system:
    → Validates the callback (security check)
    → Extracts: amount, phone, account_ref, transaction_id
    → Matches account_ref to tenant unit
    → Credits tenant account
    → Generates receipt
    → Sends SMS receipt to tenant
    → Updates dashboard in real-time

Key Technical Decisions

1. Paybill over Till Number

Paybill allows an account reference field. This is critical — the tenant enters their unit number, which the system uses to auto-match the payment. Without this (Till Number), you only get a phone number and have to look up which tenant owns that number.

Full comparison: Paybill vs Till for Rent

2. IPN (Instant Payment Notification) callbacks

Safaricom sends a POST request to our endpoint every time a payment is made. This gives us real-time data — no polling, no delays.

# Simplified IPN handler
@csrf_exempt
def mpesa_callback(request):
    data = json.loads(request.body)

    transaction_id = data['TransID']
    amount = Decimal(data['TransAmount'])
    account_ref = data['BillRefNumber']  # Unit number
    phone = data['MSISDN']

    # Find tenant by unit reference
    tenant = Tenant.objects.filter(
        unit__unit_number__iexact=account_ref,
        unit__property__organization=org
    ).first()

    if tenant:
        # Record payment
        payment = MpesaPayment.objects.create(
            tenant=tenant,
            amount=amount,
            transaction_id=transaction_id,
            phone_number=phone
        )
        # Auto-reconcile against outstanding invoice
        reconcile_payment(payment)
        # Send SMS receipt
        send_receipt_sms(tenant, amount, transaction_id)

    return JsonResponse({'ResultCode': 0})

3. Fuzzy matching for account references

Tenants do not always type their unit number correctly. "A3" might come in as "a3", "A 3", "Unit A3", or "apt3". We normalize the account reference before matching:

def normalize_account_ref(ref):
    """Normalize M-Pesa account reference for matching."""
    ref = ref.strip().upper()
    ref = re.sub(r'[^A-Z0-9]', '', ref)  # Remove special chars
    ref = ref.replace('UNIT', '').replace('APT', '').replace('ROOM', '')
    return ref

4. STK Push for proactive collection

Instead of waiting for tenants to initiate payment, we can trigger an STK Push — a payment prompt appears on the tenant's phone:

def trigger_stk_push(tenant, amount):
    """Send M-Pesa payment prompt to tenant's phone."""
    payload = {
        'BusinessShortCode': PAYBILL_NUMBER,
        'Amount': amount,
        'PartyA': tenant.phone_number,
        'PartyB': PAYBILL_NUMBER,
        'PhoneNumber': tenant.phone_number,
        'AccountReference': tenant.unit.unit_number,
        'TransactionDesc': f'Rent for {tenant.unit.unit_number}'
    }
    response = daraja_api.stk_push(payload)
    return response

This is triggered automatically when reminders are sent — the tenant gets an SMS reminder AND a payment prompt simultaneously.

Results

Payment matching: 95%+ auto-reconciled without human intervention
Receipt delivery: under 10 seconds from payment to SMS receipt
Late payment reduction: 40-60% reduction with automated reminders + STK push
Admin time saved: 8+ hours/month for a 50-unit portfolio

The Stack

Backend: Django + Django REST Framework
Database: PostgreSQL
Task Queue: Celery + Redis (for async SMS sending and reconciliation)
M-Pesa Integration: Safaricom Daraja API v2
SMS: Africa's Talking API
Hosting: AWS (ECS + RDS + S3)
Frontend: React (web) + React Native (mobile)

Try It

The platform is live at homemanager.buniva.co.ke. We handle M-Pesa integration setup for landlords — they do not need to deal with the Daraja API themselves.

If you are building fintech for East Africa and want to discuss M-Pesa integration patterns, happy to connect.

More on property management automation in Kenya: buniva.co.ke/blog

How We Built AI-Powered Property Queries for East African Landlords

brian ambeyi — Thu, 09 Jul 2026 08:56:33 +0000

Most property management platforms give you dashboards. Filters. Reports you need to export. But when a landlord with 50 units asks "who hasn't paid this month?" — they don't want to click through 3 screens. They want to type the question and get the answer.

That's what we built into HomeManager, our property management platform for the East African market.

The Problem

Kenyan landlords managing 20-500 units face a data access problem:

Payment data lives in M-Pesa transaction records
Tenant info lives in the tenant database
Arrears are calculated from invoice vs payment records
Occupancy is derived from unit status

Getting a simple answer like "what's my collection rate this month?" requires joining multiple data sources. Most landlords just... don't. They open the dashboard, glance at a number, and move on without deeper insight.

What We Built

An AI assistant that sits on top of the property management database. Landlords type questions in plain English and get answers from their actual data.

Real examples:

User: "Who hasn't paid rent this month?"
AI: "7 tenants have outstanding balances for July 2026:
- Unit A3: John Mwangi - KES 25,000 (14 days overdue)  
- Unit B7: Mary Ochieng - KES 18,000 (7 days overdue)
..."

User: "What's my occupancy rate at Sunset Apartments?"
AI: "Sunset Apartments: 18/20 units occupied (90%). 
Vacant: Unit A4 (vacant since March), Unit B7 (vacant since June)."

User: "Show me tenants whose lease expires in the next 30 days"
AI: "3 leases expiring before August 8:
- Unit C2: James Kariuki (expires July 15)
- Unit D1: Agnes Wanjiru (expires July 28)
- Unit A8: Peter Odhiambo (expires August 5)"

Technical Approach

We use Claude (AWS Bedrock) as the LLM, with a structured approach:

Intent classification — determine what data the user is asking about (payments, tenants, properties, maintenance)
Query construction — translate natural language into Django ORM queries against the property database
Response formatting — present results in a readable format with relevant context

The key insight: we don't send raw database content to the LLM. We send the schema and let it construct queries, then execute those queries server-side and format the results. This keeps data private and responses accurate.

# Simplified flow
def handle_query(user_message, organization):
    # 1. Classify intent
    intent = classify_intent(user_message)

    # 2. Build query based on intent
    if intent == "unpaid_tenants":
        data = Invoice.objects.filter(
            organization=organization,
            status="unpaid",
            due_date__month=current_month
        ).select_related('tenant', 'unit')

    # 3. Format response
    return format_response(data, user_message)

Why This Matters for East Africa

In Kenya, most landlords are not tech-savvy. They're business people who own buildings. They don't want to learn a dashboard — they want to ask a question and get an answer. The AI assistant makes the platform accessible to landlords who would otherwise stick with Excel because "software is complicated."

It also works across time zones. A diaspora landlord in London can ask "did my tenants pay this month?" at 11pm UK time and get an instant answer without calling their caretaker in Nairobi.

Results

Since launching the AI assistant:

Average session time increased (people explore their data more)
Support queries decreased (landlords answer their own questions)
Feature becomes a differentiator vs competitors who only offer dashboards

Try It

The platform is live at homemanager.buniva.co.ke. Free for up to 20 units.

Full blog post with more examples: What Can an AI Property Assistant Actually Do?

Building in the proptech space in Africa? I'd love to connect. What unique challenges have you faced with localization?

Building PropTech for East Africa: M-Pesa Rent Automation

brian ambeyi — Tue, 30 Jun 2026 13:44:08 +0000

The Problem

In Kenya, over 90% of rent payments happen via M-Pesa (mobile money). But most landlords still reconcile these payments manually — downloading M-Pesa statements, matching transactions to tenants in Excel, and spending 8-12 hours/month on what should be automated.

I'm building HomeManager to solve this.

The Technical Stack

Backend: Django + Django REST Framework
Frontend: React (web) + React Native (mobile)
Payments: Safaricom M-Pesa Daraja API (STK Push + C2B)
Infrastructure: AWS (ECS, RDS, S3, CloudFront)
Task Queue: Celery + Redis
AI: Claude API + AWS Bedrock for natural language queries

M-Pesa Integration Architecture

The most interesting technical challenge: automatic payment reconciliation.

When a tenant pays rent via M-Pesa Paybill:

Safaricom sends a C2B callback to our API
We extract the account number from the transaction
Match it to a tenant's unit
Apply payment to their oldest unpaid invoice
Send SMS receipt instantly
Update the dashboard in real-time

The tricky part? Account numbers. Tenants type them inconsistently — "A12", "a12", "A 12", "Apt 12" should all match to the same unit. We built fuzzy matching logic that handles this.

Automated Invoice Generation

Every 1st of the month, a Celery beat task:

Queries all active leases
Generates invoices with rent + utilities (water, garbage)
Calculates water charges from meter readings
Applies any carried-forward balances
Sends SMS/email notifications to tenants

Late Fee Automation

The system:

Checks daily for invoices past grace period
Calculates fee (percentage, fixed, or both)
Adds as a line item on the invoice
Respects configurable caps (tenant protection)
Won't double-charge (idempotent)

This removes the landlord from the "bad guy" equation — it's the system enforcing what the lease says.

Lessons Building SaaS in East Africa

SMS > Email. Most tenant communication is SMS. Email open rates are <20% in this market.
Mobile-first everything. Property managers do meter readings on-site from phones.
Offline matters. Internet isn't always reliable. Cache critical data.
M-Pesa is not Stripe. Powerful API but inconsistent documentation.
Multi-currency from day one. We support KES, UGX, TZS, RWF.

What's Next

WhatsApp Business API integration
Smart meter reading via OCR
Predictive analytics for vacancy forecasting

If you're building fintech or proptech for emerging markets, I'd love to connect.

Platform: homemanager.buniva.co.ke
Company: buniva.co.ke
Full comparison of property management software in Kenya: buniva.co.ke/blog/best-property-management-software-kenya.html