# Manual Payment Matching Guide

## Overview
This feature allows administrators to manually match M-Pesa payments to borrowers when automatic matching fails. This is particularly useful when:
- A borrower makes a payment without using their ID number
- The ID number in the payment doesn't match any registered borrower
- The payment was made before the borrower registered their ID number

## How to Use

### 1. Access the Callbacks Page
Navigate to: `https://branchbusinessadvance.co.ke/payments/callbacks/`

### 2. Identify Unmatched Payments
Look for payments marked with:
- ⚠️ **Not matched** label in the "Who Paid" column
- These are payments that couldn't be automatically linked to a borrower

### 3. Match a Payment

#### Option A: Quick Match from Table
1. Find the unmatched payment in the table
2. Click the **"👤 Match Payer"** button in the "Who Paid" column
3. A modal will appear with payment details

#### Option B: Match from Details Modal
1. Click the **"👁️ View Details"** button for the callback
2. In the details modal, click **"👤 Match to Borrower"** button

### 4. Select the Borrower
1. In the matching modal, you'll see:
   - Payment amount
   - Phone number used
   - Bill reference number
   - Transaction time

2. Use the search box to find the borrower:
   - Type the borrower's name
   - Type their ID number
   - Type their phone number

3. Select the correct borrower from the dropdown

4. Click **"✓ Match & Process Payment"**

### 5. What Happens Next
The system will:
1. Link the payment to the selected borrower
2. Update the bill reference number to match the borrower's ID
3. Automatically attempt to process the payment
4. Create a repayment if the borrower has an active loan
5. Show a success message with the receipt number

## Success Messages

### ✓ Full Success
```
Payment successfully matched to [Borrower Name] and processed! 
Receipt: [Receipt Number]
```
The payment was matched and a repayment was created.

### ⚠️ Partial Success
```
Payment matched to [Borrower Name] but no repayment created. 
Status: [Status]
```
The payment was matched but couldn't create a repayment (e.g., no active loan).

### ✕ Error
```
Payment matched but processing failed: [Error Message]
```
The payment was matched but there was an error during processing.

## Important Notes

1. **Verification**: Always verify the payment amount and borrower details before matching
2. **Active Loans**: The borrower must have an active loan for a repayment to be created
3. **Audit Trail**: All manual matches are logged with the admin's name in the processing notes
4. **Irreversible**: Once matched and processed, the action cannot be undone automatically
5. **Branch Filtering**: The page respects branch filtering - you'll only see payments for your selected branch

## Troubleshooting

### Payment matched but no repayment created
**Possible reasons:**
- Borrower has no active loans
- All loans are fully paid
- Loan is in a non-active status (rejected, cancelled, etc.)

**Solution:** Check the borrower's loan status in their profile

### Cannot find the borrower in the dropdown
**Possible reasons:**
- Borrower account is inactive
- Borrower role is not set to "borrower"
- Borrower hasn't been created yet

**Solution:** 
1. Create the borrower account first
2. Ensure their role is set to "borrower"
3. Ensure their account is active

### Error during processing
**Solution:**
1. Check the error message in the alert
2. Verify the borrower's loan status
3. Try the "↷ Retry" button after fixing any issues
4. Contact system administrator if the error persists

## Related Features

- **Retry Matching**: Use the "↷ Retry" button to re-attempt automatic matching (useful if ID was added after payment)
- **View Details**: Click the eye icon to see full callback and transaction details
- **Repayments Page**: View all processed repayments at `/loans/repayments/`

## Security

- Only staff members with admin privileges can access this feature
- All manual matches are logged with the admin's user ID
- Processing notes include who performed the manual match

## API Endpoint

**URL:** `/payments/transactions/<transaction_id>/manual-match/`  
**Method:** POST  
**Parameters:**
- `borrower_id` (required): UUID of the borrower to match

**Response:** Redirects back to callbacks page with success/error message