Assist_Design/docs/portal-guides/accounts-and-identity.md

Accounts & Identity

What to know about sign-up, WHMCS linking, and profile updates.

New Sign-Up Flow

• Input required: email, password, name, phone, full billing address, and Customer Number (from Salesforce).
• Salesforce check: we look up the Customer Number; if it already has a portal/WHMCS link, we stop and tell the user to log in.
• WHMCS account creation: we create a WHMCS client using the provided contact + address details. Required fields include first/last name, email, phone, address1, city, state, postcode, and country. Optional custom fields we set when provided:
  • Customer Number (custom field ID 198 by default)
  • Date of Birth
  • Gender
  • Nationality
• Portal records: we store a portal user (password hashed with Argon2) and an id_mapping row linking the portal user, WHMCS client ID, and Salesforce account ID.
• Salesforce flags: after creation we set the portal status on the Salesforce Account (status = Active, source = New Signup) and write the WHMCS Account ID back to Salesforce.
• Address ownership: WHMCS is the billing system of record. The address entered at sign-up becomes the WHMCS address used for invoices and checks.

If something goes wrong

• Customer Number not found or already mapped: we stop the flow and tell the user to log in instead.
• WHMCS already has this email: we ask the user to link instead of creating a duplicate.
• WHMCS creation fails: we show a clear “failed to create billing account” message; nothing is committed in the portal.
• Database write fails after WHMCS creation: we mark the WHMCS client as Inactive for cleanup and ask support to review.

Linking an Existing WHMCS User

• For users who already have a WHMCS account with this email:
  • We validate their WHMCS login.
  • We read the Customer Number from WHMCS custom field 198 (label “Customer Number”) and find the matching Salesforce Account.
  • We create a portal user (no password yet) and an id_mapping with WHMCS + Salesforce IDs.
  • We set Salesforce portal flags (status = Active, source = Migrated) and prompt the user to set a new portal password.
• Duplicate protection: if the WHMCS client or Salesforce account is already mapped to a portal user, we ask the user to log in instead of linking again.

If something goes wrong

• Invalid WHMCS credentials: we return “Invalid email or password.”
• WHMCS account not found: we return “No billing account found with this email.”
• Salesforce Customer Number missing in WHMCS: we tell the user to contact support (cannot link without it).
• Salesforce account lookup fails: we show a generic “unable to verify customer info” message and stop.

Profile & Address Updates

• Address and profile edits in the portal are written directly to WHMCS, and the WHMCS cache for that user is cleared so the change shows up immediately.
• Address is treated as authoritative in WHMCS; Salesforce receives address snapshots only when orders are created (so order records show the address used at checkout).
• Password changes are portal-only; WHMCS credentials are never stored in the portal.