# STK Callback Troubleshooting Guide

## Summary of Changes

Added comprehensive logging to all M-Pesa callback endpoints to trace where callbacks are being routed.

## What Was Added

Enhanced logging at these endpoints:
- `/api/payment/callback` - Main STK Push callback handler
- `/api/payment/c2b/validation` - C2B validation endpoint
- `/api/payment/c2b/confirmation` - C2B confirmation endpoint
- `/api/payment/c2b/nonstk/validation` - Non-STK C2B validation
- `/api/payment/c2b/nonstk/confirmation` - Non-STK C2B confirmation

Each endpoint now logs:
- Which endpoint received the callback
- Full payload from M-Pesa
- Helps identify routing and format issues

## How to Diagnose

### Step 1: Trigger an STK Push
1. Go to user repayment page
2. Simulate an STK push payment
3. Check logs immediately after

### Step 2: Check the Logs

Run this to see recent callback logs:
```bash
tail -100 storage/logs/laravel.log | grep -i "callback received"
```

Look for entries like:
- `M-Pesa callback received at /api/payment/callback` ← STK Push should go here
- `C2B confirmation callback received at /api/payment/c2b/confirmation` ← Manual C2B payment
- `C2B validation callback received at /api/payment/c2b/validation` ← Manual C2B payment

### Step 3: Analyze the Payload

If you see `callback received` in logs, check:

**For STK Push (should have this structure):**
```
"Body" => ["stkCallback" => [
    "MerchantRequestID" => "...",
    "CheckoutRequestID" => "...",
    "ResultCode" => 0,  // 0 = success
    "CallbackMetadata" => ["Item" => [
        ["Name" => "Amount", "Value" => 1000],
        ["Name" => "MpesaReceiptNumber", "Value" => "ABC..."]
    ]]
]]
```

**For C2B (manual payment - should have this structure):**
```
"BillRefNumber" => "...",
"TransAmount" => 1000,
"TransID" => "...",
"MSISDN" => "254700..."
```

## Expected Flow

### STK Push Successful Flow:
1. User initiates STK push
2. Transaction created with `checkout_request_id` ✓
3. M-Pesa sends callback to `/api/payment/callback`
4. Handler finds transaction by `CheckoutRequestID`
5. Transaction updated to `completed`
6. Repayment allocated ✓

### STK Push Broken Flow (Current):
1. User initiates STK push
2. Transaction created with `checkout_request_id` ✓
3. M-Pesa callback NOT arriving at `/api/payment/callback` ✗
4. Transaction stays `pending` ✗
5. No logs in storage/logs/laravel.log ✗

## Possible Issues

### Issue 1: Wrong Endpoint
If callbacks are going to `/api/payment/c2b/confirmation` instead of `/api/payment/callback`:
- M-Pesa might be configured to send STK callbacks to the C2B endpoint
- Solution: Check which URL is registered with M-Pesa for STK callbacks

### Issue 2: No Callbacks at All
If no callback logs appear:
- ngrok tunnel is down → Check `http://localhost:4040`
- Firewall blocking callbacks → Check port 443
- M-Pesa environment mismatch → Confirm sandbox vs production

### Issue 3: Validation Failure
If logs show callback but handler returns error:
- Missing `CheckoutRequestID` in payload
- Transaction lookup fails
- Solution: Check error details in logs

## Next Steps

1. **Check logs after next STK push:**
   ```bash
   tail -f storage/logs/laravel.log
   ```

2. **Identify which endpoint receives the callback**

3. **If wrong endpoint:** Update callback URL registration

4. **If no logs at all:** Check ngrok tunnel and network

## Test With Simulator

To manually test the callback handler:
```bash
php scripts/tmp_simulate_stk_callback.php
```

This simulates a successful STK callback and should show transaction updated to `completed`.
