# M-Pesa Multi-Branch Setup Guide

## Overview
Your system is configured with two M-Pesa paybills:
- **Main Branch**: 4086675
- **Juja Office**: 4159523

## Problem: Main Branch Not Receiving Payments

If Juja is receiving payments but Main is not, the most likely cause is that **callback URLs have not been registered with Safaricom for the Main branch shortcode (4086675)**.

## Solution Steps

### Step 1: Verify Branch Configuration
Run the diagnostic script:
```bash
python diagnose_mpesa_setup.py
```

This will show:
- Branch configurations
- Recent transactions by shortcode
- Callback statistics

### Step 2: Ensure Branch Credentials Are Set
Run the setup script:
```bash
python setup_branch_mpesa.py
```

This will configure both branches with the correct credentials.

### Step 3: Register Callback URLs with Safaricom

**CRITICAL**: You MUST register callback URLs for EACH paybill shortcode separately.

#### Callback URLs to Register:

**Validation URL:**
```
https://yourdomain.com/payments/callback/validation/
```

**Confirmation URL:**
```
https://yourdomain.com/payments/callback/confirmation/
```

Replace `yourdomain.com` with your actual domain.

#### How to Register (Production):

1. **Log into Safaricom M-Pesa Portal**
   - Go to https://org.ke.m-pesa.com/
   - Use your organization credentials

2. **Navigate to API Management**
   - Go to the C2B section
   - Look for "Register C2B URLs" or "Configure C2B"

3. **Register for Shortcode 4086675 (Main Branch)**
   - Select shortcode: 4086675
   - Validation URL: Your validation URL
   - Confirmation URL: Your confirmation URL
   - Response Type: Completed
   - Save

4. **Register for Shortcode 4159523 (Juja Branch)**
   - Select shortcode: 4159523
   - Validation URL: Your validation URL (same URL!)
   - Confirmation URL: Your confirmation URL (same URL!)
   - Response Type: Completed
   - Save

#### Using Safaricom API (Alternative):

You can also register URLs programmatically using the Safaricom API. See `register_mpesa_urls.py` for a script to do this.

### Step 4: Test Both Paybills

1. **Test Main Branch (4086675)**
   - Make a small payment (e.g., KES 10)
   - Use any ID number registered in the system
   - Check the admin panel for incoming transactions

2. **Test Juja Branch (4159523)**
   - Make a small payment (e.g., KES 10)
   - Verify it still works

### Step 5: Monitor Callbacks

Go to the admin panel:
- Navigate to Payments → M-Pesa Callbacks
- Filter by recent date
- Check if callbacks are being received for shortcode 4086675

## Common Issues and Solutions

### Issue 1: Callbacks Not Received
**Symptoms**: No transactions appear for shortcode 4086675

**Solutions**:
1. Verify callback URLs are registered correctly
2. Check if your server is accessible from the internet
3. Ensure SSL certificate is valid (M-Pesa requires HTTPS)
4. Check firewall rules allow Safaricom IPs

### Issue 2: Payments Received but Not Processed
**Symptoms**: Transactions appear but status is "pending" or "failed"

**Solutions**:
1. Check the callback logs for error messages
2. Verify borrower ID numbers match exactly
3. Ensure borrower has active loans
4. Check processing notes in transaction details

### Issue 3: Wrong Branch Receiving Payments
**Symptoms**: Payments go to wrong branch

**Solutions**:
1. Verify branch shortcode configuration
2. Check customer is using correct paybill number
3. Review transaction `business_short_code` field

## Technical Details

### How Branch Filtering Works

1. **Payment Callback**: M-Pesa sends `BusinessShortCode` in callback
2. **Transaction Creation**: System saves this in `business_short_code` field
3. **Branch Filtering**: Views filter by `business_short_code` to show only relevant branch transactions
4. **Unconfirmed Payments**: Also filtered by branch shortcode

### Database Fields

- `Branch.mpesa_shortcode`: The paybill number for this branch
- `MpesaTransaction.business_short_code`: The paybill that received the payment
- Branch filtering uses: `filter(mpesa_transaction__business_short_code=branch.mpesa_shortcode)`

## Verification Checklist

- [ ] Both branches have `mpesa_shortcode` configured
- [ ] Both branches have credentials set
- [ ] Callback URLs registered for shortcode 4086675
- [ ] Callback URLs registered for shortcode 4159523
- [ ] SSL certificate is valid
- [ ] Server is accessible from internet
- [ ] Test payment made to 4086675
- [ ] Test payment made to 4159523
- [ ] Both test payments appear in admin panel
- [ ] Transactions filtered correctly by branch

## Support

If issues persist:
1. Check M-Pesa Go logs in Safaricom portal
2. Review server logs for errors
3. Contact Safaricom support with shortcode 4086675
4. Verify paybill is active and accepting payments