HotLunches/payp/README_ONBOARDING_FIX.md

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:

// 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:

{
    "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):

{
    "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):

{
    "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