# QUICK START: Fix Manual Payments in 5 Minutes

## 🚀 Fast Track Solution

### 1️⃣ Diagnose (1 minute)

```bash
# SSH into production server
ssh user@grazuri.uzuriapps.xyz

# Navigate to project
cd /path/to/grazuri/

# Quick check
python quick_ipn_check.py
```

**Expected output if broken:**
```
❌ PROBLEM: No IPNs received!
   → SasaPay is NOT sending payment notifications
```

---

### 2️⃣ Fix in SasaPay Portal (3 minutes)

1. **Open browser** → https://merchant.sasapay.co.ke/ (or your SasaPay portal URL)

2. **Login** with merchant credentials

3. **Navigate to:**
   ```
   Settings → IPN Configuration
   (or similar menu item)
   ```

4. **Enter IPN URL:**
   ```
   https://grazuri.uzuriapps.xyz/payments/sasapay/ipn/
   ```

5. **Click:** 
   - ☑️ Enable IPN
   - 💾 Save
   - ✓ Verify (if button exists)

---

### 3️⃣ Test (1 minute)

1. **Make test payment:**
   - Amount: KES 10
   - BillRef: Use borrower phone (e.g., +254722909678)

2. **Wait:** 1-2 minutes for IPN to arrive

3. **Check:**
   ```bash
   python quick_ipn_check.py
   ```

**Expected output when fixed:**
```
✅ System appears healthy
   → IPNs being received and processed
```

4. **Verify in admin:**
   - Go to: https://grazuri.uzuriapps.xyz/loans/repayments/
   - Latest payment should show: **⚡ Auto (SasaPay)**

---

## 🎯 That's It!

Once IPN URL is configured:
- ✅ Payments will automatically record
- ✅ Staff won't need to enter manually
- ✅ SMS will still send (as before)
- ✅ All receipts auto-generated

---

## 📱 Visual Comparison

### BEFORE (Current - Broken)
```
Customer pays via M-Pesa
         ↓
    SasaPay receives
         ↓
    ❌ NO IPN sent (not configured)
         ↓
Staff sees SMS notification
         ↓
Staff manually enters payment
         ↓
Shows as "Manual" ❌
```

### AFTER (Fixed)
```
Customer pays via M-Pesa
         ↓
    SasaPay receives
         ↓
    ✅ IPN sent to your webhook
         ↓
    Auto-creates payment
         ↓
    Auto-sends SMS
         ↓
Shows as "⚡ Auto (SasaPay)" ✅
```

---

## 🆘 If Test Fails

If test payment doesn't create automatic payment:

```bash
# Run full diagnostic
python diagnose_production_ipn.py
```

This will show you:
- ✅ If IPN arrived (means URL is configured correctly)
- ⚠️ Why it failed to match borrower
- 🔍 Specific errors and how to fix them

Common issues:
1. **Phone format mismatch** → Standardize borrowers to +254 format
2. **No active loan** → Expected for processing fees
3. **BillRef empty** → Tell customers to use their phone as BillRef

---

## 📊 Monitor Daily

Quick check: `python quick_ipn_check.py` (10 seconds)

Or visit: `https://grazuri.uzuriapps.xyz/payments/sasapay/ipn-gaps/`

Should be empty or show only expected failures (processing fees, fully paid loans).

---

## 🎓 Files Reference

| Script | Use When | Runtime |
|--------|----------|---------|
| `quick_ipn_check.py` | Daily monitoring | 10 sec |
| `diagnose_production_ipn.py` | Troubleshooting issues | 2 min |
| `FIX_MANUAL_PAYMENTS_GUIDE.md` | Detailed solutions | Reference |

---

## ✨ Expected Results

After fixing IPN configuration, you should see:

**In admin panel:**
- July 23+ payments: **⚡ Auto (SasaPay)**
- July 22 and earlier: Manual (historical, cannot change)

**In quick check:**
```
📨 IPNs received from SasaPay: 15
💰 Payments recorded:
   ⚡ Automatic: 15
   ✋ Manual: 0
✅ System appears healthy
```

**Staff workflow:**
- Before: Receive SMS → Manually enter payment (5 min per payment)
- After: Nothing! Payment auto-records (0 min) ✨

---

**Start now:** SSH into production and run `python quick_ipn_check.py`