HotLunches/payp/QUICK_START.md

🚀 QUICK START - Fix Your Merchant Onboarding

What Just Happened?

I found and fixed the bug causing your merchants to get stuck in "onboarding" state. The problem: your code was accepting your own partner ID as if it were the merchant's ID when they didn't complete PayPal signup.

---

🔧 Step 1: Clean Up Old Data (2 minutes)

Open your browser and go to:

http://localhost/payp/cleanup.php

This will:

• Remove incorrect merchant IDs (your partner ID saved as merchant IDs)
• Mark incomplete onboardings properly
• Show you what was cleaned

Do this NOW before testing!

---

✅ Step 2: Test Complete Onboarding (5 minutes)

1. Go to: http://localhost/payp/

2. Fill in a school name and click "Connect with PayPal"

3. IMPORTANT: When redirected to PayPal:

   • ✅ DO: Complete the ENTIRE business account setup
   • ✅ DO: Fill in all required fields
   • ✅ DO: Click through all steps until PayPal shows "Return to Application"
   • ❌ DON'T: Close the browser early
   • ❌ DON'T: Skip steps

4. Click "Return to School Lunch App" when PayPal prompts

5. Verify Success:

   • You should see: ✅ "Onboarding completed and merchant saved"
   • Dashboard shows the school in "Connected Schools"
   • Merchant ID is NOT NEG5HMUKCTQNL

---

⚠️ Step 3: Test Incomplete Onboarding (2 minutes)

1. Go to: http://localhost/payp/

2. Fill in a different school name and click "Connect with PayPal"

3. As soon as PayPal page loads:

   • Click "Return to School Lunch App" WITHOUT completing signup
   • OR just close the browser tab

4. Verify Failure Handling:

   • You should see: ⚠️ "Onboarding Incomplete" warning
   • Dashboard shows the school in "Pending Onboarding" with warning icon
   • NO merchant ID is saved
   • Status shows: incomplete_onboarding

---

📊 Step 4: Check Your Data

Open these files and verify:

data/merchants.json

Should contain only COMPLETED merchants with DIFFERENT IDs:

{
    "Test School": {
        "merchant_id": "SOME_UNIQUE_ID",  // NOT NEG5HMUKCTQNL
        "tracking_id": "school_xxxxx",
        "connected_at": 1234567890
    }
}

data/pending_onboarding.json

Should show clear status for each:

{
    "school_xxxxx": {
        "school": "Complete School",
        "merchant_id": "SOME_UNIQUE_ID",
        "status": "connected"  // ✅
    },
    "school_yyyyy": {
        "school": "Incomplete School",
        "status": "incomplete_onboarding",  // ⚠️
        "note": "Merchant did not complete PayPal onboarding"
    }
}

---

🎯 Expected Results

✅ SUCCESS - Complete Onboarding

• Dashboard: ✅ Green success message
• Merchant ID: Different from NEG5HMUKCTQNL
• Status: connected
• Can create orders

⚠️ HANDLED - Incomplete Onboarding

• Dashboard: ⚠️ Yellow warning message
• No merchant ID saved
• Status: incomplete_onboarding
• Clear instructions to complete signup

❌ OLD BUG (Now Fixed)

• Saves NEG5HMUKCTQNL as merchant ID
• Status stuck at connected but not really connected
• No warning messages
• Can't create orders

---

🔍 Troubleshooting

Problem: Still seeing NEG5HMUKCTQNL as merchant ID

• Solution: Run cleanup.php again, then test with a NEW school

Problem: Dashboard doesn't show warnings

• Solution: Clear browser cache and refresh index.php

Problem: Can't complete PayPal onboarding in sandbox

• Solution: Make sure you're using a PayPal sandbox business account for testing
• Check: https://developer.paypal.com/developer/accounts/

Problem: Getting errors when creating orders

• Solution: Verify the merchant_id in merchants.json is NOT your partner ID

---

📋 Quick Checklist

• Ran cleanup.php to fix old data
• Tested complete onboarding (finish all PayPal steps)
• Saw ✅ success message
• Verified merchant ID is different from NEG5HMUKCTQNL
• Tested incomplete onboarding (close browser early)
• Saw ⚠️ warning message
• Verified NO merchant ID saved for incomplete
• Checked data/merchants.json has correct IDs
• Checked data/pending_onboarding.json has correct statuses

---

📚 More Information

• Full explanation: Read SOLUTION_SUMMARY.md
• Visual flow: Read FLOW_DIAGRAM.md
• Detailed docs: Read README_ONBOARDING_FIX.md
• Diagnostics: Open partner_diag.php in browser

---

🎉 You're Done!

Your PayPal merchant onboarding is now fixed! The key takeaway:

Merchants MUST complete the entire PayPal business account signup for you to receive their merchant ID. If they don't finish, the system now correctly detects this and shows a warning instead of saving incorrect data.

Questions? Check the documentation files created in your project. 🚀