FAA.ZONE™ Global Deployment & Troubleshooting Manual: PayPal Subscriptions

1. Introduction & Project Scope

This manual consolidates all critical configurations, terminal commands, and resolutions for challenges encountered during development and live deployment of PayPal Subscriptions for the FAA.ZONE™ Admin Portal. It aims to provide clear instructions for staff, detailing code, configuration, and critical steps for live activation and ongoing management.

The Admin Portal utilizes the "Interstellar" theme for a consistent global aesthetic. The integration supports automated plan creation and user subscription management for various industry sectors within the FAA.ZONE™ ecosystem.

2. Architectural Decisions & Prerequisites

Key architectural decisions underpin this integration:

• Backend: Vercel Serverless Functions (Node.js) via `api/index.js` handles all secure PayPal API interactions.
• Frontend: Custom HTML/JavaScript pages (`admin-panel.html`, `products.html`) provide the user interface.
• Payment Gateway: PayPal Subscriptions API (for recurring billing) and associated Webhooks (for reliable transaction updates).
• Currency: All PayPal plans and transactions are configured in **South African Rand (ZAR)**.
• Deployment Platform: Vercel.

Before proceeding, ensure the following are installed and accessible:

• Node.js & npm: Installed on your development machine.
• Vercel CLI: Installed globally (`npm install -g vercel`).
• Git: Installed and configured.
• PayPal Business Account (Live): Fully set up and verified.
• PayPal Developer Account: Access to the Live environment for API credentials and webhook setup.
• Vercel Project Access: Permissions to manage environment variables and deploy the project.
• Project Repository Access: Read/write access to the `seedwave` GitHub repository.

3. PayPal Live Account & Vercel Environment Variables Setup

This section details obtaining PayPal credentials and configuring them securely in Vercel.

3.1. Obtain Live API Credentials (MyApp_Zoho)

These credentials are vital for your backend's secure communication with PayPal.

• Client ID: BAAThS_oBJJ22PM5R1nVJpXoSl9c3si7TJ3ICJBTht_PAFcRprbXkTv4_wqrG37kkAjUcv3tKBOxnUGQ98
• Secret: EFSS4mbIMZ6Q3ijOGCjqA9i4b3dzHULkCEV9jKAAHO9_fbO2aP9YCGRV9ekZaHqT2zSZL6Svrn-WyhIs

3.2. Create the Live Product (PROD- ID)

This is the overarching product for all your subscription plans.

1. Login to your **Live PayPal Business Account** (paypal.com).
2. Navigate to **Pay & Get Paid** > **Subscriptions** > **Products**.
3. Click **"Create Product"**.
4. Fill in the details:
   • Product name: Fruitful Global FAA.ZONE™ Services
   • Product description: Access to all FAA.ZONE™ ecosystem services, including core brand activations, real-time analytics, and secure data nodes for various industry sectors.
   • Product type: DIGITAL
   • Industry category: SOFTWARE (or SAAS)
   • Product page URL: [https://seedwave.faa.zone/admin-panel.html](https://seedwave.faa.zone/admin-panel.html)
5. Save the Product. PayPal will assign a **Product ID** that starts with PROD-.

Your Live Product ID: PROD-2NC51830JC183315X

3.3. Configure Vercel Environment Variables (Production)

These variables ensure your api/index.js function accesses the correct PayPal live credentials when deployed.

1. Login to your Vercel Dashboard.
2. Navigate to your seedwave Project Settings > Environment Variables.
3. **Add or update these variables for the Production environment:**
   • PAYPAL_LIVE_CLIENT_ID: BAAThS_oBJJ22PM5R1nVJpXoSl9c3si7TJ3ICJBTht_PAFcRprbXkTv4_wqrG37kkAjUcv3tKBOxnUGQ98
   • PAYPAL_LIVE_CLIENT_SECRET: EFSS4mbIMZ6Q3ijOGCjqA9i4b3dzHULkCEV9jKAAHO9_fbO2aP9YCGRV9ekZaHqT2zSZL6Svrn-WyhIs
   • PAYPAL_LIVE_PRODUCT_ID: PROD-2NC51830JC183315X
   • SESSION_SECRET: **A strong, randomly generated string**.
   • FRONTEND_URL: [https://seedwave.faa.zone](https://seedwave.faa.zone)
   • (Optional, if using Webhooks): PAYPAL_WEBHOOK_ID, PAYPAL_WEBHOOK_SECRET

4. Project File Updates (Local Development Setup)

This section covers the setup and initial configuration of your local project files.

4.1. Initial Local Setup (Cloning Repository & Dependencies)

For new staff or development machines, clone the project repository and install dependencies.

1. **Clone the Repository:**

   git clone [https://github.com/heyns1000/seedwave.git](https://github.com/heyns1000/seedwave.git)
   cd seedwave

2. **Install Node.js Dependencies:**

   samantha@Samanthas-iMac seedwave % npm install node-fetch

   Note: `node-fetch` is primarily for Node.js versions older than 18. If using Node.js 18+ (where `fetch` is built-in), this step is optional but harmless.

4.2. .env.local File Setup (For Local Development ONLY - `vercel dev`)

This file is essential for local testing and debugging with sandbox credentials. It is ignored by Git in production deployments.

1. Action: Create a file named .env.local in the root of your seedwave project folder.
2. Content: Paste the following (replace placeholders with your **sandbox** PayPal credentials):

   # .env.local file for local Vercel CLI development (seedwave/)
   
   # IMPORTANT: These are your PayPal SANDBOX API Credentials
   PAYPAL_LIVE_CLIENT_ID=AY-WQUCahAP77PZrkYkct446AM2Z9x8q-BNBHLNJY # Your Sandbox Client ID
   PAYPAL_LIVE_CLIENT_SECRET=EIAXSeXoPY2p1-Hj0AHQJXjMcI0MLZ... # Your Sandbox Client Secret (use full value)
   PAYPAL_WEBHOOK_ID=YOUR_SANDBOX_WEBHOOK_ID_GOES_HERE
   PAYPAL_WEBHOOK_SECRET=YOUR_SANDBOX_WEBHOOK_SIGNING_SECRET_GOES_HERE
   
   # PayPal Sandbox Product ID for your plans
   PAYPAL_LIVE_PRODUCT_ID=YOUR_SANDBOX_PROD-ID_HERE # Example: PROD-ABCDEF1234567890 (a sandbox product ID)
   
   # Session Secret for Express.js sessions.
   SESSION_SECRET=a_strong_random_secret_for_development_and_testing_ONLY_CHANGE_THIS_FOR_PROD
   
   # Frontend URL for local development for return/cancel URLs in PayPal flow
   FRONTEND_URL=http://localhost:3000 # Or the port your local frontend is running on.

3. Action: Replace placeholders with your sandbox credentials.

4.3. package.json & vercel.json Updates

These core configuration files should be clean and correctly configured (merge conflicts resolved).

• Action: Verify package.json and vercel.json match their latest corrected versions (as provided in previous conversation parts).

5. Frontend (admin_panel.html) Configuration & Troubleshooting

This file manages the admin UI and integrates the PayPal SDK for plan deployment.

5.1. Update PayPal SDK Client ID

This is crucial for the PayPal SDK to load correctly in a live environment.

1. Action: Open public/admin_panel.html.
2. Find (around Line ~754): The script tag with client-id=AY-WQUCahAP77PZrkYkct446AM2Z9x8q-BNBHLNJY (the old sandbox ID).
3. Replace with:

   <script src="[https://www.paypal.com/sdk/js?client-id=](https://www.paypal.com/sdk/js?client-id=)BAAThS_oBJJ22PM5R1nVJpXoSl9c3si7TJ3ICJBTht_PAFcRprbXkTv4_wqrG37kkAjUcv3tKBOxnUGQ98&currency=ZAR&vault=true&intent=subscription" onerror="document.getElementById('loading-message').textContent='Error loading PayPal SDK. Check network.'; console.error('PayPal SDK failed to load.');"></script>

5.2. Update YOUR_PAYPAL_PRODUCT_ID

This constant directs plan creation to your correct Live PayPal Product.

1. Action: Open public/admin_panel.html.
2. Find (around Line ~950): const YOUR_PAYPAL_PRODUCT_ID = 'P-07F80334R518562XNBHLNJY'; (This was an incorrect Plan ID).
3. Replace with: const YOUR_PAYPAL_PRODUCT_ID = 'PROD-2NC51830JC183315X';

5.3. Configure PAYPAL_PLAN_IDS (Initial State)

This object holds the generated PayPal Plan IDs. It starts with the one manually created plan and will be fully populated later.

1. Action: Open public/admin_panel.html.
2. Ensure the `PAYPAL_PLAN_IDS` object looks like this:

   const PAYPAL_PLAN_IDS = {
       "Agriculture___Biotech_Starter_Package_MONTHLY": "P-1RR589971C5386049NBI327Q", // Manually obtained Live Plan ID
       // All other Live Plan IDs (P-) will be pasted here after automated deployment.
       // DO NOT PUT ANY SANDBOX IDs OR PLACEHOLDERS HERE FOR NOW.
       // Example: "Agriculture___Biotech_Starter_Package_ANNUAL_v2.0": "P-YOUR_AUTO_GENERATED_ID_HERE",
       // etc. for all tiers and sectors
   };

6. Backend (api/index.js) Setup & Troubleshooting

This serverless function handles all secure communication with PayPal's API and has been a central point for debugging.

6.1. Update & Correct api/index.js Content

Ensure your api/index.js file has the definitive, complete, and corrected code.

1. Action: Open api/index.js.
2. Action: Copy the **entire content** from the api_index_js_ultimate_definitive_code_final_final_verified Canvas (located at the end of this manual).
3. Action: Paste this copied code over **ALL** existing content in your local api/index.js file. **Save the file.**
4. **Key Changes Applied in this Code:**
   • node-fetch Dynamic Import: Resolves ERR_REQUIRE_ESM.

     // REMOVED DIRECT REQUIRE: const fetch = require('node-fetch');
     // ... inside generateAccessToken and callPayPalApi functions ...
     const { default: fetch } = await import('node-fetch');

   • module.exports = app;: Resolves "No exports found in module" error.

     // ... (end of your app.post('/api', ...) route)
     module.exports = app; // CRITICAL: This exports your Express app for Vercel

   • Plan Naming Workaround: Resolves PayPal returning same `P-` ID for distinct plans.

     const monthlyPlanName = `${sectorDisplayName} ${tierName} Package (Monthly) v2.0`;
     const annualPlanName = `${sectorDisplayName} ${tierName} Package (Annual) v2.0`;

   • Return/Cancel URLs: Corrected `admin-panel.co.za` to `admin-panel.html`.

     return_url: process.env.FRONTEND_URL ? `${process.env.FRONTEND_URL}/subscription-success.html` : '[https://seedwave.faa.zone/admin-panel.html/subscription-success.html](https://seedwave.faa.zone/admin-panel.html/subscription-success.html)',
     cancel_url: process.env.FRONTEND_URL ? `${process.env.FRONTEND_URL}/subscription-cancel.html` : '[https://seedwave.faa.zone/admin-panel.html/subscription-cancel.html](https://seedwave.faa.zone/admin-panel.html/subscription-cancel.html)',

7. Git & Vercel Deployment Workflow (Live Activation)

This section outlines the precise terminal commands to synchronize your project with GitHub and trigger Vercel deployments. Staff should execute these from the seedwave project directory in Terminal.

7.1. Pull Latest Remote Changes

git pull origin main

Purpose: Ensures your local copy is up-to-date with any changes pushed directly to GitHub (e.g., via GitHub's web interface or by Vercel's automated updates), preventing push rejections.

7.2. Add All Modified Files to Staging

git add .

Purpose: Prepares all local changes (including code updates and content changes) for the next commit.

7.3. Commit the Changes

git commit -m "Comprehensive deployment: Frontend, Backend fixes and Plan Naming V2.0"

Purpose: Saves your current local state to your Git history.

7.4. Push the Changes to GitHub (and Trigger Vercel Deployment)

git push origin main --force

Purpose: This is the critical step to get your code live. It pushes your local branch to GitHub, which automatically triggers a new Vercel deployment. `--force` is used to ensure the remote matches your local state, overcoming any previous sync issues.

7.5. Monitor Vercel Deployment Status

Go to your Vercel Dashboard and navigate to your seedwave project. Wait for the new deployment to complete and show a status of "Ready."

8. Deploying Live PayPal Subscription Plans (from Admin Portal UI)

Once your Vercel deployment is Ready, you can use your Admin Portal to create all your Live PayPal Subscription Plans automatically.

8.1. Access Deployed Admin Portal (Perform an EXTREME Hard Refresh!)

Go to your live Admin Portal URL in your web browser: [https://seedwave.faa.zone/admin](https://seedwave.faa.zone/admin)

Perform a **VERY AGGRESSIVE HARD REFRESH** to ensure your browser loads the absolute latest admin_panel.html file and clears all cache:

• Chrome/Firefox (Mac): Hold Cmd + Shift and press R repeatedly.
• Safari (Mac): Press Cmd + Option + E (to empty caches), then Cmd + R.
• General / Ultimate Method: Open Developer Tools (F12), go to the "Network" tab, then right-click the refresh button in the browser toolbar and choose "Empty Cache and Hard Reload."
• Recommended: Also try opening the URL in a **new Incognito/Private window** to bypass all caching.

8.2. Initiate Plan Deployment for Each Sector

Navigate to the "Global Index" section within your Admin Portal. Click the "**Deploy Plan**" button for the sectors whose plans you wish to create in the live PayPal environment.

8.3. Monitor Console for Live Plan IDs (CRITICAL STEP)

Keep your browser's Developer Console (F12) open to the "Console" tab. Observe the output carefully.

8.4. Copy Generated Live Plan IDs

Copy the *entire* createdPlans array (the object containing all the plan names and their new P- IDs) that is logged in your console.

8.5. Update Local admin_panel.html

Open your **LOCAL** public/admin_panel.html file in your code editor.

Locate the PAYPAL_PLAN_IDS object (Lines ~954-972 in your updated admin_panel.html). **Manually paste those new Live P- IDs you just copied** from the console output into this object.

Carefully match each P- ID to its correct planKey string. The planKey will include the v2.0 suffix (e.g., "Agriculture___Biotech_Starter_Package_ANNUAL_v2.0").

const PAYPAL_PLAN_IDS = {
    "Agriculture___Biotech_Starter_Package_MONTHLY": "P-1RR589971C5386049NBI327Q", // Keep the manually obtained one for consistency if it's there
    "Agriculture___Biotech_Starter_Package_ANNUAL_v2.0": "P-NEW_LIVE_AGRI_STARTER_ANNUAL_ID_FROM_CONSOLE",
    "Agriculture___Biotech_Pro_Package_MONTHLY_v2.0": "P-NEW_LIVE_AGRI_PRO_MONTHLY_ID_FROM_CONSOLE",
    "Agriculture___Biotech_Pro_Package_ANNUAL_v2.0": "P-NEW_LIVE_AGRI_PRO_ANNUAL_ID_FROM_CONSOLE",
    "Agriculture___Biotech_Enterprise_Package_MONTHLY_v2.0": "P-NEW_LIVE_AGRI_ENTERPRISE_MONTHLY_ID_FROM_CONSOLE",
    "Agriculture___Biotech_Enterprise_Package_ANNUAL_v2.0": "P-NEW_LIVE_AGRI_ENTERPRISE_ANNUAL_ID_FROM_CONSOLE",

    // ... add other sectors' v2.0 plan IDs here after their successful deployment ...
};

Action: **Save** your public/admin_panel.html file.

8.6. Commit & Push Final Frontend Changes

git add public/admin-panel.html
git commit -m "Updated PAYPAL_PLAN_IDS with all unique live PayPal Plan IDs"
git push origin main

Purpose: This last push will update your live frontend. Once this final Vercel deployment is "Ready," your "Subscribe Now" buttons on your live website will be fully functional, allowing customers to subscribe to your live plans.