Documentation

Everything you need to integrate, use, and get the most out of MOMO LENS.

Cash-Up System Guide

The Cash-Up system helps you reconcile daily cash transactions, track denominations, calculate variances, and maintain accurate end-of-day records.

Overview

Cash-Up is an essential daily process for businesses that handle cash transactions. It helps you verify that the cash in your till matches your recorded sales, identify discrepancies, and maintain accurate financial records.

Key Benefits

  • Daily cash reconciliation and variance tracking
  • Denomination breakdown for accurate counting
  • Shift management and session tracking
  • Complete cash-up history for audit purposes
  • PDF export for accounting records
  • Integration with sales and reconciliation

How Cash-Up Works

Cash-up reconciliation matches your recorded sales with the actual money you've received. The system calculates expected amounts from your sales records and compares them with what you physically count or verify.

Expected Amounts from Sales

The system automatically calculates expected amounts by analyzing all of today's sales and grouping them by payment method:

  • Cash Sales: Sum of all sales recorded with "Cash" payment method
  • MTN MoMo: Sum of all sales recorded with "MTN MoMo" payment method
  • Airtel Money: Sum of all sales recorded with "Airtel Money" payment method
  • Zamtel Kwacha: Sum of all sales recorded with "Zamtel Kwacha" payment method
  • Other Mobile Money: Sum of sales from other providers (M-Pesa, OPay, etc.)
  • Digital Payments: Sum of card/Flutterwave payments

This gives you the exact amount you should have received based on your sales records.

Actual Amounts (What You Count)

You then count or verify what you actually received:

  • Physical Cash: Count all cash in your till
  • Mobile Money: Verify amounts received via each provider (check SMS confirmations or mobile money balance)
  • Provider Breakdown: Enter actual amounts for each mobile money provider separately (MTN, Airtel, Zamtel, etc.)

The system shows expected amounts next to each field, making it easy to see what you should have received.

Variance Calculation (Matching)

The system automatically calculates variance (difference) for each payment method:

  • Positive Variance: More money than expected (overage) - shown in blue
  • Negative Variance: Less money than expected (shortage) - shown in red
  • Zero Variance: Perfect match - shown in green
  • Sorted by Largest: Variances are sorted by absolute amount, so largest discrepancies appear first

This matching process helps you identify discrepancies between what you recorded in sales and what you actually received.

Starting a Cash-Up Session

To begin your end-of-day cash-up reconciliation:

  1. Navigate to Cash-Up

    From the Reconciliation Hub, tap the "Cash-Up" action card. The system loads today's sales data and calculates expected amounts automatically.

  2. Review Expected Amounts

    The screen shows expected amounts calculated from today's sales, broken down by payment method (Cash, MTN MoMo, Airtel Money, Zamtel Kwacha, etc.). You can expand the "Sales Breakdown" to see individual sales that contributed to each amount.

  3. Count Physical Cash

    Physically count all cash in your till. Tap the Cash card to enter the actual amount you counted. The system shows the expected amount next to the input field for easy comparison.

  4. Verify Mobile Money Amounts

    For each mobile money provider (MTN, Airtel, Zamtel, etc.), verify the actual amount you received. Check SMS confirmations or your mobile money balance. Tap each provider card to enter the actual amount. The system shows the expected amount based on sales recorded with that payment method.

  5. Review Variance Automatically

    As you enter actual amounts, the system immediately calculates variance for each payment method. Variances are sorted by largest discrepancy first, making it easy to spot issues. Green means balanced, blue means over, red means short.

  6. Investigate Discrepancies

    If you see variances, review the sales breakdown to identify which sales might be causing the discrepancy. Check for unrecorded sales, incorrect payment method selection, or counting errors.

  7. Add Notes (Optional)

    Add any notes explaining variances, unusual transactions, or other relevant information. This helps with future reference and investigation.

  8. Complete Cash-Up

    Review all variances and notes, then tap "Complete Cash-Up". The system saves the reconciliation record with all expected, actual, and variance amounts for each payment method.

Expected Amounts Breakdown

The cash-up screen shows expected amounts calculated from your sales, broken down by payment method:

Expected From Today's Sales

The system automatically calculates what you should have received based on all sales recorded today, grouped by payment method.

  • Total expected amount (sum of all payment methods)
  • Cash expected (from cash sales)
  • Mobile money expected (broken down by provider: MTN, Airtel, Zamtel, etc.)
  • Number of sales recorded

Sales Breakdown (Expandable)

Tap "Show Sales Breakdown" to see detailed information:

  • Individual sales that contributed to each payment method
  • Sale numbers, amounts, and timestamps
  • Customer information for each sale
  • Payment method for each sale

This helps you verify that expected amounts match your sales records and identify which sales contributed to each payment method total.

Matching Sales with Mobile Money

The cash-up system matches your sales records with actual mobile money receipts:

How Matching Works

The system matches expected mobile money amounts (from sales) with actual amounts you verify:

  1. Expected: System sums all sales recorded with a specific mobile money provider (e.g., all "MTN MoMo" sales)
  2. Actual: You verify the amount you actually received from that provider (check SMS or mobile money balance)
  3. Variance: System calculates the difference - this shows if there's a mismatch

This matching process helps identify if sales were recorded incorrectly, payments weren't received, or if there are other discrepancies.

Provider-Specific Matching

The system tracks each mobile money provider separately for accurate matching:

Zambia Providers

  • MTN MoMo - tracked separately
  • Airtel Money - tracked separately
  • Zamtel Kwacha - tracked separately

Each provider has its own expected/actual/variance calculation

Other Providers

  • M-Pesa, OPay, PalmPay, Paga, etc.
  • Grouped under "Mobile Money" (generic)
  • Still matched against sales records

All non-Zambia providers are grouped but still matched accurately

Variance Analysis

Variances show discrepancies between expected (from sales) and actual (what you counted) amounts. Understanding variances helps identify issues:

Zero Variance (Balanced)

Perfect match between expected and actual. This means your sales records match what you actually received. Shown in green - this is the ideal outcome.

Positive Variance (Overage)

More money than expected. Common causes: customers overpaid, sales recorded with wrong payment method, unrecorded cash payments, or counting errors. Small overages may be normal, but large ones should be investigated.

Negative Variance (Shortage)

Less money than expected. Common causes: sales recorded but payment not received, incorrect payment method selected, incorrect change given, or counting errors. All shortages should be investigated and documented.

Variance Sorted by Largest

The system automatically sorts variances by absolute amount (largest first), making it easy to spot the biggest discrepancies first. This helps prioritize investigation.

Shift Management

Cash-up sessions are tied to shifts, allowing you to track multiple cash-ups per day:

  • Each cash-up session has a unique session number
  • Sessions track start and end times
  • Multiple sessions can be created per day for shift changes
  • Session history is maintained for audit purposes
  • Each session can have its own notes and variance tracking

Cash-Up History

All cash-up sessions are saved and can be reviewed:

Session Details

View session number, date, time, expected cash, actual cash, and variance for each session.

Trends & Analysis

Track variance trends over time, identify patterns, and spot recurring issues.

Export & Reporting

Export cash-up reports to PDF for accounting, tax purposes, or management review.

How Cash-Up Matches Sales with Payments

The cash-up system performs matching by comparing sales records with actual receipts. The matching is based on the payment method you selected during checkout:

Sales-to-Payment Matching Flow

The complete matching process from sale to reconciliation:

  1. During Sale (Checkout): You select a payment method (Cash, MTN MoMo, Airtel Money, etc.) and for mobile money, enter customer phone number
  2. Sale Created: Sale is saved with the selected payment method (e.g., `paymentMethod: "MTN_MOMO"`)
  3. Cash-Up Time: System analyzes all today's sales and groups them by payment method
  4. Expected Calculation: Sums all sales with same payment method (e.g., all "MTN_MOMO" sales = expected MTN MoMo amount)
  5. You Verify Actual: Count physical cash and verify mobile money receipts for each provider
  6. System Matches: Compares expected (from sales) vs actual (what you counted) for each payment method
  7. Variance Shows Discrepancies: Differences highlight mismatches that need investigation

Key Point: The payment method you select during checkout determines which "bucket" the sale goes into. If you select "MTN MoMo", it contributes to expected MTN MoMo. If you select "Airtel Money", it goes to Airtel Money. This is why selecting the correct payment method during checkout is critical for accurate reconciliation!

Best Practices for Accurate Matching

Select Correct Payment Method During Checkout

When processing a sale in checkout, always select the correct payment method that matches how the customer actually paid. If the customer paid via MTN MoMo, select "MTN MoMo" - not "Airtel Money" or "Cash". The payment method you select is saved with the sale and determines which expected amount bucket it contributes to in cash-up. Selecting the wrong payment method will cause mismatches.

Enter Customer Phone for Mobile Money

For mobile money payments, always enter the customer's phone number when prompted. This phone number is saved with the sale and helps with payment tracking and verification. It also helps you identify which customer made which payment when reconciling.

Verify Mobile Money Receipts

For mobile money, verify actual amounts by checking SMS confirmations or your mobile money balance. Don't rely on memory - check the actual receipts to ensure accurate matching.

Count Cash Carefully

Take time to count physical cash accurately. Double-check your count if variance is significant. Consider counting by denominations (notes and coins) for accuracy and easier verification.

Review Sales Breakdown

Use the "Show Sales Breakdown" feature to see which sales contributed to each expected amount. This helps verify calculations and identify specific sales that might be causing variances.

Investigate Variances Promptly

When you see variances, investigate immediately while details are fresh. Check if sales were recorded correctly, if payments were actually received, or if there are counting errors. Document findings in notes.

Document All Variances

Always add notes explaining significant variances. Include what you found during investigation, any corrections made, or reasons for the discrepancy. This creates an audit trail.

Perform Cash-Up Daily

Complete cash-up at the end of each business day or shift. Regular reconciliation helps catch issues early and maintains accurate financial records.

Review Trends Over Time

Regularly review cash-up history to identify patterns. Consistent variances in the same payment method may indicate systematic issues (e.g., always selecting wrong payment method, or provider-specific problems).

Troubleshooting Matching Issues

Large Variance in Mobile Money

If mobile money variance is large, check: (1) Did you select the correct payment method during checkout? (e.g., if customer paid via MTN but you selected Airtel, that causes mismatch) (2) Did you actually receive the payments? (3) Are you checking the right mobile money account/provider? (4) Review the sales breakdown to see which sales contributed to the expected amount - verify each sale's payment method matches how customer actually paid.

Expected Amount Doesn't Match Sales

If expected amounts seem wrong, expand the sales breakdown to verify: (1) Are all today's sales included? (2) Are payment methods recorded correctly? (3) Check for refunds that might have affected totals. The expected amount should equal the sum of all sales for that payment method.

Multiple Providers Showing Variance

If multiple mobile money providers show variances, this often indicates incorrect payment method selection during checkout. A common issue: customer paid via "Airtel Money" but you selected "MTN MoMo" in checkout. This causes the sale to contribute to expected MTN MoMo (but you received Airtel Money), creating mismatches in both providers. Always verify the payment method matches how the customer actually paid before completing checkout.

No Expected Amount for Provider

If a mobile money provider shows zero expected amount, it means no sales were recorded with that payment method today. If you received payments via that provider, check if sales were recorded with a different payment method (common mistake).

API Integration

For programmatic access to cash-up data:

POST /api/v1/merchants/{merchantId}/cash-up/sessions
Authorization: Bearer YOUR_TOKEN

{
  "notes": "End of day cash-up"
}

PUT /api/v1/merchants/{merchantId}/cash-up/sessions/{sessionId}/complete
Authorization: Bearer YOUR_TOKEN

{
  "actualCash": 1250.50,
  "notes": "All denominations counted"
}

GET /api/v1/merchants/{merchantId}/cash-up/sessions
Authorization: Bearer YOUR_TOKEN

Next Steps