7c929eb4dc
- Streamlined the README.md for clarity and conciseness. - Deleted outdated documentation files related to Freebit SIM management, SIM management API data flow, and various architectural guides to reduce clutter and improve maintainability. - Updated the last modified date in the README to reflect the latest changes.
180 lines
9.0 KiB
Markdown
180 lines
9.0 KiB
Markdown
# 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.
|
||
|
||
---
|
||
|
||
## 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.”
|