Server : Apache/2 System : Linux server-15-235-50-60 5.15.0-164-generic #174-Ubuntu SMP Fri Nov 14 20:25:16 UTC 2025 x86_64 User : gositeme ( 1004) PHP Version : 8.2.29 Disable Function : exec,system,passthru,shell_exec,proc_close,proc_open,dl,popen,show_source,posix_kill,posix_mkfifo,posix_getpwuid,posix_setpgid,posix_setsid,posix_setuid,posix_setgid,posix_seteuid,posix_setegid,posix_uname Directory :  /home/gositeme/domains/soundstudiopro.com/public_html/

Upload File : current_dir [ Writeable ] document_root [ Writeable ]

# Purchase Fix Explanation & Automation Guide

## 🔍 Understanding the Problem

### Why Purchases Go Missing

When customers purchase tracks, the flow works like this:

1. **Checkout** → Payment intent created → Logged to `logs/cart_payment_detailed.log`
2. **Stripe Webhook** → `payment_intent.succeeded` event → Calls `processTrackPurchase()` or `processMixedCartPayment()`
3. **Database** → Should create records in:
   - `track_purchases` (customer's purchase record)
   - `sales` (artist's sale record)
   - `user_library` (customer's library)

**The Problem**: Sometimes step 3 fails due to:
- Webhook delivery failures
- Database transaction errors
- Race conditions
- Exceptions in `processTrackPurchase()` that are caught but not retried
- Network issues between Stripe and your server

**Result**: Customer paid, but tracks don't appear in their purchases/library, and artists don't see the sales.

---

## 🛠️ How `admin_purchase_tracker.php` Fixes It

The script works by:

1. **Reading Payment Logs**: Scans `logs/cart_payment_detailed.log` for payment intents
2. **Cross-Referencing**: Checks if tracks from those payment intents exist in `track_purchases` table
3. **Identifying Missing**: Flags tracks that were in payment intents but NOT in database
4. **Manual Fix**: When you click "Fix", it calls `fixMissingPurchase()` which:
   ```php
   - Creates record in `sales` table
   - Creates record in `track_purchases` table
   - Adds track to `user_library` table
   - Logs the fix to `logs/manual_purchase_fixes.log`
   ```

**Key Function**: `fixMissingPurchase()` (lines 576-658)
- Checks if already purchased (prevents duplicates)
- Gets track info from database
- Determines revenue recipient (free users → platform, paid users → artist)
- Creates all three database records in a transaction
- Logs the fix for audit trail

---

## 🤖 How to Automate the Fix

### Option 1: Automated Cron Script (Recommended)

Create a script that runs periodically (every 5-15 minutes) to automatically detect and fix missing purchases.

**Benefits**:
- ✅ Catches issues within minutes
- ✅ No manual intervention needed
- ✅ Can verify with Stripe before fixing
- ✅ Logs all automatic fixes

**Implementation**: See `auto_fix_missing_purchases.php` (created below)

### Option 2: Enhanced Webhook Handler

Add retry logic and better error handling to `webhooks/stripe.php` so purchases are less likely to fail in the first place.

**Benefits**:
- ✅ Prevents the problem at the source
- ✅ Immediate fix when webhook succeeds

**Implementation**: Add retry logic to `processTrackPurchase()` and `processMixedCartPayment()`

### Option 3: Real-time Monitoring

Add a monitoring script that watches for payment intents and immediately checks if purchases were created.

**Benefits**:
- ✅ Near-instant detection
- ✅ Can trigger alerts

---

## 📋 Recommended Automation Strategy

**Best Approach**: Combine all three:

1. **Enhanced Webhook** (prevention) - Better error handling and retries
2. **Real-time Monitor** (detection) - Check purchases within 1-2 minutes
3. **Cron Script** (safety net) - Daily scan for any missed purchases

---

## 🔐 Safety Considerations

Before automating fixes:

1. **Verify Payment Status**: Always check with Stripe API that payment actually succeeded
2. **Prevent Duplicates**: Check if purchase already exists before creating
3. **Log Everything**: Keep audit trail of all automatic fixes
4. **Notification**: Alert admin when automatic fixes are applied
5. **Rate Limiting**: Don't check Stripe API too frequently

---

## 📊 Monitoring

Track these metrics:
- Number of missing purchases detected
- Number of automatic fixes applied
- Number of manual fixes still needed
- False positives (payment intent created but payment failed)

---

## 🚨 Important Notes

- **Payment Intent ≠ Payment Success**: A payment intent can be created but payment might fail. Always verify with Stripe.
- **Timing**: Some purchases might be in-flight. Wait 2-5 minutes after payment intent creation before flagging as missing.
- **Webhook Delays**: Stripe webhooks can be delayed. Don't flag as missing too quickly.