Assist_Design/docs/how-it-works/eligibility-and-verification.md

Eligibility & Verification

This guide describes how eligibility and verification work in the customer portal:

• Internet eligibility (NTT serviceability review)
• ID verification (residence card / identity document) for all services

Overview

Concept	Source of Truth	Description
Products + pricing	Salesforce pricebook	Single catalog truth
Payment methods	WHMCS	Card storage via Stripe
Orders + fulfillment	Salesforce Order (and downstream WHMCS)	Operational workflow
Internet eligibility status	Salesforce Account (with Case for workflow)	Reuse for future internet orders
ID verification status	Salesforce Account (with Files)	Reuse for future orders

Internet Eligibility (NTT Address Review)

How It Works

1. Customer navigates to /account/services/internet
2. Customer clicks Check Availability (requires a service address on file)
3. Portal calls POST /api/services/internet/eligibility-request and shows an immediate confirmation screen at /account/services/internet/request-submitted
4. Portal finds/creates a Salesforce Opportunity (Stage = Introduction) and creates a Salesforce Case linked to that Opportunity for agent review
5. Agent performs NTT serviceability check (manual process)
6. Agent updates Account eligibility fields
7. Salesforce Flow sends email notification to customer
8. Customer returns and sees eligible plans

Caching & Rate Limiting (Security + Load)

• BFF cache (Redis):
  • Internet catalog data is cached in Redis (CDC-driven invalidation, no TTL) so repeated portal hits do not repeatedly query Salesforce.
  • Eligibility details are cached per Salesforce Account ID and are invalidated/updated when Salesforce emits Account change events.
• Portal cache (React Query):
  • The portal caches service catalog responses in-memory, scoped by auth state, and will refetch when stale.
  • On logout, the portal clears cached queries to avoid cross-user leakage on shared devices.
• Rate limiting:
  • Public catalog endpoints are rate-limited per IP + User-Agent to prevent abuse.
  • POST /api/services/internet/eligibility-request is authenticated and rate-limited, and the BFF is idempotent when a request is already pending (no duplicate Cases created).

Subscription Type Detection

The portal identifies Internet subscriptions by product name matching:

// Matches any of these patterns (case-insensitive):
// - "internet"
// - "sonixnet"
// - "ntt" + "fiber"
const isInternetService =
  productName.includes("internet") ||
  productName.includes("sonixnet") ||
  (productName.includes("ntt") && productName.includes("fiber"));

Salesforce Account Fields

Field API Name	Type	Set By	When
Internet_Eligibility_Status__c	Picklist	Portal/Agent	Request/Check
Internet_Eligibility__c	Text	Agent	After check
Internet_Eligibility_Request_Date_Time__c	DateTime	Portal	On request
Internet_Eligibility_Checked_Date_Time__c	DateTime	Agent	After check

Notes:

• The portal returns an API-level request id (Salesforce Case ID) from POST /api/services/internet/eligibility-request for display/auditing.
• The portal UI reads eligibility status/value from the Account fields above; it does not rely on an Account-stored Case ID.

Status Values

Status	Services Page UI	Checkout Gating
Not Requested	Show "Request eligibility check" button	Block submit
Pending	Show "Review in progress"	Block submit
Eligible	Show eligible plans	Allow submit
Ineligible	Show "Not available" + contact support	Block submit

ID Verification (Residence Card)

How It Works

1. Customer navigates to /account/settings (Profile page)
2. Customer uploads residence card in the "Identity Verification" section
3. File is uploaded to Salesforce (ContentVersion linked to Account)
4. Agent reviews document and updates verification status
5. Customer sees "Verified" status and can submit orders

Where to Upload

ID verification is available in two places:

1. Profile Page (/account/settings) - Integrated upload in the "Identity Verification" card
2. Standalone Page (/account/settings/verification) - For checkout flow redirects

The Profile page is the primary location. The standalone page is used when redirecting from checkout with a returnTo parameter.

Salesforce Account Fields

Field API Name	Type	Set By	When
Id_Verification_Status__c	Picklist	Portal/Agent	Upload/Review
Id_Verification_Submitted_Date_Time__c	DateTime	Portal	On upload
Id_Verification_Verified_Date_Time__c	DateTime	Agent	After review
Id_Verification_Note__c	Text	Agent	After review
Id_Verification_Rejection_Message__c	Text	Agent	If rejected

Status Values

Status	Portal UI	Can Submit Order?
Not Submitted	Show upload form	No
Submitted	Show "Under Review" with submitted info	Yes
Verified	Show "Verified" badge	Yes
Rejected	Show rejection reason + upload form	No

Supported File Types

• PDF
• PNG
• JPG/JPEG

Portal UI Locations

Location	What's Shown
/account/settings	Profile, Address, ID Verification (with upload)
/account/services/internet	Eligibility status and eligible plans
/account/services/internet/request-submitted	Immediate confirmation after submitting an eligibility request
Subscription detail	Service-specific actions (cancel, etc.)

Cancellation Flow

Internet Cancellation

1. Customer navigates to subscription detail → clicks "Request Cancellation"
2. Portal creates Salesforce Case with WHMCS Service ID
3. Portal updates Opportunity with cancellation data:
   • ScheduledCancellationDateAndTime__c = end of cancellation month
   • CancellationNotice__c = "有" (received)
   • LineReturn__c = "NotYet"
4. Agent processes Case:
   • Terminates WHMCS service on scheduled date
   • Updates LineReturn__c for equipment return tracking
   • Updates Opportunity to "〇Cancelled"

Note: WHMCS service termination is manual (agent work). The portal updates Salesforce, but does not automatically terminate in WHMCS.

SIM Cancellation

1. Customer navigates to subscription detail → SIM Management → Cancel
2. Portal calls Freebit PA02-04 cancellation API
3. Service is scheduled for cancellation at end of selected month

Opportunity ↔ WHMCS Linking

How They're Connected

After order provisioning, the Opportunity is linked to WHMCS via:

Opportunity.WHMCS_Service_ID__c = WHMCS Service ID (e.g., 456)

Provisioning Flow

1. Order placed → Opportunity created (Stage = "Post Processing")
2. Order approved → Fulfillment runs
3. WHMCS AddOrder API called → returns serviceIds
4. Opportunity updated:
   • WHMCS_Service_ID__c = service ID from WHMCS
   • StageName = "Active"

Finding Opportunity for Cancellation

When customer requests cancellation, the portal:

1. Takes WHMCS subscription ID from the portal
2. Queries Salesforce: WHERE WHMCS_Service_ID__c = {subscriptionId}
3. Updates the found Opportunity with cancellation data

If Opportunity is Cancelled but WHMCS is Not

This can happen if the agent doesn't complete the WHMCS termination. Result:

• Customer continues to be billed (WHMCS active)
• Service remains active (not terminated)
• Salesforce says cancelled, WHMCS says active

Prevention: Agent must follow Case instructions to terminate WHMCS service on the scheduled date.

Customer Profile Data

Data Sources

Field	Source	Editable in Portal?
Email	Portal DB / WHMCS	Yes
Phone Number	WHMCS	Yes
First Name	WHMCS	No (read-only)
Last Name	WHMCS	No (read-only)
Customer Number	WHMCS Custom Field (ID: 198)	No (read-only)
Date of Birth	WHMCS Custom Field (ID: 201)	No (read-only)
Gender	WHMCS Custom Field (ID: 200)	No (read-only)
Address	WHMCS	Yes

Environment Variables

# WHMCS custom field IDs (must match your WHMCS installation)
WHMCS_CUSTOMER_NUMBER_FIELD_ID=198  # Default
WHMCS_DOB_FIELD_ID=201              # Default
WHMCS_GENDER_FIELD_ID=200           # Default

If customer number, DOB, or gender aren't showing, verify these field IDs match your WHMCS custom fields.