Feature: Implement Tende Pay CSV export for ticket expenses with formatter, endpoints, and tests

docs/features/tende_pay_csv_export.md

@@ -0,0 +1,199 @@
+# Tende Pay CSV Export Feature
+
+## Overview
+
+The ticket expense CSV export has been updated to generate files in **Tende Pay bulk payment format**, compatible with the Tende Pay financial management system.
+
+## What Changed
+
+### Before
+- Custom CSV format with columns: `technician_name`, `phone_number`, `account_name`, `total_amount`, `expense_count`, `date`, `tickets_summary`, `categories_summary`, `expense_ids`
+- Phone numbers included `+` prefix
+- Separate summary fields for tickets and categories
+
+### After
+- **Tende Pay standard format** with columns:
+  - `NAME` - Technician or vendor name
+  - `ID NUMBER` - User's ID number (from users.id_number)
+  - `PHONE NUMBER` - Normalized phone (254XXXXXXXXX, no +)
+  - `AMOUNT` - Total payment amount
+  - `PAYMENT MODE` - MPESA, BANK, PAYBILL, or BUYGOODS
+  - `BANK (Optional)` - Bank name for bank transfers
+  - `BANK ACCOUNT NO (Optional)` - Bank account number
+  - `PAYBILL BUSINESS NO (Optional)` - Paybill business number
+  - `PAYBILL ACCOUNT NO (Optional)` - Paybill account number
+  - `BUY GOODS TILL NO (Optional)` - Till number for buy goods
+  - `BILL PAYMENT BILLER CODE (Optional)` - Not currently used
+  - `BILL PAYMENT ACCOUNT NO (Optional)` - Not currently used
+  - `NARRATION (OPTIONAL)` - Single narration field with expense details
+
+## Payment Method Mapping
+
+| Our System | Tende Pay Mode | Notes |
+|------------|----------------|-------|
+| `send_money` | `MPESA` | M-Pesa send money |
+| `bank_transfer` | `BANK` | Bank account transfer |
+| `paybill` | `PAYBILL` | M-Pesa paybill |
+| `till_number` | `BUYGOODS` | M-Pesa till number |
+| `pochi_la_biashara` | `MPESA` | Treated as regular M-Pesa |
+| `cash` | ❌ Not supported | Skipped with warning |
+
+## Phone Number Normalization
+
+Phone numbers are automatically normalized to Tende Pay format:
+- `+254712345678` → `254712345678` (remove +)
+- `0712345678` → `254712345678` (convert 07 to 254)
+- Spaces and dashes are removed
+- Invalid formats result in warnings and row skipping
+
+## Narration Format
+
+Single narration field combining all expense details:
+
+```
+Expenses 2024-12-05: Ticket #ABC123 (Transport 500, Materials 1000) | Ticket #XYZ789 (Meals 300) - 3 items, 1800 KES
+```
+
+- Maximum 200 characters (truncated with "..." if longer)
+- Includes date, ticket references, categories, item count, and total
+
+## Data Validation
+
+Before export, each expense group is validated:
+- ✅ Has payment_method
+- ✅ Has payment_details
+- ✅ Payment method is supported (not cash)
+- ⚠️ Has ID number (warns if missing, but doesn't block)
+- ✅ Phone number is valid format (for MPESA)
+- ✅ Bank details complete (for BANK)
+- ✅ Paybill details complete (for PAYBILL)
+- ✅ Till number present (for BUYGOODS)
+
+## Warnings
+
+Expenses are skipped with warnings if:
+- Payment method is `cash` (not supported by Tende Pay)
+- Payment details are missing or incomplete
+- Phone number format is invalid
+- User has no ID number (warning only, still exported with empty ID field)
+
+Warnings are appended as comments at the end of the CSV file:
+```csv
+# WARNINGS:
+# User John Doe has no ID number - exported with empty ID field
+# Skipped 2 expense(s) for Jane Smith: No payment details found
+```
+
+## API Endpoints
+
+### 1. Export by Date Range
+```
+POST /api/v1/ticket-expenses/export-for-payment
+  ?from_date=2024-12-01
+  &to_date=2024-12-08
+  &project_id=uuid (optional)
+  &ticket_id=uuid (optional)
+  &user_id=uuid (optional)
+```
+
+### 2. Bulk Export by IDs
+```
+POST /api/v1/ticket-expenses/bulk-export
+  ?expense_ids=uuid1
+  &expense_ids=uuid2
+  &expense_ids=uuid3
+```
+
+Both endpoints:
+- Return Tende Pay formatted CSV
+- Mark expenses as paid (irreversible)
+- Set payment_reference to `CSV_EXPORT_{timestamp}_{user_id}`
+- Include warning count in response headers
+
+## File Naming
+
+- Date range export: `tende_pay_expenses_2024-12-01_2024-12-08_20241210_143022.csv`
+- Bulk export: `tende_pay_bulk_20241210_143022.csv`
+
+## Implementation Details
+
+### New Service: `TendePayFormatter`
+
+Location: `src/app/services/tende_pay_formatter.py`
+
+Key methods:
+- `normalize_phone()` - Phone number normalization
+- `validate_payment_details()` - Payment details validation
+- `build_narration()` - Single narration field builder
+- `format_payment_row()` - Format agent payment row
+- `format_vendor_payment_row()` - Format vendor payment row
+
+### Updated Services
+
+**`TicketExpenseService.export_for_payment()`**
+- Now uses `TendePayFormatter` for row generation
+- Enhanced validation and error handling
+- Better warning messages
+
+### Updated API Endpoints
+
+**`/export-for-payment`** and **`/bulk-export`**
+- Updated CSV column headers to match Tende Pay format
+- Updated filename prefix to `tende_pay_`
+
+## Testing
+
+Unit tests: `tests/unit/test_tende_pay_formatter.py`
+
+Test coverage:
+- ✅ Phone normalization (all formats)
+- ✅ Payment mode mapping
+- ✅ Payment details validation (all methods)
+- ✅ Narration building and truncation
+- ✅ Agent payment row formatting
+- ✅ Vendor payment row formatting
+
+## Migration Notes
+
+### Breaking Changes
+- CSV format completely changed
+- Old format is no longer supported
+- Any integrations expecting old format will break
+
+### Data Requirements
+- Users should have `id_number` populated (optional but recommended)
+- All expenses should have `payment_method` and `payment_details`
+- Phone numbers should be in valid Kenyan format
+
+### Backward Compatibility
+- None - this is a breaking change
+- Old CSV format is not available
+- Decision: Clean break is better than maintaining two formats
+
+## Example CSV Output
+
+```csv
+NAME,ID NUMBER,PHONE NUMBER,AMOUNT,PAYMENT MODE,BANK (Optional),BANK ACCOUNT NO (Optional),PAYBILL BUSINESS NO (Optional),PAYBILL ACCOUNT NO (Optional),BUY GOODS TILL NO (Optional),BILL PAYMENT BILLER CODE (Optional),BILL PAYMENT ACCOUNT NO (Optional),NARRATION (OPTIONAL)
+John Doe,12345678,254712345678,1500.00,MPESA,,,,,,,,Expenses 2024-12-05: Ticket #ABC123 (Transport 500, Materials 1000) - 2 items, 1500 KES
+Jane Smith,,254722000001,2000.00,BANK,Equity Bank,0123456789,,,,,,"Expenses 2024-12-05: Ticket #XYZ789 (Materials 2000) - 1 items, 2000 KES"
+VENDOR: ABC Hardware,,,5000.00,BUYGOODS,,,,,123456,,,Vendor payment 2024-12-06: Ticket #VENDOR001 - Materials 5000 KES
+
+# WARNINGS:
+# User Jane Smith has no ID number - exported with empty ID field
+```
+
+## Future Enhancements
+
+Potential improvements:
+1. Add `BILL_PAYMENT` support if needed (GOTV, KPLC, etc.)
+2. Add export format parameter (`?format=tende`) for backward compatibility
+3. Add dry-run mode to preview export without marking as paid
+4. Add batch size limits for large exports
+5. Add export history tracking
+6. Add Tende Pay API integration for automatic upload
+
+## References
+
+- Tende Pay template: `tests/fixtures/tende_bulk_payment_template.csv`
+- Database schema: `supabase/migrations/20251120123500_init_schema.sql`
+- Payment methods: `src/app/schemas/ticket_expense.py`

src/app/api/v1/ticket_expenses.py

@@ -1055,7 +1055,9 @@ def bulk_export_expenses(
             key = (expense.incurred_by_user_id, expense.expense_date)
         grouped[key].append(expense)
     
-    # Build CSV rows
+    # Build Tende Pay CSV rows
+    from app.services.tende_pay_formatter import TendePayFormatter
+    
     csv_rows = []
     warnings = []
     payment_reference = f"CSV_EXPORT_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}_{current_user.id}"
@@ -1065,26 +1067,41 @@ def bulk_export_expenses(
         
         # Handle vendor payments
         if first_expense.payment_recipient_type == "vendor":
-            row = TicketExpenseService._build_vendor_payment_row(first_expense, warnings)
-            if row:
+            try:
+                # Validate payment details
+                is_valid, error_msg = TendePayFormatter.validate_payment_details(
+                    payment_method=first_expense.payment_method,
+                    payment_details=first_expense.payment_details,
+                    user_name=f"Vendor (Expense {first_expense.id})"
+                )
+                
+                if not is_valid:
+                    warnings.append(error_msg)
+                    continue
+                
+                # Format vendor row
+                row = TendePayFormatter.format_vendor_payment_row(
+                    expense=first_expense,
+                    payment_method=first_expense.payment_method,
+                    payment_details=first_expense.payment_details
+                )
                 csv_rows.append(row)
+                
+            except Exception as e:
+                logger.error(f"Failed to format vendor payment row: {str(e)}")
+                warnings.append(f"Skipped vendor expense {first_expense.id}: {str(e)}")
             continue
         
         # Handle agent payments
         user = first_expense.incurred_by_user
         expense_date = first_expense.expense_date
         
-        # Get payment details
-        phone_number = None
-        account_name = None
-        
-        if first_expense.payment_details:
-            phone_number = first_expense.payment_details.get("phone_number") or \
-                          first_expense.payment_details.get("account_number")
-            account_name = first_expense.payment_details.get("recipient_name") or \
-                          first_expense.payment_details.get("account_name")
+        # Get payment method and details from first expense
+        payment_method = first_expense.payment_method
+        payment_details = first_expense.payment_details
         
-        if not phone_number or not account_name:
+        # If no payment details on expense, try to get from financial account
+        if not payment_method or not payment_details:
             financial_account = db.query(UserFinancialAccount).filter(
                 UserFinancialAccount.user_id == user.id,
                 UserFinancialAccount.is_primary == True,
@@ -1094,41 +1111,53 @@ def bulk_export_expenses(
             
             if financial_account:
                 if financial_account.payout_method == "mobile_money":
-                    phone_number = financial_account.mobile_money_phone
-                    account_name = financial_account.mobile_money_account_name or user.name
+                    payment_method = "send_money"
+                    payment_details = {
+                        "phone_number": financial_account.mobile_money_phone,
+                        "recipient_name": financial_account.mobile_money_account_name or user.name
+                    }
                 elif financial_account.payout_method == "bank_transfer":
-                    phone_number = financial_account.bank_account_number
-                    account_name = financial_account.bank_account_name
+                    payment_method = "bank_transfer"
+                    payment_details = {
+                        "bank_name": financial_account.bank_name,
+                        "account_number": financial_account.bank_account_number,
+                        "account_name": financial_account.bank_account_name
+                    }
         
-        if not phone_number or not account_name:
+        # Validate payment details
+        if not payment_method or not payment_details:
             warnings.append(f"Skipped {len(group_expenses)} expense(s) for {user.name}: No payment details")
             continue
         
-        # Calculate totals
-        total_amount = sum(e.total_cost for e in group_expenses)
-        expense_count = len(group_expenses)
-        expense_ids_str = [str(e.id) for e in group_expenses]
+        is_valid, error_msg = TendePayFormatter.validate_payment_details(
+            payment_method=payment_method,
+            payment_details=payment_details,
+            user_name=user.name
+        )
+        
+        if not is_valid:
+            warnings.append(f"Skipped {len(group_expenses)} expense(s) for {user.name}: {error_msg}")
+            continue
         
-        # Build summaries
+        # Format agent payment row
         try:
-            tickets_summary = TicketExpenseService._build_tickets_summary(group_expenses)
-            categories_summary = TicketExpenseService._build_categories_summary(group_expenses)
+            row = TendePayFormatter.format_payment_row(
+                expenses=group_expenses,
+                user=user,
+                expense_date=expense_date,
+                payment_method=payment_method,
+                payment_details=payment_details,
+                user_id_number=user.id_number
+            )
+            csv_rows.append(row)
+            
+            # Warn if user has no ID number
+            if not user.id_number:
+                warnings.append(f"User {user.name} has no ID number - exported with empty ID field")
+                
         except Exception as e:
-            logger.error(f"Failed to build summaries for user {user.name}: {str(e)}")
-            tickets_summary = f"{len(group_expenses)} expenses"
-            categories_summary = f"Total: {float(total_amount)} KES"
-        
-        csv_rows.append({
-            "technician_name": user.name,
-            "phone_number": phone_number,
-            "account_name": account_name,
-            "total_amount": float(total_amount),
-            "expense_count": expense_count,
-            "date": expense_date.isoformat(),
-            "tickets_summary": tickets_summary,
-            "categories_summary": categories_summary,
-            "expense_ids": ",".join(expense_ids_str)
-        })
+            logger.error(f"Failed to format payment row for {user.name}: {str(e)}")
+            warnings.append(f"Skipped {len(group_expenses)} expense(s) for {user.name}: {str(e)}")
     
     # Mark as paid
     try:
@@ -1152,12 +1181,24 @@ def bulk_export_expenses(
             detail="Failed to mark expenses as paid"
         )
     
-    # Generate CSV
+    # Generate Tende Pay CSV
     output = io.StringIO()
     if csv_rows:
+        # Tende Pay column order (must match template exactly)
         fieldnames = [
-            "technician_name", "phone_number", "account_name", "total_amount",
-            "expense_count", "date", "tickets_summary", "categories_summary", "expense_ids"
+            "NAME",
+            "ID NUMBER",
+            "PHONE NUMBER",
+            "AMOUNT",
+            "PAYMENT MODE",
+            "BANK (Optional)",
+            "BANK ACCOUNT NO (Optional)",
+            "PAYBILL BUSINESS NO (Optional)",
+            "PAYBILL ACCOUNT NO (Optional)",
+            "BUY GOODS TILL NO (Optional)",
+            "BILL PAYMENT BILLER CODE (Optional)",
+            "BILL PAYMENT ACCOUNT NO (Optional)",
+            "NARRATION (OPTIONAL)"
         ]
         writer = csv.DictWriter(output, fieldnames=fieldnames)
         writer.writeheader()
@@ -1169,7 +1210,7 @@ def bulk_export_expenses(
             output.write(f"# {warning}\n")
     
     output.seek(0)
-    filename = f"expense_payments_bulk_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
+    filename = f"tende_pay_bulk_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
     
     # Send notification to initiator about export completion
     if csv_rows:
@@ -1278,19 +1319,24 @@ def export_expenses_for_payment(
         user_id=user_id
     )
     
-    # Generate CSV
+    # Generate Tende Pay CSV
     output = io.StringIO()
     if csv_rows:
+        # Tende Pay column order (must match template exactly)
         fieldnames = [
-            "technician_name",
-            "phone_number",
-            "account_name",
-            "total_amount",
-            "expense_count",
-            "date",
-            "tickets_summary",
-            "categories_summary",
-            "expense_ids"
+            "NAME",
+            "ID NUMBER",
+            "PHONE NUMBER",
+            "AMOUNT",
+            "PAYMENT MODE",
+            "BANK (Optional)",
+            "BANK ACCOUNT NO (Optional)",
+            "PAYBILL BUSINESS NO (Optional)",
+            "PAYBILL ACCOUNT NO (Optional)",
+            "BUY GOODS TILL NO (Optional)",
+            "BILL PAYMENT BILLER CODE (Optional)",
+            "BILL PAYMENT ACCOUNT NO (Optional)",
+            "NARRATION (OPTIONAL)"
         ]
         
         writer = csv.DictWriter(output, fieldnames=fieldnames)
@@ -1305,7 +1351,7 @@ def export_expenses_for_payment(
     
     # Prepare response
     output.seek(0)
-    filename = f"expense_payments_{from_date.isoformat()}_{to_date.isoformat()}_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
+    filename = f"tende_pay_expenses_{from_date.isoformat()}_{to_date.isoformat()}_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
     
     return StreamingResponse(
         iter([output.getvalue()]),

src/app/services/tende_pay_formatter.py

@@ -0,0 +1,331 @@
+"""
+Tende Pay CSV Formatter
+
+Converts expense data to Tende Pay bulk payment CSV format.
+Handles payment method mapping, phone normalization, and narration building.
+"""
+
+from typing import List, Dict, Optional, Tuple
+from decimal import Decimal
+from datetime import date
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class TendePayFormatter:
+    """
+    Formatter for Tende Pay bulk payment CSV exports.
+    
+    Tende Pay supports these payment modes:
+    - MPESA: Mobile money (M-Pesa send money)
+    - BANK: Bank transfer
+    - PAYBILL: M-Pesa paybill
+    - BUYGOODS: M-Pesa till number (buy goods)
+    - BILL_PAYMENT: Bill payment (GOTV, KPLC, etc.) - not currently used
+    """
+    
+    # Payment method mapping: our system -> Tende Pay
+    PAYMENT_MODE_MAP = {
+        "send_money": "MPESA",
+        "bank_transfer": "BANK",
+        "paybill": "PAYBILL",
+        "till_number": "BUYGOODS",
+        "pochi_la_biashara": "MPESA",  # Treat as regular M-Pesa
+        "cash": None,  # Not supported by Tende Pay
+    }
+    
+    # Maximum narration length (conservative limit)
+    MAX_NARRATION_LENGTH = 200
+    
+    @staticmethod
+    def normalize_phone(phone: Optional[str]) -> str:
+        """
+        Normalize phone number to Tende Pay format (254XXXXXXXXX without +).
+        
+        Args:
+            phone: Phone number in various formats (+254..., 254..., 07...)
+            
+        Returns:
+            Normalized phone number (254XXXXXXXXX) or empty string
+        """
+        if not phone:
+            return ""
+        
+        # Remove +, spaces, dashes
+        normalized = phone.replace("+", "").replace(" ", "").replace("-", "")
+        
+        # Convert 07... to 2547...
+        if normalized.startswith("0"):
+            normalized = "254" + normalized[1:]
+        
+        # Validate format
+        if not normalized.startswith("254") or len(normalized) != 12:
+            logger.warning(f"Invalid phone number format: {phone} -> {normalized}")
+            return ""
+        
+        return normalized
+    
+    @staticmethod
+    def build_narration(
+        expenses: List,
+        expense_date: date,
+        max_length: int = MAX_NARRATION_LENGTH
+    ) -> str:
+        """
+        Build single narration field from multiple expenses.
+        
+        Format: "Expenses 2024-12-05: Ticket #ABC (Transport 500, Materials 1000) | Ticket #XYZ (Meals 300) - 3 items, 1800 KES"
+        
+        Args:
+            expenses: List of TicketExpense objects
+            expense_date: Date of expenses
+            max_length: Maximum narration length
+            
+        Returns:
+            Formatted narration string
+        """
+        from collections import defaultdict
+        
+        # Group by ticket
+        by_ticket = defaultdict(list)
+        total_amount = Decimal(0)
+        
+        for expense in expenses:
+            if expense.ticket:
+                ticket_ref = expense.ticket.ticket_name or str(expense.ticket.id)[:8]
+            else:
+                ticket_ref = "Unknown"
+            by_ticket[ticket_ref].append(expense)
+            total_amount += expense.total_cost
+        
+        # Build ticket summaries
+        ticket_parts = []
+        for ticket_ref, ticket_expenses in by_ticket.items():
+            expense_details = [
+                f"{e.category.title()} {float(e.total_cost)}"
+                for e in ticket_expenses
+            ]
+            ticket_parts.append(f"Ticket #{ticket_ref} ({', '.join(expense_details)})")
+        
+        # Build full narration
+        narration = (
+            f"Expenses {expense_date.isoformat()}: "
+            f"{' | '.join(ticket_parts)} - "
+            f"{len(expenses)} items, {float(total_amount)} KES"
+        )
+        
+        # Truncate if too long
+        if len(narration) > max_length:
+            truncated = narration[:max_length - 3] + "..."
+            logger.warning(f"Narration truncated from {len(narration)} to {max_length} chars")
+            return truncated
+        
+        return narration
+    
+    @staticmethod
+    def validate_payment_details(
+        payment_method: str,
+        payment_details: Optional[Dict],
+        user_name: str
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate payment details are complete for the payment method.
+        
+        Args:
+            payment_method: Payment method (send_money, bank_transfer, etc.)
+            payment_details: Payment details dict
+            user_name: User name for error messages
+            
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not payment_details:
+            return False, f"No payment details for {user_name}"
+        
+        if payment_method == "send_money":
+            phone = payment_details.get("phone_number")
+            if not phone:
+                return False, f"Missing phone number for {user_name}"
+            if not TendePayFormatter.normalize_phone(phone):
+                return False, f"Invalid phone number format for {user_name}: {phone}"
+            return True, None
+        
+        elif payment_method == "bank_transfer":
+            bank_name = payment_details.get("bank_name")
+            account_number = payment_details.get("account_number")
+            if not bank_name or not account_number:
+                return False, f"Missing bank details for {user_name}"
+            return True, None
+        
+        elif payment_method == "paybill":
+            business_number = payment_details.get("business_number")
+            account_number = payment_details.get("account_number")
+            if not business_number or not account_number:
+                return False, f"Missing paybill details for {user_name}"
+            return True, None
+        
+        elif payment_method == "till_number":
+            till_number = payment_details.get("till_number")
+            if not till_number:
+                return False, f"Missing till number for {user_name}"
+            return True, None
+        
+        elif payment_method == "pochi_la_biashara":
+            phone = payment_details.get("phone_number")
+            if not phone:
+                return False, f"Missing phone number for {user_name}"
+            if not TendePayFormatter.normalize_phone(phone):
+                return False, f"Invalid phone number format for {user_name}: {phone}"
+            return True, None
+        
+        elif payment_method == "cash":
+            return False, f"Cash payments not supported by Tende Pay for {user_name}"
+        
+        else:
+            return False, f"Unknown payment method '{payment_method}' for {user_name}"
+    
+    @staticmethod
+    def format_payment_row(
+        expenses: List,
+        user,
+        expense_date: date,
+        payment_method: str,
+        payment_details: Dict,
+        user_id_number: Optional[str] = None
+    ) -> Dict[str, str]:
+        """
+        Format a group of expenses into a Tende Pay CSV row.
+        
+        Args:
+            expenses: List of TicketExpense objects (grouped by user+date)
+            user: User object (incurred_by_user)
+            expense_date: Date of expenses
+            payment_method: Payment method (send_money, bank_transfer, etc.)
+            payment_details: Payment details dict
+            user_id_number: User's ID number (optional)
+            
+        Returns:
+            Dict with Tende Pay CSV columns
+        """
+        # Calculate totals
+        total_amount = sum(e.total_cost for e in expenses)
+        
+        # Build narration
+        narration = TendePayFormatter.build_narration(expenses, expense_date)
+        
+        # Map payment mode
+        payment_mode = TendePayFormatter.PAYMENT_MODE_MAP.get(payment_method)
+        if not payment_mode:
+            raise ValueError(f"Unsupported payment method: {payment_method}")
+        
+        # Base row structure (all Tende Pay columns)
+        row = {
+            "NAME": user.name,
+            "ID NUMBER": user_id_number or "",
+            "PHONE NUMBER": "",
+            "AMOUNT": float(total_amount),
+            "PAYMENT MODE": payment_mode,
+            "BANK (Optional)": "",
+            "BANK ACCOUNT NO (Optional)": "",
+            "PAYBILL BUSINESS NO (Optional)": "",
+            "PAYBILL ACCOUNT NO (Optional)": "",
+            "BUY GOODS TILL NO (Optional)": "",
+            "BILL PAYMENT BILLER CODE (Optional)": "",
+            "BILL PAYMENT ACCOUNT NO (Optional)": "",
+            "NARRATION (OPTIONAL)": narration
+        }
+        
+        # Fill in method-specific fields
+        if payment_mode == "MPESA":
+            phone = payment_details.get("phone_number")
+            row["PHONE NUMBER"] = TendePayFormatter.normalize_phone(phone)
+        
+        elif payment_mode == "BANK":
+            row["BANK (Optional)"] = payment_details.get("bank_name", "")
+            row["BANK ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+        
+        elif payment_mode == "PAYBILL":
+            row["PAYBILL BUSINESS NO (Optional)"] = payment_details.get("business_number", "")
+            row["PAYBILL ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+        
+        elif payment_mode == "BUYGOODS":
+            row["BUY GOODS TILL NO (Optional)"] = payment_details.get("till_number", "")
+        
+        return row
+    
+    @staticmethod
+    def format_vendor_payment_row(
+        expense,
+        payment_method: str,
+        payment_details: Dict
+    ) -> Dict[str, str]:
+        """
+        Format a vendor expense into a Tende Pay CSV row.
+        
+        Args:
+            expense: TicketExpense object
+            payment_method: Payment method
+            payment_details: Payment details dict
+            
+        Returns:
+            Dict with Tende Pay CSV columns
+        """
+        # Map payment mode
+        payment_mode = TendePayFormatter.PAYMENT_MODE_MAP.get(payment_method)
+        if not payment_mode:
+            raise ValueError(f"Unsupported payment method: {payment_method}")
+        
+        # Get vendor name
+        vendor_name = (
+            payment_details.get("business_name") or
+            payment_details.get("recipient_name") or
+            payment_details.get("account_name") or
+            "Unknown Vendor"
+        )
+        
+        # Build simple narration for single expense
+        if expense.ticket:
+            ticket_ref = expense.ticket.ticket_name or str(expense.ticket.id)[:8]
+        else:
+            ticket_ref = "Unknown"
+        
+        narration = (
+            f"Vendor payment {expense.expense_date.isoformat()}: "
+            f"Ticket #{ticket_ref} - {expense.category.title()} {float(expense.total_cost)} KES"
+        )
+        
+        # Base row structure
+        row = {
+            "NAME": f"VENDOR: {vendor_name}",
+            "ID NUMBER": "",  # Vendors don't have ID numbers
+            "PHONE NUMBER": "",
+            "AMOUNT": float(expense.total_cost),
+            "PAYMENT MODE": payment_mode,
+            "BANK (Optional)": "",
+            "BANK ACCOUNT NO (Optional)": "",
+            "PAYBILL BUSINESS NO (Optional)": "",
+            "PAYBILL ACCOUNT NO (Optional)": "",
+            "BUY GOODS TILL NO (Optional)": "",
+            "BILL PAYMENT BILLER CODE (Optional)": "",
+            "BILL PAYMENT ACCOUNT NO (Optional)": "",
+            "NARRATION (OPTIONAL)": narration
+        }
+        
+        # Fill in method-specific fields
+        if payment_mode == "MPESA":
+            phone = payment_details.get("phone_number")
+            row["PHONE NUMBER"] = TendePayFormatter.normalize_phone(phone)
+        
+        elif payment_mode == "BANK":
+            row["BANK (Optional)"] = payment_details.get("bank_name", "")
+            row["BANK ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+        
+        elif payment_mode == "PAYBILL":
+            row["PAYBILL BUSINESS NO (Optional)"] = payment_details.get("business_number", "")
+            row["PAYBILL ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+        
+        elif payment_mode == "BUYGOODS":
+            row["BUY GOODS TILL NO (Optional)"] = payment_details.get("till_number", "")
+        
+        return row

src/app/services/ticket_expense_service.py

@@ -1028,7 +1028,7 @@ class TicketExpenseService:
         user_id: Optional[UUID] = None
     ) -> Tuple[List[dict], List[str]]:
         """
-        Export approved unpaid expenses grouped by user+date for payment processing.
+        Export approved unpaid expenses in Tende Pay CSV format.
         Marks all exported expenses as paid.
         
         Args:
@@ -1042,7 +1042,7 @@ class TicketExpenseService:
             
         Returns:
             Tuple of (csv_rows, warnings)
-            - csv_rows: List of dicts with payment data
+            - csv_rows: List of dicts with Tende Pay CSV columns
             - warnings: List of warning messages
             
         Raises:
@@ -1050,6 +1050,7 @@ class TicketExpenseService:
         """
         from app.models.user_financial_account import UserFinancialAccount
         from app.models.ticket import Ticket
+        from app.services.tende_pay_formatter import TendePayFormatter
         from collections import defaultdict
         
         # Authorization: Only PM, dispatcher, or platform admin
@@ -1099,7 +1100,7 @@ class TicketExpenseService:
                 key = (expense.incurred_by_user_id, expense.expense_date)
             grouped[key].append(expense)
         
-        # Build CSV rows
+        # Build Tende Pay CSV rows
         csv_rows = []
         warnings = []
         payment_reference = f"CSV_EXPORT_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}_{current_user.id}"
@@ -1113,30 +1114,41 @@ class TicketExpenseService:
             
             # Handle vendor payments separately
             if first_expense.payment_recipient_type == "vendor":
-                row = TicketExpenseService._build_vendor_payment_row(
-                    expense=first_expense,
-                    warnings=warnings
-                )
-                if row:
+                try:
+                    # Validate payment details
+                    is_valid, error_msg = TendePayFormatter.validate_payment_details(
+                        payment_method=first_expense.payment_method,
+                        payment_details=first_expense.payment_details,
+                        user_name=f"Vendor (Expense {first_expense.id})"
+                    )
+                    
+                    if not is_valid:
+                        warnings.append(error_msg)
+                        continue
+                    
+                    # Format vendor row
+                    row = TendePayFormatter.format_vendor_payment_row(
+                        expense=first_expense,
+                        payment_method=first_expense.payment_method,
+                        payment_details=first_expense.payment_details
+                    )
                     csv_rows.append(row)
+                    
+                except Exception as e:
+                    logger.error(f"Failed to format vendor payment row: {str(e)}")
+                    warnings.append(f"Skipped vendor expense {first_expense.id}: {str(e)}")
                 continue
             
             # Handle agent payments
             user = first_expense.incurred_by_user
             expense_date = first_expense.expense_date
             
-            # Get payment details from first expense (should be same for all in group)
-            phone_number = None
-            account_name = None
-            
-            if first_expense.payment_details:
-                phone_number = first_expense.payment_details.get("phone_number") or \
-                              first_expense.payment_details.get("account_number")
-                account_name = first_expense.payment_details.get("recipient_name") or \
-                              first_expense.payment_details.get("account_name")
+            # Get payment method and details from first expense
+            payment_method = first_expense.payment_method
+            payment_details = first_expense.payment_details
             
-            # If no payment details, try to get from financial account
-            if not phone_number or not account_name:
+            # If no payment details on expense, try to get from financial account
+            if not payment_method or not payment_details:
                 financial_account = db.query(UserFinancialAccount).filter(
                     UserFinancialAccount.user_id == user.id,
                     UserFinancialAccount.is_primary == True,
@@ -1146,43 +1158,58 @@ class TicketExpenseService:
                 
                 if financial_account:
                     if financial_account.payout_method == "mobile_money":
-                        phone_number = financial_account.mobile_money_phone
-                        account_name = financial_account.mobile_money_account_name or user.name
+                        payment_method = "send_money"
+                        payment_details = {
+                            "phone_number": financial_account.mobile_money_phone,
+                            "recipient_name": financial_account.mobile_money_account_name or user.name
+                        }
                     elif financial_account.payout_method == "bank_transfer":
-                        phone_number = financial_account.bank_account_number
-                        account_name = financial_account.bank_account_name
+                        payment_method = "bank_transfer"
+                        payment_details = {
+                            "bank_name": financial_account.bank_name,
+                            "account_number": financial_account.bank_account_number,
+                            "account_name": financial_account.bank_account_name
+                        }
             
-            # Skip if still no payment details
-            if not phone_number or not account_name:
+            # Validate payment details
+            if not payment_method or not payment_details:
                 warnings.append(
                     f"Skipped {len(group_expenses)} expense(s) for {user.name} on {expense_date}: "
                     f"No payment details found"
                 )
                 continue
             
-            # Calculate totals
-            total_amount = sum(e.total_cost for e in group_expenses)
-            expense_count = len(group_expenses)
-            expense_ids = [str(e.id) for e in group_expenses]
-            
-            # Build tickets summary
-            tickets_summary = TicketExpenseService._build_tickets_summary(group_expenses)
+            is_valid, error_msg = TendePayFormatter.validate_payment_details(
+                payment_method=payment_method,
+                payment_details=payment_details,
+                user_name=user.name
+            )
             
-            # Build categories summary
-            categories_summary = TicketExpenseService._build_categories_summary(group_expenses)
+            if not is_valid:
+                warnings.append(
+                    f"Skipped {len(group_expenses)} expense(s) for {user.name} on {expense_date}: {error_msg}"
+                )
+                continue
             
-            # Build CSV row
-            csv_rows.append({
-                "technician_name": user.name,
-                "phone_number": phone_number,
-                "account_name": account_name,
-                "total_amount": float(total_amount),
-                "expense_count": expense_count,
-                "date": expense_date.isoformat(),
-                "tickets_summary": tickets_summary,
-                "categories_summary": categories_summary,
-                "expense_ids": ",".join(expense_ids)
-            })
+            # Format agent payment row
+            try:
+                row = TendePayFormatter.format_payment_row(
+                    expenses=group_expenses,
+                    user=user,
+                    expense_date=expense_date,
+                    payment_method=payment_method,
+                    payment_details=payment_details,
+                    user_id_number=user.id_number
+                )
+                csv_rows.append(row)
+                
+                # Warn if user has no ID number
+                if not user.id_number:
+                    warnings.append(f"User {user.name} has no ID number - exported with empty ID field")
+                    
+            except Exception as e:
+                logger.error(f"Failed to format payment row for {user.name}: {str(e)}")
+                warnings.append(f"Skipped {len(group_expenses)} expense(s) for {user.name}: {str(e)}")
         
         # Mark all expenses as paid (in transaction)
         try:
@@ -1196,7 +1223,7 @@ class TicketExpenseService:
             
             logger.info(
                 f"Exported {len(expenses)} expenses for payment by user {current_user.id}. "
-                f"Generated {len(csv_rows)} payment rows. Reference: {payment_reference}"
+                f"Generated {len(csv_rows)} Tende Pay payment rows. Reference: {payment_reference}"
             )
         except Exception as e:
             db.rollback()
@@ -1207,100 +1234,7 @@ class TicketExpenseService:
             )
         
         return csv_rows, warnings
-    
-    @staticmethod
-    def _build_vendor_payment_row(expense: TicketExpense, warnings: List[str]) -> Optional[dict]:
-        """Build CSV row for vendor payment"""
-        if not expense.payment_details:
-            warnings.append(
-                f"Skipped vendor expense {expense.id}: No payment details"
-            )
-            return None
-        
-        phone_number = expense.payment_details.get("phone_number") or \
-                      expense.payment_details.get("till_number") or \
-                      expense.payment_details.get("account_number")
-        account_name = expense.payment_details.get("recipient_name") or \
-                      expense.payment_details.get("business_name") or \
-                      expense.payment_details.get("account_name")
-        
-        if not phone_number or not account_name:
-            warnings.append(
-                f"Skipped vendor expense {expense.id}: Incomplete payment details"
-            )
-            return None
-        
-        # Build ticket summary for single expense
-        if expense.ticket:
-            ticket_ref = expense.ticket.ticket_name or str(expense.ticket.id)[:8]
-        else:
-            ticket_ref = "Unknown"
-        tickets_summary = f"Ticket {ticket_ref} (1 expense: {expense.category.title()} {float(expense.total_cost)} KES)"
-        
-        return {
-            "technician_name": f"VENDOR: {account_name}",
-            "phone_number": phone_number,
-            "account_name": account_name,
-            "total_amount": float(expense.total_cost),
-            "expense_count": 1,
-            "date": expense.expense_date.isoformat(),
-            "tickets_summary": tickets_summary,
-            "categories_summary": f"{expense.category.title()}: {float(expense.total_cost)} (1x)",
-            "expense_ids": str(expense.id)
-        }
-    
-    @staticmethod
-    def _build_tickets_summary(expenses: List[TicketExpense]) -> str:
-        """Build detailed tickets summary for CSV"""
-        from collections import defaultdict
-        
-        # Group by ticket
-        by_ticket = defaultdict(list)
-        for expense in expenses:
-            # Use ticket ID or name as reference
-            if expense.ticket:
-                ticket_ref = expense.ticket.ticket_name or str(expense.ticket.id)[:8]
-            else:
-                ticket_ref = "Unknown"
-            by_ticket[ticket_ref].append(expense)
-        
-        # Build summary for each ticket
-        ticket_summaries = []
-        for ticket_ref, ticket_expenses in by_ticket.items():
-            expense_details = []
-            ticket_total = Decimal(0)
-            
-            for expense in ticket_expenses:
-                expense_details.append(
-                    f"{expense.category.title()} {float(expense.total_cost)}"
-                )
-                ticket_total += expense.total_cost
-            
-            summary = f"Ticket {ticket_ref} ({len(ticket_expenses)} expenses: {', '.join(expense_details)} = {float(ticket_total)} KES)"
-            ticket_summaries.append(summary)
-        
-        return " | ".join(ticket_summaries)
-    
-    @staticmethod
-    def _build_categories_summary(expenses: List[TicketExpense]) -> str:
-        """Build categories summary for CSV"""
-        from collections import defaultdict
-        
-        # Group by category
-        by_category = defaultdict(list)
-        for expense in expenses:
-            by_category[expense.category].append(expense)
-        
-        # Build summary for each category
-        category_summaries = []
-        for category, cat_expenses in by_category.items():
-            total = sum(e.total_cost for e in cat_expenses)
-            count = len(cat_expenses)
-            category_summaries.append(
-                f"{category.title()}: {float(total)} ({count}x)"
-            )
-        
-        return " | ".join(category_summaries)
+
 
     
     @staticmethod

tests/fixtures/tende_bulk_payment_template.csv

@@ -0,0 +1,10 @@
+NAME,ID NUMBER,PHONE NUMBER,AMOUNT,PAYMENT MODE,BANK (Optional),BANK ACCOUNT NO (Optional),PAYBILL BUSINESS NO (Optional),PAYBILL ACCOUNT NO (Optional),BUY GOODS TILL NO (Optional),BILL PAYMENT BILLER CODE (Optional),BILL PAYMENT ACCOUNT NO (Optional),NARRATION (OPTIONAL)
+John Doe,12345678,254722000000,15,BANK,KCB BANK,123456789,,,,,,
+Jane Doe,12345678,254722000001,15,MPESA,,,,,,,,
+John Smith,12345678,254722000002,15,PAYBILL,,,888888,123456789,,,,
+Jane Smith,12345678,254722000003,15,BUYGOODS,,,,,123456789,,,
+Barbra Smith,12345678,254722000004,15,BILL_PAYMENT,,,,,,GOTV,123456789,
+,,,,,,,,,,,,
+,,,,,,,,,,,,
+,,,,,,,,,,,,
+,,,,,,,,,,,,

tests/unit/test_tende_pay_formatter.py

@@ -0,0 +1,310 @@
+"""
+Unit tests for Tende Pay CSV Formatter
+"""
+
+import pytest
+from datetime import date
+from decimal import Decimal
+from app.services.tende_pay_formatter import TendePayFormatter
+
+
+class TestPhoneNormalization:
+    """Test phone number normalization"""
+    
+    def test_normalize_with_plus(self):
+        """Should remove + prefix"""
+        assert TendePayFormatter.normalize_phone("+254712345678") == "254712345678"
+    
+    def test_normalize_without_plus(self):
+        """Should keep 254 format as is"""
+        assert TendePayFormatter.normalize_phone("254712345678") == "254712345678"
+    
+    def test_normalize_with_zero_prefix(self):
+        """Should convert 07... to 2547..."""
+        assert TendePayFormatter.normalize_phone("0712345678") == "254712345678"
+    
+    def test_normalize_empty(self):
+        """Should return empty string for None"""
+        assert TendePayFormatter.normalize_phone(None) == ""
+        assert TendePayFormatter.normalize_phone("") == ""
+    
+    def test_normalize_with_spaces(self):
+        """Should remove spaces"""
+        assert TendePayFormatter.normalize_phone("+254 712 345 678") == "254712345678"
+    
+    def test_normalize_invalid_format(self):
+        """Should return empty for invalid format"""
+        result = TendePayFormatter.normalize_phone("123456")
+        assert result == ""
+
+
+class TestPaymentModeMapping:
+    """Test payment method to Tende Pay mode mapping"""
+    
+    def test_send_money_maps_to_mpesa(self):
+        """send_money should map to MPESA"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["send_money"] == "MPESA"
+    
+    def test_bank_transfer_maps_to_bank(self):
+        """bank_transfer should map to BANK"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["bank_transfer"] == "BANK"
+    
+    def test_paybill_maps_to_paybill(self):
+        """paybill should map to PAYBILL"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["paybill"] == "PAYBILL"
+    
+    def test_till_number_maps_to_buygoods(self):
+        """till_number should map to BUYGOODS"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["till_number"] == "BUYGOODS"
+    
+    def test_pochi_maps_to_mpesa(self):
+        """pochi_la_biashara should map to MPESA"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["pochi_la_biashara"] == "MPESA"
+    
+    def test_cash_not_supported(self):
+        """cash should map to None (not supported)"""
+        assert TendePayFormatter.PAYMENT_MODE_MAP["cash"] is None
+
+
+class TestPaymentDetailsValidation:
+    """Test payment details validation"""
+    
+    def test_validate_send_money_valid(self):
+        """Valid send_money details should pass"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="send_money",
+            payment_details={"phone_number": "+254712345678", "recipient_name": "John Doe"},
+            user_name="John Doe"
+        )
+        assert is_valid is True
+        assert error is None
+    
+    def test_validate_send_money_missing_phone(self):
+        """send_money without phone should fail"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="send_money",
+            payment_details={"recipient_name": "John Doe"},
+            user_name="John Doe"
+        )
+        assert is_valid is False
+        assert "phone number" in error.lower()
+    
+    def test_validate_bank_transfer_valid(self):
+        """Valid bank_transfer details should pass"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="bank_transfer",
+            payment_details={
+                "bank_name": "KCB Bank",
+                "account_number": "1234567890",
+                "account_name": "John Doe"
+            },
+            user_name="John Doe"
+        )
+        assert is_valid is True
+        assert error is None
+    
+    def test_validate_bank_transfer_missing_details(self):
+        """bank_transfer without bank name should fail"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="bank_transfer",
+            payment_details={"account_number": "1234567890"},
+            user_name="John Doe"
+        )
+        assert is_valid is False
+        assert "bank details" in error.lower()
+    
+    def test_validate_paybill_valid(self):
+        """Valid paybill details should pass"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="paybill",
+            payment_details={
+                "business_number": "123456",
+                "account_number": "789",
+                "business_name": "ABC Ltd"
+            },
+            user_name="ABC Ltd"
+        )
+        assert is_valid is True
+        assert error is None
+    
+    def test_validate_till_number_valid(self):
+        """Valid till_number details should pass"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="till_number",
+            payment_details={"till_number": "123456", "business_name": "ABC Hardware"},
+            user_name="ABC Hardware"
+        )
+        assert is_valid is True
+        assert error is None
+    
+    def test_validate_cash_not_supported(self):
+        """cash payment should fail"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="cash",
+            payment_details={"recipient_name": "John Doe"},
+            user_name="John Doe"
+        )
+        assert is_valid is False
+        assert "not supported" in error.lower()
+    
+    def test_validate_no_payment_details(self):
+        """No payment details should fail"""
+        is_valid, error = TendePayFormatter.validate_payment_details(
+            payment_method="send_money",
+            payment_details=None,
+            user_name="John Doe"
+        )
+        assert is_valid is False
+        assert "no payment details" in error.lower()
+
+
+class TestNarrationBuilding:
+    """Test narration field building"""
+    
+    def test_build_narration_single_ticket(self):
+        """Should build narration for single ticket"""
+        # Mock expense objects
+        class MockTicket:
+            ticket_name = "ABC123"
+        
+        class MockExpense:
+            def __init__(self, category, cost):
+                self.category = category
+                self.total_cost = Decimal(cost)
+                self.ticket = MockTicket()
+        
+        expenses = [
+            MockExpense("transport", "500"),
+            MockExpense("materials", "1000")
+        ]
+        
+        narration = TendePayFormatter.build_narration(
+            expenses=expenses,
+            expense_date=date(2024, 12, 5)
+        )
+        
+        assert "2024-12-05" in narration
+        assert "ABC123" in narration
+        assert "Transport 500" in narration
+        assert "Materials 1000" in narration
+        assert "2 items" in narration
+        assert "1500" in narration
+    
+    def test_build_narration_truncates_long_text(self):
+        """Should truncate narration if too long"""
+        class MockTicket:
+            ticket_name = "A" * 100
+        
+        class MockExpense:
+            def __init__(self):
+                self.category = "transport"
+                self.total_cost = Decimal("500")
+                self.ticket = MockTicket()
+        
+        expenses = [MockExpense() for _ in range(20)]
+        
+        narration = TendePayFormatter.build_narration(
+            expenses=expenses,
+            expense_date=date(2024, 12, 5),
+            max_length=100
+        )
+        
+        assert len(narration) <= 100
+        assert narration.endswith("...")
+
+
+class TestFormatPaymentRow:
+    """Test formatting payment rows"""
+    
+    def test_format_mpesa_payment(self):
+        """Should format MPESA payment row correctly"""
+        class MockUser:
+            name = "John Doe"
+            id_number = "12345678"
+        
+        class MockTicket:
+            ticket_name = "ABC123"
+        
+        class MockExpense:
+            category = "transport"
+            total_cost = Decimal("500")
+            ticket = MockTicket()
+        
+        row = TendePayFormatter.format_payment_row(
+            expenses=[MockExpense()],
+            user=MockUser(),
+            expense_date=date(2024, 12, 5),
+            payment_method="send_money",
+            payment_details={"phone_number": "+254712345678", "recipient_name": "John Doe"},
+            user_id_number="12345678"
+        )
+        
+        assert row["NAME"] == "John Doe"
+        assert row["ID NUMBER"] == "12345678"
+        assert row["PHONE NUMBER"] == "254712345678"  # No + prefix
+        assert row["AMOUNT"] == 500.0
+        assert row["PAYMENT MODE"] == "MPESA"
+        assert "2024-12-05" in row["NARRATION (OPTIONAL)"]
+    
+    def test_format_bank_payment(self):
+        """Should format BANK payment row correctly"""
+        class MockUser:
+            name = "Jane Smith"
+            id_number = None  # No ID number
+        
+        class MockTicket:
+            ticket_name = "XYZ789"
+        
+        class MockExpense:
+            category = "materials"
+            total_cost = Decimal("2000")
+            ticket = MockTicket()
+        
+        row = TendePayFormatter.format_payment_row(
+            expenses=[MockExpense()],
+            user=MockUser(),
+            expense_date=date(2024, 12, 6),
+            payment_method="bank_transfer",
+            payment_details={
+                "bank_name": "Equity Bank",
+                "account_number": "0123456789",
+                "account_name": "Jane Smith"
+            },
+            user_id_number=None
+        )
+        
+        assert row["NAME"] == "Jane Smith"
+        assert row["ID NUMBER"] == ""  # Empty for missing ID
+        assert row["PHONE NUMBER"] == ""  # Not needed for bank
+        assert row["AMOUNT"] == 2000.0
+        assert row["PAYMENT MODE"] == "BANK"
+        assert row["BANK (Optional)"] == "Equity Bank"
+        assert row["BANK ACCOUNT NO (Optional)"] == "0123456789"
+
+
+class TestFormatVendorPaymentRow:
+    """Test formatting vendor payment rows"""
+    
+    def test_format_vendor_till_payment(self):
+        """Should format vendor till number payment"""
+        class MockTicket:
+            ticket_name = "VENDOR001"
+            id = "abc-123"
+        
+        class MockExpense:
+            category = "materials"
+            total_cost = Decimal("5000")
+            expense_date = date(2024, 12, 7)
+            ticket = MockTicket()
+        
+        row = TendePayFormatter.format_vendor_payment_row(
+            expense=MockExpense(),
+            payment_method="till_number",
+            payment_details={"till_number": "123456", "business_name": "ABC Hardware"}
+        )
+        
+        assert row["NAME"] == "VENDOR: ABC Hardware"
+        assert row["ID NUMBER"] == ""  # Vendors don't have ID
+        assert row["PAYMENT MODE"] == "BUYGOODS"
+        assert row["BUY GOODS TILL NO (Optional)"] == "123456"
+        assert row["AMOUNT"] == 5000.0