# M-Pesa Production Deployment Checklist

## 🚨 Critical Files to Upload to Production Server

### 1. Templates (REQUIRED - Missing on Production)

Upload these template files to `/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/`:

- ✅ `callbacks.html` - View M-Pesa callback logs
- ✅ `transaction_detail.html` - View transaction details
- ✅ `reprocess_transaction.html` - Reprocess failed transactions
- ✅ `my_payments.html` - Borrower payment history

**Upload Command (from local machine):**
```bash
# Using FTP/cPanel File Manager, upload these files:
templates/payments/callbacks.html
templates/payments/transaction_detail.html
templates/payments/reprocess_transaction.html
templates/payments/my_payments.html
```

**Or using SCP (if you have SSH access):**
```bash
scp templates/payments/callbacks.html acbptxvs@branchbusinessadvance.co.ke:/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/
scp templates/payments/transaction_detail.html acbptxvs@branchbusinessadvance.co.ke:/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/
scp templates/payments/reprocess_transaction.html acbptxvs@branchbusinessadvance.co.ke:/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/
scp templates/payments/my_payments.html acbptxvs@branchbusinessadvance.co.ke:/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/
```

### 2. Updated Standalone Script (OPTIONAL)

Upload the updated `register_mpesa_urls_standalone.py` to production:
- Fixed non-interactive mode issue
- Can now run via cPanel without manual confirmation

### 3. Management Command (Already Uploaded)

The Django management command should already be in:
`/home/acbptxvs/public_html/branchbusinessadvance.co.ke/payments/management/commands/register_mpesa_urls.py`

---

## 📝 Step-by-Step Deployment

### Step 1: Upload Templates via cPanel

1. Login to cPanel
2. Go to **File Manager**
3. Navigate to: `/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/`
4. Click **Upload**
5. Upload these 4 files:
   - `callbacks.html`
   - `transaction_detail.html`
   - `reprocess_transaction.html`
   - `my_payments.html`

### Step 2: Verify Templates Uploaded

Check that files exist:
```
/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/callbacks.html
/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/transaction_detail.html
/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/reprocess_transaction.html
/home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/my_payments.html
```

### Step 3: Restart Application

In cPanel:
1. Go to **Setup Python App**
2. Find your application
3. Click **Restart**

Or via command line:
```bash
touch /home/acbptxvs/public_html/branchbusinessadvance.co.ke/passenger_wsgi.py
```

### Step 4: Test the Pages

Visit these URLs to confirm templates are working:
- https://branchbusinessadvance.co.ke/payments/callbacks/
- https://branchbusinessadvance.co.ke/payments/transactions/
- https://branchbusinessadvance.co.ke/payments/my-payments/

---

## 🧪 Testing M-Pesa Integration

### Test 1: Check Callback Endpoint

The URLs are already registered with M-Pesa:
- Validation: `https://branchbusinessadvance.co.ke/payments/callback/validation/`
- Confirmation: `https://branchbusinessadvance.co.ke/payments/callback/confirmation/`

### Test 2: Make a Test Payment

1. **Use a registered borrower's phone number**
2. Send payment via M-Pesa:
   - Go to M-Pesa
   - Select Lipa na M-Pesa → Pay Bill
   - Business Number: **4159523**
   - Account Number: **Loan Number** (optional)
   - Amount: **10 KES** (test amount)
   - Enter PIN and confirm

3. **Check the results:**
   - Visit: https://branchbusinessadvance.co.ke/payments/callbacks/
   - You should see validation and confirmation callbacks
   - Visit: https://branchbusinessadvance.co.ke/payments/transactions/
   - You should see the transaction created
   - Check the loan - balance should be updated

### Test 3: Verify Automatic Processing

After making a payment:

1. **Check Transaction Status:**
   - Go to `/payments/transactions/`
   - Find your test transaction
   - Status should be "Confirmed" or "Processed"

2. **Check Loan Updated:**
   - Go to the borrower's loan
   - Outstanding balance should be reduced
   - Repayment record should exist

3. **Check Notifications:**
   - Borrower should receive notification
   - Loan officer should be notified

---

## 🔍 Troubleshooting

### Issue: Templates Still Not Found

**Cause:** Files not uploaded or wrong location

**Solution:**
1. Verify files are in correct directory
2. Check file permissions (should be 644)
3. Restart the application
4. Clear browser cache

### Issue: Payments Not Reflecting

**Possible Causes:**

1. **Phone number not registered**
   - Solution: Ensure borrower's phone number in system matches M-Pesa phone

2. **Callbacks not reaching server**
   - Check: `/payments/callbacks/` - should show incoming requests
   - If empty, M-Pesa can't reach your server
   - Verify URLs are publicly accessible

3. **Loan matching failed**
   - Check transaction detail page for error messages
   - Verify borrower has an active loan
   - Check processing notes

4. **SSL/HTTPS issues**
   - M-Pesa requires valid HTTPS
   - Verify SSL certificate is valid

### Issue: Callback Logs Empty

**Cause:** M-Pesa can't reach your server

**Solutions:**
1. Verify URLs are publicly accessible
2. Test URLs in browser - should return JSON
3. Check firewall settings
4. Verify SSL certificate is valid
5. Re-register URLs if needed

---

## 📊 Monitoring After Deployment

### Daily Checks

1. **Check Callback Logs:**
   ```
   https://branchbusinessadvance.co.ke/payments/callbacks/
   ```
   - Should show incoming M-Pesa requests
   - All should be marked "Processed"

2. **Check Failed Transactions:**
   ```
   https://branchbusinessadvance.co.ke/payments/transactions/?status=failed
   ```
   - Investigate any failed transactions
   - Reprocess if needed

3. **Check Dashboard:**
   ```
   https://branchbusinessadvance.co.ke/payments/dashboard/
   ```
   - View statistics
   - Monitor success rate

### Weekly Tasks

1. Review unmatched payments
2. Check for duplicate transactions
3. Verify all payments processed correctly
4. Update borrower phone numbers if needed

---

## 🔐 Security Checklist

- ✅ URLs registered with M-Pesa
- ✅ HTTPS enabled with valid SSL
- ✅ Credentials stored in database (not hardcoded)
- ✅ Callback endpoints log all requests
- ✅ Transaction processing is idempotent (no duplicates)
- ✅ Staff-only access to admin pages
- ✅ Borrowers can only see their own payments

---

## 📞 Support Contacts

### If Payments Not Working:

1. **Check Django Logs:**
   - cPanel → Error Logs
   - Look for M-Pesa related errors

2. **Check M-Pesa Portal:**
   - https://developer.safaricom.co.ke/
   - Verify URLs are registered
   - Check API status

3. **Contact Safaricom:**
   - If callbacks not arriving
   - If API errors persist

---

## ✅ Deployment Verification

After uploading templates, verify:

- [ ] All 4 template files uploaded
- [ ] Files in correct directory
- [ ] Application restarted
- [ ] `/payments/callbacks/` page loads
- [ ] `/payments/transactions/` page loads
- [ ] Test payment made and processed
- [ ] Callback logs show incoming requests
- [ ] Transaction appears in list
- [ ] Loan balance updated
- [ ] Borrower notified

---

## 🎯 Quick Fix Commands

### Restart Application
```bash
touch /home/acbptxvs/public_html/branchbusinessadvance.co.ke/passenger_wsgi.py
```

### Check Template Directory
```bash
ls -la /home/acbptxvs/public_html/branchbusinessadvance.co.ke/templates/payments/
```

### View Recent Callbacks (Django Shell)
```python
from payments.models import MpesaCallback
callbacks = MpesaCallback.objects.all()[:5]
for c in callbacks:
    print(f"{c.created_at}: {c.callback_type} - Processed: {c.processed}")
```

### View Recent Transactions (Django Shell)
```python
from loans.models import MpesaTransaction
transactions = MpesaTransaction.objects.all()[:5]
for t in transactions:
    print(f"{t.trans_id}: KES {t.amount} - {t.status}")
```

---

**Last Updated:** November 2025  
**Status:** Ready for Production Deployment