Assist_Design/docs/portal/PORTAL-NONTECH-PRESENTATION.md

Customer Portal — Simple Overview (Non‑Technical)

Use these slide-ready bullets to explain, in plain language, how our portal works with Salesforce and WHMCS.

1) What The Portal Does

• Purpose: One place for customers to browse plans, place orders, and view/pay bills.
• Connects two company systems: Salesforce (service control) and WHMCS (billing).
• Goal: Smooth experience for customers, clear control and visibility for our team.

2) The Two Systems We Connect

• Salesforce: Our “control center” for products and orders. Staff review and approve here.
• WHMCS: Our “billing system” for invoices, payment methods, and subscriptions.
• The Portal: The “bridge” customers use. It talks to both safely in the background.

3) How It Fits Together (Big Picture)

• Customer uses the Portal → chooses products → places an order.
• Portal creates the order in Salesforce for review/approval.
• After approval, the Portal provisions the order in WHMCS.
• WHMCS then holds the subscription and generates the invoices customers can pay.

4) Catalog (What Customers Can Buy)

• We show the catalog from Salesforce so prices and products are consistent.
• Products are organized (e.g., Internet, SIM, VPN) with clear names and monthly/one‑time fees.
• The Portal only shows what’s approved for online sale.

5) Customer Journey (At a Glance)

1. Sign up and link your account.
2. Add a payment method (credit card or gateway) — one‑time step.
3. Browse the catalog and select a plan.
4. Place an order (Portal sends it to Salesforce).
5. Staff reviews/approves in Salesforce, and the Portal activates it in WHMCS.
6. Customer sees subscriptions and invoices in the Portal and pays securely.

5a) Sign Up & Account Linking (Plain English)

• What we ask for: email, password, name, and your Customer Number (Salesforce number) — this lets us find your existing account.
• What happens: we create a billing profile in WHMCS and securely link three IDs together behind the scenes:
  • Portal user ↔ WHMCS client ↔ Salesforce account.
• Why this matters: from then on, the Portal always shows the right invoices, payment methods, and subscriptions for that customer.

5b) Address — Where It Lives and How We Use It

• Required at signup: we capture a full billing address and store it in WHMCS (our billing source of truth).
• Always available: the Portal pulls your current address from WHMCS so checkout is smooth.
• Snapshotted on every order: we copy the current address into the Salesforce order so staff can review what was used at the time.
• Internet orders: we ask you to explicitly confirm the installation address (technician visit). If you change it, we mark the order “address changed” for staff visibility.
• Updates later: when customers update address in the Portal, we sync it to WHMCS so billing and future orders are correct.

5c) Payment Methods — Why We Require One First

• Fewer failures: we only allow ordering after a payment method is on file.
• How customers add it: the Portal opens WHMCS’s secure payment page (single sign‑on); cards are stored by WHMCS, not by the Portal.
• Provisioning also checks: even after approval, we re‑check payment to avoid failed activations.

6) Ordering Flow (Simple)

• Before ordering, the Portal checks: “Do you have a saved payment method?”
• The Portal sends your chosen items to Salesforce as an order for review.
• After approval, the Portal creates the service in WHMCS and finishes activation.

6a) Business Rules We Enforce (Simple)

• Internet: must include a service plan; installation options are clearly shown; we prevent duplicate active Internet services for the same account.
• SIM: must include a SIM plan and a one‑time activation fee; optional add‑ons (e.g., voicemail) can be added; for number transfer (MNP), we collect the reservation details.
• VPN: must include the VPN activation fee; regions/options are chosen up front.
• Product validity: only products that are approved and priced are allowed to be ordered.

7) Billing & Payments (Simple)

• Invoices: Created by WHMCS and shown in the Portal.
• Payment: The Portal opens a secure payment page (SSO) directly in WHMCS.
• Subscriptions: Ongoing services (e.g., monthly plans) displayed in the Portal.

8) Built‑In Safeguards (What We Check Automatically)

• Payment method required: prevents failed activations and billing issues.
• Product validity: only approved, priced items can be ordered.
• Duplicate protection: e.g., avoids ordering a second Internet line by mistake.
• Status tracking: Salesforce and WHMCS stay in sync (Created → Activating → Activated).

8a) Behind the Scenes (Safe & Repeatable)

• Approvals: staff review orders in Salesforce; on approval, the Portal activates the order in WHMCS.
• Single sign‑on (SSO): the Portal uses expiring links to WHMCS for invoices and payments; we don’t handle card numbers directly.
• Clear errors: if something blocks activation (e.g., missing payment method), we pause and show a short, human‑readable note to staff and a clear status to the customer.

9) If Something Goes Wrong

• The order is paused with a clear status (e.g., “Awaiting payment method”).
• Staff sees a short error code and message in Salesforce to resolve quickly.
• Customers keep seeing clear status updates in the Portal.

10) Why This Is Better

• For customers: Clear catalog, simple checkout, easy invoice payments.
• For staff: Single review step in Salesforce, automated activation, fewer manual tasks.
• For the business: Consistent pricing, faster time‑to‑activate, fewer errors.

---

Suggested Slide Deck (Titles + Bullets + Notes)

1. Title — “Customer Portal: How It Works”

   • Bullets: One place to buy, manage, and pay.
   • Notes: We connect Salesforce (control) and WHMCS (billing).

2. The Systems

   • Bullets: Salesforce = control; WHMCS = billing; Portal = bridge.
   • Notes: Keep the mental model: control center vs. billing system.

3. Big Picture Flow

   • Bullets: Choose → Order in Salesforce → Approve → Activate in WHMCS → Pay.
   • Notes: Emphasize approvals happen in Salesforce; invoices in WHMCS.

4. The Catalog

   • Bullets: Products come from Salesforce; only approved offers appear.
   • Notes: Ensures one source of truth for products and prices.

5. Customer Journey

   • Bullets: Sign up → Add payment → Choose plan → Order → Approve → Activate → Pay.
   • Notes: This is what a typical customer sees end‑to‑end.

6. Ordering Checks

   • Bullets: Payment method required; valid items only; no duplicates.
   • Notes: Prevents surprises and support tickets later.

7. Billing & Payments

   • Bullets: Invoices from WHMCS; pay via secure SSO; subscriptions visible.
   • Notes: We never store card numbers in the Portal.

8. Status & Errors

   • Bullets: Clear statuses; short error messages for staff.
   • Notes: Faster turnaround and fewer escalations.

9. Benefits

   • Bullets: Better customer experience; less manual work; consistent pricing.
   • Notes: Close with impact on activation time and error reduction.

10. Q&A

• Bullets: —
• Notes: Keep backup slides with examples/screenshots.

---

Tip: Pair these slides with a simple swimlane diagram (Customer, Portal, Salesforce, WHMCS) showing the hand‑offs at order and activation.

References for deeper reading (optional for presenters)

• Address flow details: docs/ADDRESS_SYSTEM.md
• Technical overview: docs/PORTAL-INTEGRATION-OVERVIEW.md

Diagram (PNG/SVG for slides)

• Swimlane visual: docs/assets/portal-swimlane.svg

---

11) Migration (Moving Existing WHMCS Users Into the Portal)

Goal: Let existing customers with WHMCS billing accounts start using the new Portal without losing history.

How it works (plain English):

• Check your email: if you already have a WHMCS billing account, choose “Link account”.
• One-time check: enter your current WHMCS password once. We only verify it directly with WHMCS to prove ownership — we don’t copy it.
• Auto‑linking: we read your Customer Number from WHMCS and find the matching Salesforce account. Then we create your Portal account and link all three IDs.
• Set a new Portal password: we ask you to create a new password for the Portal (your WHMCS password stays in WHMCS).
• After that: log in with your new Portal password; continue to manage payment methods and invoices via secure SSO into WHMCS.

Why setting a NEW Portal password is better than reusing the old one:

• Separation of risk: WHMCS and the Portal are different systems. Separate passwords reduce the blast radius if one is compromised.
• Stronger policy & protections: the Portal enforces modern hashing, lockouts, and audit logs tailored to our app. We don’t control WHMCS’s password rules.
• Least privilege: the Portal never stores or proxies your WHMCS password. We only validate it once during linking, then discard it.
• Future flexibility: lets us improve Portal security (e.g., MFA, rotation rules) without affecting WHMCS.
• Clear SSO flow: customers use the Portal to reach WHMCS billing pages securely without sharing credentials.

Simple talking points for the migration slide:

• “Link your existing billing account by confirming your current password once.”
• “Create a new Portal password — safer, independent, and future‑proof.”
• “Nothing is lost — subscriptions and invoices automatically appear once linked.”