First Commit

payp/README_ONBOARDING_FIX.md

@@ -0,0 +1,145 @@
+# PayPal Merchant Onboarding - Issue Fixed
+
+## The Problem You Were Experiencing
+
+Your application was getting **stuck in "onboarding" state** and never receiving the actual merchant ID. Instead, you were seeing your **partner merchant ID** (`NEG5HMUKCTQNL`) returned for all merchants.
+
+### Root Cause
+
+When merchants click the "Connect with PayPal" button, they are redirected to PayPal's onboarding flow. However:
+
+1. **If they don't complete the entire signup process** (close browser, navigate away, etc.)
+2. PayPal's API returns your **partner's own merchant ID** instead of the new merchant's ID
+3. Your code was incorrectly saving this partner ID as if it were the merchant's ID
+
+## What Was Fixed
+
+### 1. **Partner ID Detection** 
+Added checks to reject the partner's own ID (`NEG5HMUKCTQNL`) when it's returned:
+
+```php
+// Don't accept the partner's own ID as merchant ID
+if (strcasecmp($foundId, $config['partner_merchant_id']) !== 0) {
+    $merchantId = $foundId;
+}
+```
+
+### 2. **Better Status Tracking**
+Now tracks onboarding status:
+- `incomplete_onboarding` - Merchant started but didn't complete PayPal signup
+- `connected` - Merchant completed signup and ID is available
+- `pending` - Waiting for PayPal to propagate the data
+
+### 3. **User Feedback**
+Enhanced the UI to show:
+- ⚠️ Warning when onboarding is incomplete
+- Clear instructions to complete the PayPal signup process
+- Sync button to check for completed onboardings
+
+## How To Use It Properly
+
+### For Testing (Sandbox):
+
+1. **Start Onboarding**: Click "Connect with PayPal" and enter a school name
+2. **Complete the FULL PayPal Flow**: 
+   - You'll be redirected to PayPal's sandbox signup
+   - **IMPORTANT**: You must complete the entire business account creation
+   - Don't just close the browser - finish all steps at PayPal
+3. **Return**: After completing, you'll be redirected back
+4. **Verify**: Check that the merchant ID is saved (not `NEG5HMUKCTQNL`)
+
+### What Success Looks Like:
+
+In `data/pending_onboarding.json`, you should see:
+```json
+{
+    "school_xxx": {
+        "school": "Test School",
+        "merchant_id": "SOME_OTHER_ID_NOT_YOUR_PARTNER_ID",
+        "status": "connected",
+        "connected_at": 1234567890
+    }
+}
+```
+
+### What Failure Looks Like (Before Fix):
+
+```json
+{
+    "school_xxx": {
+        "school": "Test School",
+        "merchant_id": "NEG5HMUKCTQNL",  // ❌ This is YOUR partner ID, not the merchant's!
+        "status": "connected"
+    }
+}
+```
+
+### What Incomplete Looks Like (After Fix):
+
+```json
+{
+    "school_xxx": {
+        "school": "Test School",
+        "status": "incomplete_onboarding",
+        "note": "Merchant did not complete PayPal onboarding. Partner ID was returned instead."
+    }
+}
+```
+
+## Files Modified
+
+1. **return.php** - Return handler after PayPal onboarding
+   - Added partner ID detection and rejection
+   - Added incomplete status tracking
+
+2. **sync_merchants.php** - Sync pending merchants
+   - Added partner ID filtering in all lookup methods
+   - Marks incomplete onboardings
+
+3. **index.php** - Main dashboard
+   - Shows incomplete onboarding warnings
+   - Better status messages
+
+## Testing Your Fix
+
+1. **Clear old data**:
+   - Delete or backup `data/merchants.json` and `data/pending_onboarding.json`
+
+2. **Test incomplete onboarding**:
+   - Click "Connect with PayPal"
+   - When redirected to PayPal, immediately click "Return to School Lunch App" WITHOUT completing signup
+   - You should see "⚠️ Onboarding Incomplete" warning
+   - No incorrect merchant ID should be saved
+
+3. **Test complete onboarding**:
+   - Click "Connect with PayPal"  
+   - **Complete the ENTIRE PayPal business account setup**
+   - You should see "✅ Onboarding completed"
+   - Verify the merchant ID is NOT `NEG5HMUKCTQNL`
+
+## Expected Merchant IDs in Sandbox
+
+- ✅ **Different from your partner ID**: Good! This is a real merchant
+- ❌ **Same as partner ID** (`NEG5HMUKCTQNL`): Bad! Onboarding not completed
+
+## One Successful Example Found
+
+Looking at your debug logs, I found ONE successful onboarding:
+- School: "b"
+- Tracking ID: `school_3387003d82`
+- Merchant ID: `796GQ4VM8SWSQ` ✅
+
+This proves your integration works when merchants **complete the full signup process**.
+
+## Next Steps
+
+1. Test with a fresh onboarding
+2. Make sure to complete ALL steps at PayPal during signup
+3. For production, ensure your merchants understand they must complete the entire PayPal business account setup
+4. Monitor `data/pending_onboarding.json` for `incomplete_onboarding` status entries
+
+## Questions?
+
+- Check `partner_diag.php` to see all merchant integrations
+- Review `data/sync_debug.json` for detailed API responses
+- Ensure your PayPal Partner credentials are correct in `config.php`