╔══════════════════════════════════════════════════════════════════════════════╗
║                    MANUAL PAYMENT MATCHING - VISUAL GUIDE                    ║
╚══════════════════════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: Callbacks Page - Before Matching                                     │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ M-Pesa Callback Logs                                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│ Time          | Type    | Transaction | Who Paid          | Amount | Actions│
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK123456   │ John Doe          │ 5,000  │ 👁️ 🔄 │
│ 14:30:25      │         │ ID: 12345   │ ID: 12345678      │        │        │
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK789012   │ ⚠️ Not matched    │ 3,000  │ 👁️ 🔄 │
│ 13:15:10      │         │ ID: 67890   │ Bill Ref: 67890   │        │        │
│               │         │             │ [👤 Match Payer]  │        │        │  ← NEW BUTTON!
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK345678   │ Jane Smith        │ 2,500  │ 👁️ 🔄 │
│ 12:00:00      │         │ ID: 54321   │ ID: 87654321      │        │        │
└─────────────────────────────────────────────────────────────────────────────┘


┌──────────────────────────────────────────────────────────────────────────────┐
│ STEP 2: Click "Match Payer" Button                                           │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                   👤 Manually Match Payment to Borrower                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ ℹ️ Payment Details:                                                  │   │
│  │                                                                       │   │
│  │ 💰 Amount: KES 3,000.00                                              │   │
│  │ 📱 Phone: 254712345678                                               │   │
│  │ 🆔 Bill Ref: 67890                                                   │   │
│  │ 🕐 Time: 2025-01-20 13:15:10                                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│  Select Borrower: *                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ Type to search borrowers...                                          │   │  ← SEARCH BOX
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ -- Select a borrower --                                              │   │
│  │ Alice Wanjiku (ID: 12345678) - 0712345678                           │   │
│  │ Bob Kamau (ID: 23456789) - 0723456789                               │   │
│  │ Carol Akinyi (ID: 34567890) - 0734567890                            │   │  ← DROPDOWN
│  │ David Omondi (ID: 45678901) - 0745678901                            │   │
│  │ ...                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ ⚠️ Important: This will:                                             │   │
│  │ • Link this payment to the selected borrower                         │   │
│  │ • Attempt to process the payment automatically                       │   │
│  │ • Create a repayment if the borrower has an active loan             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│                    [ Cancel ]  [ ✓ Match & Process Payment ]                │
│                                                                               │
└─────────────────────────────────────────────────────────────────────────────┘


┌──────────────────────────────────────────────────────────────────────────────┐
│ STEP 3: Search for Borrower                                                  │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                   👤 Manually Match Payment to Borrower                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  Payment Details: [Same as above]                                            │
│                                                                               │
│  Select Borrower: *                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ carol                                                                 │   │  ← USER TYPES
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ -- Select a borrower --                                              │   │
│  │ Carol Akinyi (ID: 34567890) - 0734567890                            │   │  ← FILTERED!
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│  Warning: [Same as above]                                                    │
│                                                                               │
│                    [ Cancel ]  [ ✓ Match & Process Payment ]                │
│                                                                               │
└─────────────────────────────────────────────────────────────────────────────┘


┌──────────────────────────────────────────────────────────────────────────────┐
│ STEP 4: After Successful Match                                               │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ ✓ Success!                                                                   │
│ Payment successfully matched to Carol Akinyi and processed!                  │
│ Receipt: RCP-2025-001234                                                     │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ M-Pesa Callback Logs                                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│ Time          | Type    | Transaction | Who Paid          | Amount | Actions│
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK123456   │ John Doe          │ 5,000  │ 👁️ 🔄 │
│ 14:30:25      │         │ ID: 12345   │ ID: 12345678      │        │        │
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK789012   │ Carol Akinyi      │ 3,000  │ 👁️ 🔄 │  ← NOW MATCHED!
│ 13:15:10      │         │ ID: 67890   │ ID: 34567890      │        │        │
│               │         │             │ 🧾 RCP-2025-001234│        │        │  ← REPAYMENT CREATED!
│───────────────┼─────────┼─────────────┼───────────────────┼────────┼────────│
│ 2025-01-20    │ ✓ Conf  │ SLK345678   │ Jane Smith        │ 2,500  │ 👁️ 🔄 │
│ 12:00:00      │         │ ID: 54321   │ ID: 87654321      │        │        │
└─────────────────────────────────────────────────────────────────────────────┘


┌──────────────────────────────────────────────────────────────────────────────┐
│ ALTERNATIVE: Match from Details Modal                                        │
└──────────────────────────────────────────────────────────────────────────────┘

Click the 👁️ (View Details) button, then in the modal:

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Callback Details - Confirmation                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  Transaction Details          │  Borrower Information                        │
│  • Transaction ID: SLK789012  │  ⚠️ Borrower not matched                    │
│  • Amount: KES 3,000.00       │                                              │
│  • Status: Confirmed          │  [👤 Match to Borrower]  ← CLICK THIS       │
│  • Bill Ref: 67890            │                                              │
│  • Phone: 254712345678        │                                              │
│                                                                               │
│  ✕ No Repayment Created                                                      │
│  Reason: No borrower matched                                                 │
│                                                                               │
│  ℹ️ If the ID number was added after this payment was made, click Retry     │
│     to match it now.                                                         │
│                                                                               │
│  [↷ Retry Matching]                                                          │
│                                                                               │
│  Raw Callback Data: [...]                                                    │
│                                                                               │
│                                              [ Close ]                        │
└─────────────────────────────────────────────────────────────────────────────┘


╔══════════════════════════════════════════════════════════════════════════════╗
║                              KEY FEATURES                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝

✓ SEARCH FUNCTIONALITY
  • Type name, ID number, or phone number
  • Real-time filtering of borrower list
  • Easy to find the right borrower

✓ PAYMENT DETAILS
  • Shows amount, phone, bill ref, time
  • Helps verify you're matching the right payment
  • Clear visual presentation

✓ AUTOMATIC PROCESSING
  • Matches payment to borrower
  • Processes payment automatically
  • Creates repayment if borrower has active loan
  • Shows success message with receipt number

✓ AUDIT TRAIL
  • Logs admin username in processing notes
  • Records who performed the manual match
  • Tracks in processed_by field

✓ ERROR HANDLING
  • Clear error messages if something goes wrong
  • Suggests solutions for common issues
  • Allows retry if needed


╔══════════════════════════════════════════════════════════════════════════════╗
║                           COMMON SCENARIOS                                    ║
╚══════════════════════════════════════════════════════════════════════════════╝

SCENARIO 1: Payment without ID number
  Problem: Customer paid without entering their ID number
  Solution: Use "Match Payer" to manually link to their account
  Result: Payment processed, repayment created

SCENARIO 2: Payment before registration
  Problem: Customer paid before registering their ID in system
  Solution: Add ID to customer profile, then use "Match Payer"
  Result: Payment matched and processed

SCENARIO 3: Wrong ID number used
  Problem: Customer entered wrong ID number when paying
  Solution: Use "Match Payer" to link to correct account
  Result: Payment corrected and processed

SCENARIO 4: Multiple loans
  Problem: Customer has multiple loans, payment needs allocation
  Solution: Match payment, system will allocate to oldest loan first
  Result: Payment applied to appropriate loan


╔══════════════════════════════════════════════════════════════════════════════╗
║                              QUICK TIPS                                       ║
╚══════════════════════════════════════════════════════════════════════════════╝

💡 TIP 1: Use the search box to quickly find borrowers
   Type any part of their name, ID, or phone number

💡 TIP 2: Verify payment amount before matching
   Make sure it matches what the borrower says they paid

💡 TIP 3: Check borrower has active loan
   If no repayment is created, borrower might not have active loan

💡 TIP 4: Use "View Details" for more information
   Click 👁️ to see full transaction and callback details

💡 TIP 5: All matches are logged
   Your username is recorded in the processing notes for audit
