How DesisPay's Real-Time Reconciliation Works — A Technical Explainer

If you have ever worked in a school bursar's office in Uganda, you know the pain. A parent sends UGX 1,200,000 via MTN Mobile Money. The message arrives on the school phone. Someone writes the details in a ledger. Later — sometimes hours later, sometimes days — someone else manually searches for the student's name, cross-references the fee structure, calculates the outstanding balance, and updates the record. Multiply that by hundreds of payments every week, and you begin to understand why reconciliation is the single biggest administrative bottleneck in Ugandan schools.

At DesisPay, we set out to eliminate that bottleneck entirely. Our real-time reconciliation engine matches every incoming payment to the correct student account within seconds — automatically, accurately, and without any human intervention. Today, I want to pull back the curtain and explain exactly how it works.

The Reconciliation Problem in Ugandan Schools

Before diving into the technical architecture, it is important to understand why reconciliation is so difficult in the traditional school payment model.

• Multiple payment channels: Parents pay via MTN MoMo, Airtel Money, bank deposits, cash, and sometimes third-party agents. Each channel produces a different receipt format.
• Inconsistent references: A parent might send money with the reference "John K Term 2" while the school records show "Kabuye, John — S3." Matching these manually is error-prone.
• Partial payments: Many parents pay in instalments, creating multiple transactions for a single fee obligation that must be tracked and aggregated.
• Shared phone numbers: In many families, one mobile money account serves multiple children at different schools.
• Timing gaps: Bank transfers can take 24-48 hours to clear, creating reconciliation delays that cascade into inaccurate balance reports.

"Before DesisPay, our bursar spent the first two weeks of every term doing nothing but reconciliation. Fee records were always behind, and parents would call daily asking whether their payment had been received." — Director of Studies, Greenhill Academy, Kibuli

The Cost of Manual Reconciliation

The financial and operational impact is staggering. Our research across 200 Ugandan schools found that:

• The average school spends 42 hours per term on manual reconciliation.
• 15% of payments are misallocated or temporarily lost in manual systems.
• 1 in 4 parent complaints to school offices relate to payment status confusion.
• Schools with more than 500 students typically require a dedicated staff member solely for fee tracking.

Architecture Overview: The Reconciliation Engine

DesisPay's reconciliation engine is built on an event-driven microservices architecture designed for speed, accuracy, and fault tolerance. Here is a high-level view of how the system operates.

The Payment Ingestion Layer

Every payment enters the system through what we call the Payment Ingestion Layer. This is a unified gateway that normalises incoming payment data from all channels:

1. MTN Mobile Money API: Direct integration with MTN Uganda's disbursement and collection APIs. Callbacks are received within 2-3 seconds of a successful transaction.
2. Airtel Money API: Similar direct integration with Airtel Uganda, with real-time webhook notifications.
3. Bank Transfer Feeds: Automated SWIFT/RTGS feeds from partner banks including Stanbic, Centenary, and dfcu, with polling intervals as low as 15 minutes.
4. Manual Entry API: For cash payments received at the school office, staff enter details through the DesisPay dashboard, which feeds into the same pipeline.

Every payment, regardless of channel, is transformed into a standardised Payment Event object containing: amount, source identifier, timestamp, reference text, channel metadata, and a unique transaction ID.

The Matching Algorithm

The heart of the reconciliation engine is our proprietary multi-signal matching algorithm. Rather than relying on a single identifier (which is fragile), we score matches across multiple dimensions:

• Student ID match (weighted score: 40%): If the payment reference contains a valid DesisPay student ID, this is the strongest signal.
• Phone number match (weighted score: 25%): We map the sender's mobile money number to registered parent phone numbers in the system.
• Fuzzy name match (weighted score: 20%): Natural language processing parses reference text to extract student names and matches them against the school roster using Levenshtein distance scoring.
• Amount pattern match (weighted score: 10%): If the amount corresponds exactly to a known fee structure item or outstanding balance, this adds confidence.
• Historical pattern match (weighted score: 5%): If this phone number has previously paid for a specific student, we factor in that relationship.

A payment is auto-matched when the composite confidence score exceeds 85%. Payments scoring between 60-85% are flagged for quick manual review with the top three suggested matches. Payments below 60% enter a review queue with full context for the bursar.

The Matching Pipeline: What Happens in Those 3 Seconds

Let me walk you through exactly what happens from the moment a parent confirms a mobile money payment to the moment the student's balance updates.

Second 0.0 — Payment Initiated: Parent confirms MTN MoMo payment of UGX 800,000 with reference "Nakamya Grace P5 fees."

Second 0.5 — Callback Received: MTN's API sends a webhook to our Payment Ingestion Layer. The raw payload is validated, deduplicated, and transformed into a Payment Event.

Second 1.0 — Matching Begins: The Payment Event enters the Matching Engine. Three parallel processes fire simultaneously:

• Phone number lookup against the parent registry.
• Reference text parsing and fuzzy name matching against all students at the target school.
• Amount analysis against outstanding fee balances.

Second 1.5 — Score Calculation: The weighted signals converge. In this case: phone number matches Grace Nakamya's registered parent (25%), "Nakamya Grace" fuzzy-matches "Grace Nakamya" in P5 roster (20%), and UGX 800,000 matches her outstanding tuition balance exactly (10%). Student ID was not provided (0%). Historical pattern confirms this number paid for Grace last term (5%). Total: 60% + confidence boost for exact amount = 88%. Auto-match threshold met.

Second 2.0 — Ledger Update: The payment is posted to Grace Nakamya's fee account. Her outstanding balance is recalculated. The school's income ledger is updated. An audit trail entry is created.

Second 2.5 — Notifications Dispatched: Three notifications fire: an SMS to the parent confirming receipt and new balance, a push notification to the school bursar's dashboard, and an update to Grace's student profile visible to her class teacher.

Second 3.0 — Complete: The entire process is finished. Grace's account is current. The parent has confirmation. The school's books are balanced.

Handling Edge Cases: Where the Real Engineering Lives

The happy path is straightforward. The true complexity — and the true value — of our reconciliation engine lies in how it handles edge cases.

Partial Payments and Instalment Tracking

Many Ugandan parents pay fees in two, three, or even five instalments per term. Our system maintains a fee obligation graph for each student: a structured breakdown of every fee item (tuition, boarding, lunch, uniform, etc.) and the payments allocated against each.

When a partial payment arrives, the engine uses a configurable allocation waterfall defined by the school. For example:

1. First, apply to mandatory fees (tuition, examination).
2. Then, apply to boarding and meals.
3. Finally, apply to optional items (transport, extracurriculars).

Schools can customise this waterfall through the admin dashboard, and the engine respects it automatically for every payment.

Overpayments and Credit Balances

When a payment exceeds the total outstanding balance, the excess is automatically posted as a credit balance on the student's account and carried forward to the next term. Parents are notified of the credit, and the school's financial report clearly separates earned revenue from advance payments.

Duplicate Transaction Detection

Network issues in Uganda occasionally cause mobile money callbacks to fire twice for the same transaction. Our deduplication layer uses a combination of transaction ID, amount, timestamp, and source number to identify and suppress duplicates before they enter the matching pipeline. In production, this layer catches approximately 0.3% of all incoming callbacks — a small percentage, but one that would cause significant reconciliation errors without protection.

Reliability and Fault Tolerance

A reconciliation engine is only as good as its uptime. If payments cannot be processed, schools and parents lose trust immediately. Here is how we ensure reliability.

• Queue-based architecture: Every payment event is persisted to a durable message queue before processing begins. If any downstream service fails, the event is retried automatically — up to five times with exponential backoff.
• Idempotent processing: Every operation in the pipeline is idempotent, meaning it produces the same result regardless of how many times it runs. This makes retries safe.
• Multi-region deployment: Our infrastructure runs across two availability zones with automatic failover. Even if an entire data centre goes offline, reconciliation continues uninterrupted.
• 99.97% uptime: Over the past 12 months, the reconciliation engine has maintained 99.97% uptime, with the longest single outage lasting 11 minutes.

"As an engineer, I appreciate that DesisPay's system does not just work — it works reliably. We process over 15,000 transactions per day during peak enrolment season, and the engine has never dropped a single payment." — David Okello, CTO, DesisPay

Results: What Real-Time Reconciliation Means for Schools

The impact of automated reconciliation goes far beyond saving the bursar's time. Here are the measurable outcomes we have observed across our school network:

• Reconciliation time reduced by 98%: From an average of 42 hours per term to less than 1 hour (for manual review queue items only).
• Payment misallocation reduced to 0.1%: Down from 15% in manual systems.
• Parent complaints reduced by 73%: Because payment confirmations are instant, parents no longer need to call the school to verify.
• Fee collection rates improved by 22%: When parents can see exactly what they owe and what they have paid in real time, they pay more consistently.
• Audit preparation time reduced by 90%: Every transaction is logged with full provenance, making regulatory and board audits straightforward.

What Comes Next: The Reconciliation Roadmap

We are not done. Real-time reconciliation is the foundation, and we are building aggressively on top of it:

• Predictive fee collection: Using payment history patterns to forecast which students are likely to have outstanding balances and alerting schools early.
• Cross-school reconciliation: For parents with children at multiple DesisPay schools, a single payment will be automatically split and allocated across schools based on predefined rules.
• Bank statement auto-import: Optical character recognition (OCR) for bank statements, allowing schools that still receive some payments via direct deposit to import and reconcile them automatically.
• Open API for third parties: We are building a reconciliation API that will allow third-party school management systems to leverage our matching engine without migrating to the full DesisPay platform.

Real-time reconciliation is not a luxury — it is the minimum standard that Ugandan schools deserve. Every shilling a parent sends should be accounted for instantly, accurately, and transparently. That is the promise of DesisPay, and that is what our reconciliation engine delivers every single day.