# Bulk Deposit - Member Matching Fields

## Current Matching Logic

The bulk deposit system matches members from your CSV/Excel file using the following fields (in order of priority):

### 1. Reference Number (Highest Priority)
The system looks for these column names (case-insensitive, spaces/hyphens are normalized):
- `reference_number`
- `reference`
- `ref_number`
- `ref`
- `member_reference`
- `loyalaid`

**Format Examples:**
- "Loyalaid/0001" → matches member with reference "Loyalaid/0001"
- "0001" → matches member with reference "Loyalaid/0001" (prefix is optional)
- "LOYALAID/0001" → matches (case-insensitive)

**How it works:**
- Removes "Loyalaid/" prefix if present
- Removes "/" characters
- Converts to lowercase for comparison
- Matches against member's `reference_number` field

### 2. ID Number
The system looks for these column names:
- `id_number`
- `id`
- `id_no`
- `national_id`
- `passport`
- `identity_number`

**Format:** Exact match required (case-sensitive for the value, but column name is case-insensitive)

### 3. Email Address
The system looks for these column names:
- `email`
- `e_mail`
- `email_address`

**Format:** Exact match required (case-sensitive for the value, but column name is case-insensitive)

### 4. Account Number (Lowest Priority)
The system looks for these column names:
- `account_number`
- `account`
- `account_no`
- `bank_account`
- `standard_bank_account`
- `fnb_bank_account`
- `nedbank_account`
- `post_bank_account`

**Format:** Matches against any of the member's bank account fields:
- `standard_bank_account`
- `fnb_bank_account`
- `nedbank_account`
- `post_bank_account`

## Column Name Normalization

All column names are normalized before matching:
1. Converted to lowercase
2. Spaces, hyphens, and dots replaced with underscores
3. Quotes removed

**Examples:**
- "Reference Number" → `reference_number`
- "Reference-Number" → `reference_number`
- "Reference.Number" → `reference_number`
- "REFERENCE NUMBER" → `reference_number`
- "Email Address" → `email_address`

## Matching Process

For each row in your CSV/Excel file:

1. **First**, tries to match by Reference Number
   - If found and match successful → uses that member
   - If not found → continues to next method

2. **Second**, tries to match by ID Number
   - If found and match successful → uses that member
   - If not found → continues to next method

3. **Third**, tries to match by Email
   - If found and match successful → uses that member
   - If not found → continues to next method

4. **Fourth**, tries to match by Account Number
   - If found and match successful → uses that member
   - If not found → member not matched (row skipped)

## Payment Detection

After matching a member, the system determines if they paid by checking:

1. **Status Column** - Looks for columns named:
   - `status`, `Status`, `STATUS`, `payment_status`, `Payment Status`
   - Values indicating "Paid": "paid", "yes", "y", "1", "true", "received", "success"
   - Values indicating "Unpaid": "unpaid", "no", "n", "0", "false", "pending", "failed"

2. **Amount Column** - Looks for columns named:
   - `amount`, `Amount`, `AMOUNT`, `payment_amount`, `Payment Amount`
   - If amount > 0 → considered as paid
   - If amount = 0 or empty → considered as unpaid

3. **Default**: If payment status cannot be determined → defaults to "Paid"

## Points Calculation

Once a member is matched and payment status is determined:

- **If Paid**: Points = Member's subscription plan `points_per_month`
  - M100 plan → 100 points
  - M200 plan → 200 points
  - M300 plan → 300 points
  - M400 plan → 400 points
  - M500 plan → 500 points
  - M600 plan → 600 points
  - M700+ plan → 700 points

- **If Unpaid**: Points = 0 (member will be unchecked by default)

## Example CSV/Excel Format

```csv
Reference Number,ID Number,Email,Account Number,Amount,Status
Loyalaid/0001,1234567890,member1@example.com,123456789,100,Paid
Loyalaid/0002,0987654321,member2@example.com,987654321,200,Yes
0003,1122334455,member3@example.com,112233445,0,Unpaid
```

**This will match:**
- Row 1: Member with reference "Loyalaid/0001" → 100 points (if M100 plan)
- Row 2: Member with reference "Loyalaid/0002" → 200 points (if M200 plan)
- Row 3: Member with reference "Loyalaid/0003" → 0 points (unpaid, unchecked)

## Troubleshooting

If members are not being matched:

1. **Check the logs**: `storage/logs/laravel.log`
   - Look for "Finding member for row" entries
   - Check "row_keys" to see what columns were found
   - Check "Member not found for row" entries

2. **Verify column names**: Ensure at least one matching column exists

3. **Verify data values**: 
   - Reference numbers must match exactly (after normalization)
   - ID numbers must match exactly
   - Emails must match exactly
   - Account numbers must match exactly

4. **Check for extra spaces**: The system trims values, but ensure your data is clean

5. **Test with one row**: Upload a file with just one known member to test matching

