# Identity Verification

## Overview

This journey covers the residence card (ID) verification process that customers must complete before they can place certain orders (such as SIM activation). Customers upload a photo or scan of their residence card, which is then reviewed by a support agent. Verification status is tracked on the Salesforce Account record. The portal shows the current status and allows re-upload if the document is rejected.

## Portal Flow

### Where to Find ID Verification

ID verification is available in two locations:

1. **Profile / Settings page** (`/account/settings`): The verification card is integrated into the settings page alongside other profile information.
2. **Standalone verification page** (`/account/settings/verification`): This page is used when the customer is redirected from the checkout flow. It accepts a `returnTo` parameter so the customer can be sent back to checkout after uploading.

### Status: Not Submitted

1. When a customer has not yet submitted their residence card, the page shows:
   - A status pill labeled **"Not Submitted"** (amber)
   - An informational banner titled "Upload required" explaining what to do
   - Instructions listing:
     - Upload a clear photo or scan of your residence card (JPG, PNG, or PDF)
     - Make sure all text is readable and the full card is visible
     - Avoid glare/reflections and blurry photos
     - Maximum file size: 5 MB
2. A **file picker** lets the customer select a file from their device.
   - Accepted formats: JPG, PNG, PDF, and other image formats
3. After selecting a file, a preview appears showing the file name, with a **Change** button to select a different file.
4. Click **Submit Document** to upload the file.
5. A loading state shows "Uploading..." while the file is being sent.
6. If the upload came from a checkout redirect (with a `returnTo` parameter), a **Back to checkout** button also appears.

### Status: Under Review (Pending)

1. After successful upload, the status changes to **"Under Review"** (blue).
2. The page shows:
   - A status pill labeled **"Under Review"**
   - An informational banner: "We'll verify your residence card before activating SIM service."
   - A **submission timestamp** showing when the document was submitted
3. The customer cannot upload a new document while the current one is under review.
4. If arriving from checkout, a **Continue to Checkout** button appears so the customer can proceed (orders can be submitted while verification is pending, though they will not be fulfilled until verification completes).

### Status: Verified

1. When the agent approves the document, the status changes to **"Verified"** (green).
2. The page shows:
   - A status pill labeled **"Verified"**
   - A success banner: "Your residence card is on file and approved. No further action is required."
3. The customer cannot upload a new document (the upload form is hidden).
4. If arriving from checkout, a **Continue to Checkout** button appears.

### Status: Rejected

1. If the agent rejects the document, the status changes to **"Action Needed"** (amber).
2. The page shows:
   - A status pill labeled **"Action Needed"**
   - A warning banner titled "Verification rejected" with the agent's rejection reason (reviewer notes)
   - Instructions for re-uploading
   - The **submission and review timestamps** showing when the document was submitted and reviewed
3. The **file picker** reappears so the customer can upload a corrected document.
4. After re-uploading, the status returns to "Under Review."

### Accepted File Types and Limits

| Property     | Value                                       |
| ------------ | ------------------------------------------- |
| File types   | JPG, JPEG, PNG, PDF, other images           |
| Maximum size | 5 MB                                        |
| Tip          | Higher resolution photos make review faster |

## What Happens in Salesforce

- **File storage**: The uploaded document is stored as a **ContentVersion** record in Salesforce, linked to the customer's Account.
- **Account fields updated on upload**:
  - `Id_Verification_Status__c` is set to **"Submitted"**
  - `Id_Verification_Submitted_Date_Time__c` is set to the upload timestamp
- **Agent review**: The agent reviews the document in Salesforce and updates the Account:
  - **Approved**: Sets `Id_Verification_Status__c` to **"Verified"** and `Id_Verification_Verified_Date_Time__c` to the review time.
  - **Rejected**: Sets `Id_Verification_Status__c` to **"Rejected"**, fills `Id_Verification_Rejection_Message__c` with the reason, and optionally `Id_Verification_Note__c` with internal notes.
- **Platform Event**: When the verification status changes, Salesforce fires a Platform Event (`Account_Update__e`). The portal receives this event and automatically refreshes the verification status in real time -- the customer sees the update without needing to refresh the page.
- **Notification**: When the status changes to Verified or Rejected, the portal creates an in-app notification for the customer:
  - Verified: "ID verification complete" with a link to continue checkout
  - Rejected: "ID verification requires attention" with a link to resubmit

### Salesforce Account Fields Reference

| Field                                    | 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 approval  |
| `Id_Verification_Note__c`                | Text     | Agent        | After review    |
| `Id_Verification_Rejection_Message__c`   | Text     | Agent        | If rejected     |

### Status Values in Salesforce

| Salesforce Value | Portal Display | Can Submit Orders? |
| ---------------- | -------------- | ------------------ |
| Not Submitted    | Not Submitted  | No                 |
| Submitted        | Under Review   | Yes                |
| Verified         | Verified       | Yes                |
| Rejected         | Action Needed  | No                 |

## Key Things to Verify

- **Upload flow**: Select a file (JPG, PNG, or PDF under 5 MB), click Submit Document, and verify:
  - The file appears as a ContentVersion record in Salesforce linked to the customer's Account
  - `Id_Verification_Status__c` changes to "Submitted"
  - `Id_Verification_Submitted_Date_Time__c` is set
  - The portal shows "Under Review" status
- **Rejection flow**: Have an agent reject the verification in Salesforce with a rejection message. Verify:
  - The portal updates to show "Action Needed" with the rejection reason displayed
  - The upload form reappears so the customer can re-upload
  - An in-app notification is created: "ID verification requires attention"
- **Approval flow**: Have an agent approve the verification in Salesforce. Verify:
  - The portal updates to show "Verified" with a green status badge
  - The upload form is hidden
  - An in-app notification is created: "ID verification complete"
- **Real-time updates**: Status changes in Salesforce should appear in the portal within a few seconds (via Platform Events) without manual page refresh.
- **Checkout redirect**: Navigate to `/account/settings/verification?returnTo=/account/checkout`. After upload, the "Continue to Checkout" button should correctly navigate back to the checkout page.
- **File validation**: Try uploading a file larger than 5 MB or an unsupported format and verify the portal shows an appropriate error.
- **Error handling**: If the upload fails (e.g., network issue), an error message appears and the customer can try again.