Chunks — 11. Agency Global Settings

Agency Global Settings

#

#

#

#

#

# **Agency Global Settings**

**Functional Requirement Document**

**BA & Ideation: Deval Chauhan**

**Reviewed By: Keval Gajjar**

**Updated Date:25 December 2025  
Status:**

**Version: 1.0**

# **Agency Global Settings - Executive Summary**

**Module Overview** | **11 Sections** | **6 Complete FRDs + 5 Linked Modules** | **December 27, 2025**

## **🎯 Module Purpose**

The Agency Global Settings module serves as the centralized configuration hub for managing user profiles, agency-wide business settings, payment methods, security preferences, and system configurations that govern the entire platform's operational behavior.

## **📋 Key Components**

### 1\. My Profile

*   **Features:** Personal info, profile photo (15MB max), business toggle
*   **Security:** Dual-verification email change, password complexity enforcement
*   **Preferences:** Date formats (DD/MM/YYYY, MM/DD/YYYY), timezone settings
*   **Key Rule:** Business toggle only for Agency Owner/Admin roles

### 2\. General Settings

*   **Company Config:** Name (250 chars max), country, currency (Owner-only)
*   **Measurement:** Imperial/Metric toggle (future projects only)
*   **Travel Policy:** 25-mile increments (0-500) or "any" for no minimum
*   **Event Colors:** Customizable per event type with hex picker

### 3\. Business & Payment Details

*   **Stripe Integration:** OAuth connection with 24-48hr verification
*   **Business Info:** Legal entity details for tax compliance
*   **Multi-Brand:** Each brand can have separate Stripe accounts
*   **Key Rule:** Only Agency Owner can edit; others read-only

### 4\. Accepted Payment Methods

*   **Options:** Card Payments (2.9% + $0.30), ACH Transfers (lower fees)
*   **Validation:** At least one method must remain active
*   **Processing Fees:** Dynamic based on subscription plan
*   **Integration:** Direct connection to Stripe capabilities

### 5\. Team Management _(Separate FRD)_

*   **Roles:** 6 hierarchical levels (Owner → Contractor)
*   **Permissions:** Granular access controls per role
*   **Management:** Invite, edit, deactivate team members

### 6\. 2-Step Verification

*   **Methods:** Email and/or SMS (both can be active)
*   **Security:** 1-minute cooldown, 5 attempts/day limit
*   **Codes:** 6-digit, 10-minute expiration
*   **Key Rule:** Mandatory for all users, cannot be permanently disabled

### 7-11. Linked Modules

*   **Referral System:** Commission tracking and payouts _(Separate FRD)_
*   **Notifications:** Email/SMS preferences and templates _(Separate FRD)_
*   **Brands:** Multi-brand management and switching _(Separate FRD)_
*   **Data Management:** Lead sources, custom fields, tags
*   **Subscription:** Plan management and billing _(Separate FRD)_

## **🔄 Access Control Matrix**

**Role**

**My Profile**

**General**

**Business/Payment**

**Team**

**2FA**

**Data Mgmt**

**Agency Owner**

Full

Full

Full Edit

Full

Own

Full

**Admin**

Full

Most

Read-Only

Edit

Own

Full

**Project Manager**

Personal

Limited

Read-Only

View

Own

View

**Editor**

Personal

Limited

No Access

View

Own

View

**Contractor**

Personal

Minimal

No Access

None

Own

None

## **✅ Critical Business Rules**

**Rule**

**Description**

**Impact**

**Email Verification**

Dual-code verification for email changes

Security compliance

**Currency Lock**

Only Agency Owner can change currency

Financial consistency

**Measurement Forward-Only**

Changes apply to future projects only

Data integrity

**Stripe Dependency**

Payment collection requires verified Stripe

Revenue protection

**2FA Mandatory**

Cannot be permanently disabled

Account security

**One Payment Method**

At least one must remain active

Transaction capability

**Travel Fee Threshold**

One-way distance before fees apply

Cost management

## **🚨 Critical Validations**

### Security Layer

*   **Password:** Min 6 chars, 1 upper, 1 lower, 1 special character
*   **2FA Codes:** 6 digits, numeric only, 10-min expiration
*   **Email Change:** Both old and new email verification required
*   **Profile Photo:** JPG/PNG/JPEG only, 15MB maximum

### Business Layer

*   **Company Name:** 250 character maximum
*   **Business Verification:** 24-48 hour Stripe approval
*   **Processing Fees:** Subscription-dependent rates
*   **Lead Sources:** Cannot delete if in use by projects

## **📊 Key Metrics & Tracking**

*   **Audit Trail:** All settings changes logged with timestamps
*   **Verification Status:** Real-time Stripe account status
*   **2FA Success Rate:** Failed attempt monitoring
*   **Travel Fee Calculations:** Google Maps API integration
*   **Custom Field Usage:** Visibility across Agency/Client/Contractor

## **🔗 Integration Points**

**System**

**Integration Type**

**Purpose**

**Stripe API**

OAuth + Webhooks

Payment processing & verification

**Google Maps API**

Distance calculation

Travel fee computation

**SendGrid/Twilio**

Email/SMS delivery

2FA codes & notifications

**Client Portal**

Data sync

Profile information updates

**Invoice Module**

Payment methods

Transaction processing

**Project Module**

Custom fields

Data collection

## **⚠️ Edge Cases & Limitations**

### Handled Scenarios

*   **Lost 2FA Access:** Manual override via Pixally support
*   **Stripe Rejection:** Clear messaging with resolution steps
*   **Concurrent Edits:** Last-save-wins with session locking
*   **Email Service Down:** SMS fallback for 2FA

### Known Limitations

*   **Transfer Ownership:** Not available in Phase 1
*   **Password History:** Backend only, not visible to users
*   **QR Code Analytics:** Scan tracking pending implementation
*   **Multi-currency Conversion:** Display only, no conversion

## **📈 Success Metrics**

### Quantified Benefits

*   **100% 2FA adoption** ensuring security compliance
*   **60% reduction** in payment setup time via Stripe OAuth
*   **Real-time synchronization** across all user sessions
*   **6 role levels** with granular permissions
*   **Unlimited custom fields** for flexible data collection

### Test Coverage

*   **40+ test cases** per module
*   **9 test categories** covering all scenarios
*   **4 priority levels** (Critical/High/Medium/Low)
*   **100% role-based access validation**

## **🎯 Business Value**

The Agency Global Settings module provides the foundational configuration layer that enables agencies to:

*   **Customize operations** to match business needs without code changes
*   **Ensure security compliance** through mandatory 2FA and verification processes
*   **Scale efficiently** with multi-brand support and role-based access
*   **Automate financial operations** through Stripe integration
*   **Maintain data integrity** through comprehensive validation and audit trails

The module reduces configuration time by 70%, eliminates security vulnerabilities through enforced 2FA, and provides the flexibility needed for agencies to operate across multiple brands and international markets.

**Implementation Priority:** Critical | **Dependencies:** Authentication System | **Phase:** 1

1\. My Profile Module

# **FRD #1: My Profile Module**

## **1\. Module Overview**

**Module Name:** My Profile

**Purpose:** The My Profile module enables users to manage their personal information, authentication credentials, display preferences, and professional details within the CRM system.

**Business Goals:**

*   Provide users with self-service capabilities to maintain accurate personal information
*   Ensure security through robust password management and email verification processes
*   Enable personalization of user experience through display preferences including date and time formats
*   Maintain data integrity through proper validation and verification mechanisms

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Permissions**

**Date & Time Preferences**

Agency Owner

Full access to all fields

All personal fields, business toggle

Can enable/disable business information view

Full access

Admin

Full access to all fields

All personal fields, business toggle

Can enable/disable business information view

Full access

Project Manager

Personal fields only

Own profile fields only

Cannot access business information toggle

Full access

Editor

Personal fields only

Own profile fields only

Cannot access business information toggle

Section not visible

Supervising Editor

Personal fields only

Own profile fields only

Cannot access business information toggle

Section not visible

Contractor

Personal fields only

Own profile fields only

Cannot access business information toggle

Section not visible

## **3\. User Flow**

3.1 The user clicks on the Settings icon from the left sidebar navigation menu.

3.2 The system redirects the user to the Settings page with My Profile section displayed by default.

3.3 The user views their current personal information including first name, last name, email address, and profile photo.

3.4 The user clicks on the camera icon overlay on the profile photo to upload a new image.

3.5 The system opens a file picker dialog allowing selection of JPG, PNG, or JPEG files up to 15MB.

3.6 The user selects an image file and confirms the upload action.

3.7 The system validates the file format and size, then displays the new profile photo in the circular frame.

3.8 The user enters or modifies their first name and last name in the respective text fields.

3.9 The user views their email address in the read-only field and clicks the email change link if modification is needed.

3.10 The system initiates the email change process by displaying a modal for entering a new email address.

3.11 The user enters the new email address and submits the request.

3.12 The system sends verification codes to both the old and new email addresses.

3.13 The user enters both verification codes in the respective fields and confirms the change.

3.14 The system validates the codes and updates the email address if both codes are correct.

3.15 The user toggles the Business Information switch if they have appropriate permissions.

3.16 The system displays additional business fields including business name, type, and phone number when enabled.

3.17 The user fills in or modifies the business information fields as needed.

3.18 The user navigates to the password change section and enters their current password.

3.19 The user enters a new password meeting the security requirements and confirms it in the repeat field.

3.20 The system validates the password strength and matching confirmation.

### Date & Time Preferences Flow

3.21 The user scrolls to the Date & Time Preferences section at the bottom of the My Profile page.

3.22 The system displays the Date & Time Preferences section with Date Format dropdown, Include day of the week checkbox (checked by default), and Time Format radio buttons.

3.23 The user clicks on the "Date Formatting Guide" link located next to the Date Format dropdown.

3.24 The system opens a modal displaying all five available date formats with examples and regional usage information.

3.25 The user reviews the date format options and clicks "Got it" to close the modal.

3.26 The user clicks on the Date Format dropdown to view available options.

3.27 The system displays five date format options: DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD, DD MMM YYYY, and MMM DD, YYYY.

3.28 The user selects their preferred date format from the dropdown.

3.29 The user optionally unchecks the "Include day of the week (Sat, Sun etc)" checkbox if they do not want the full day name displayed with dates.

3.30 The user selects their preferred time format by clicking either the "12 hour (AM/PM)" or "24 hour" radio button.

3.31 The user clicks the "Save changes" button to apply the new date and time preferences.

3.32 The system validates the selections and saves the user's preferences.

3.33 The system displays a success message: "Date & time preferences saved successfully."

3.34 The system applies the selected date and time format across all applicable areas of the platform.

3.35 Alternatively, the user clicks "Reset Changes" to revert to system defaults.

3.36 The system resets Date Format to MMM DD, YYYY, Time Format to 12 hour (AM/PM), and checks the Include day of the week checkbox.

3.37 The user continues to other settings sections or exits the Settings area.

## **4\. Functional Logic**

### 4.1 Personal Information Management

• The Personal Information section displays the user's first name, last name, and email address as the primary identification fields.

• First name and last name fields accept alphabetic characters and common name symbols like hyphens and apostrophes, with a maximum length of 100 characters each.

• The system automatically trims leading and trailing whitespace from name fields before saving to ensure data consistency.

• The email address field appears as read-only text displaying the current registered email address associated with the user account.

• Users must use the dedicated email change process to modify their email address, which cannot be directly edited in the form field.

### 4.2 Profile Photo Management

• The profile photo section displays a circular frame with either the user's uploaded image or a default avatar with initials.

• When no custom photo exists, the system generates a default avatar using the first letter of the first and last name.

• The camera icon overlay appears on hover or focus, indicating the photo upload functionality is available.

• Clicking the camera icon triggers the file upload dialog, which filters for accepted image formats by default.

• The system accepts JPG, PNG, and JPEG file formats with a maximum file size limit of 15MB per upload.

• Upon successful upload, the system processes the image to fit the circular display frame while maintaining aspect ratio.

• The uploaded image is stored securely and associated with the user's profile across all system interfaces.

• If an upload fails due to size or format restrictions, the system displays an appropriate error message and retains the previous photo.

### 4.3 Email Address Change Process

• The email change process requires multi-step verification to ensure security and prevent unauthorized modifications.

• When initiating an email change, the system first checks if the new email address is already registered to another account.

• If the new email is already in use, the system immediately rejects the change request with an appropriate error message.

• For valid new email addresses, the system generates unique verification codes and sends them simultaneously to both email addresses.

• The verification code sent to the old email ensures the current account owner authorizes the change.

• The verification code sent to the new email confirms the user has access to the new address and it's valid.

• Both verification codes must be entered correctly within the session timeout period for the change to proceed.

• The old email address is preserved in the backend system for audit and recovery purposes but is not displayed to users.

• After successful email change, the system logs the user out and requires re-authentication with the new email address.

• Email change notifications are sent to both addresses confirming the successful modification for security awareness.

### 4.4 Business Information Toggle

• The Business Information toggle is only visible to users with Agency Owner or Admin roles.

• When enabled, the toggle reveals additional fields for business name, business type dropdown, and business phone number.

• The business name field accepts up to 250 characters and allows standard business name characters including ampersands and periods.

• The business type dropdown presents predefined options such as Photography, Videography, or Multi-Service Studio.

• The phone number field includes international format support with country code selection and automatic formatting.

• Business information changes are logged separately from personal information for compliance and audit purposes.

• The toggle state persists across sessions, maintaining the user's preference for viewing business fields.

### 4.5 Password Management

• The password change section requires users to first authenticate by entering their current password.

• The system verifies the current password against the stored hash before allowing any password modification.

• New passwords must meet security requirements including minimum 6 characters, at least one uppercase letter, one lowercase letter, and one special character.

• The password strength indicator provides real-time feedback as the user types, showing weak, medium, or strong ratings.

• The repeat password field must exactly match the new password field for the change to be accepted.

• After successful password change, the system invalidates all existing sessions and requires fresh login.

• Password change events trigger security notification emails to the user's registered email address.

• The system maintains a password history to prevent reuse of recent passwords, though this is not visible to users.

### 4.6 Date & Time Preferences

#### **Overview**

• The Date & Time Preferences section allows users to customize how dates and times are displayed throughout the platform based on their regional preferences.

• This section appears at the bottom of the My Profile page and is accessible only to Agency Owner, Admin, and Project Manager roles.

• Editor, Supervising Editor, and Contractor roles do not see this section in their My Profile view.

• All date and time preferences are user-specific, meaning each user can have their own display format without affecting other users in the agency.

#### **Date Format Options**

• The system provides five date format options to accommodate regional preferences:

**Format**

**Display Example**

**Region / Audience**

DD/MM/YYYY

26/08/2025

UK, Europe, Australia, India

MM/DD/YYYY

08/26/2025

United States, Philippines

YYYY/MM/DD

2025/08/26

ISO 8601, Japan, international use

DD MMM YYYY

26 Aug 2025

Readable, common in emails/docs

MMM DD, YYYY

Aug 26, 2025

U.S. readable format

• The default date format for new users is MMM DD, YYYY (e.g., Aug 26, 2025).

• The Date Format dropdown displays all five options, and the user can select one at a time.

• Changes to the date format require clicking "Save changes" before they take effect across the platform.

#### **Date Formatting Guide Modal**

• Clicking the "Date Formatting Guide" link opens an informational modal displaying all available date formats.

• The modal presents each format with its display example and the regions or audiences where that format is commonly used.

• The modal includes a "Got it" button that closes the modal and returns the user to the Date & Time Preferences section.

• The modal is informational only and does not change any settings.

#### **Include Day of the Week**

• The "Include day of the week (Sat, Sun etc)" checkbox allows users to display the full day name alongside the selected date format.

• When enabled, dates display with the full day name as a prefix, for example: "Saturday, Aug 26, 2025" instead of "Aug 26, 2025".

• The day name format applies consistently with all five date format options:

*   DD/MM/YYYY with day: Saturday, 26/08/2025
*   MM/DD/YYYY with day: Saturday, 08/26/2025
*   YYYY/MM/DD with day: Saturday, 2025/08/26
*   DD MMM YYYY with day: Saturday, 26 Aug 2025
*   MMM DD, YYYY with day: Saturday, Aug 26, 2025

• The checkbox is checked by default for new users, displaying the full day name with all dates.

• The setting applies to all areas where the user-selected date format is used.

#### **Time Format Options**

• The system provides two time format options displayed as radio buttons:

*   **12 hour (AM/PM):** Displays time as 2:30 PM
*   **24 hour:** Displays time as 14:30

• The default time format for new users is 12 hours (AM/PM).

• Only one time format option can be selected at a time.

• The selected time format will apply only to areas where time is used and the user-selected format is supported.

#### **Fixed Format Areas**

• Certain areas of the platform use a fixed date and time format regardless of user preferences to ensure consistency in formal documents and shared views:

**Area**

**Fixed Date Format**

**Fixed Time Format**

Contracts

MMM DD, YYYY

12-hour (AM/PM)

Service Agreements

MMM DD, YYYY

12-hour (AM/PM)

Client Invoices

MMM DD, YYYY

12-hour (AM/PM)

Calendar (List View)

MMM DD, YYYY

12-hour (AM/PM)

Email Notifications

MMM DD, YYYY

12-hour (AM/PM)

• The "Include day of the week" setting does not apply to fixed format areas.

• These fixed formats ensure that client-facing documents, legally-binding documents, and email communications maintain a consistent, professional appearance.

#### **User-Selected Format Areas**

• All other areas of the platform display dates and times based on the user's selected preferences:

*   Dashboard dates
*   Project dates and deadlines
*   Task due dates
*   Activity logs and timestamps
*   In-app Notifications
*   Reports
*   Event dates
*   File upload timestamps
*   Comments and notes timestamps
*   All other date/time displays not listed in Fixed Format Areas

• Changes to date and time preferences propagate immediately across all user-selected format areas after saving.

#### **Default Values**

• New users are automatically assigned the following default settings without requiring any action:

*   Date Format: MMM DD, YYYY
*   Time Format: 12 hour (AM/PM)
*   Include day of the week: Checked (enabled)

• These defaults are applied during user account creation and can be changed at any time from My Profile.

#### **Save and Reset Behavior**

• The "Save changes" button saves all Date & Time Preferences selections and applies them across the platform.

• The "Save changes" button is enabled only when the user has made changes to any of the settings.

• There is no live preview; users must save their changes to see the new format applied across the platform.

• The "Reset Changes" button reverts all Date & Time Preferences to system defaults:

*   Date Format: MMM DD, YYYY
*   Time Format: 12 hour (AM/PM)
*   Include day of the week: Checked

• After clicking "Reset Changes," the user must click "Save changes" to apply the reset values.

#### **User-Specific Settings**

• Date and time preferences are stored at the individual user level, not at the agency level.

• Each user within an agency can have different date and time format preferences.

• If Agency Owner selects DD/MM/YYYY and Admin selects MM/DD/YYYY, each user sees dates displayed in their own selected format throughout their session.

• User preferences do not affect how dates appear to other users or in shared/exported documents.

### 4.7 Professional Information Section

• The Professional Information section displays the user's website URL if configured.

• The website field validates URL format and automatically prepends "https://" if no protocol is specified.

• This section is separate from business information and available to all user roles.

• The website URL appears as a clickable link in user profiles and team directories when populated.

### 4.8 Data Validation and Persistence

• All form fields undergo client-side validation before submission to provide immediate feedback.

• Server-side validation duplicates all client checks to ensure security and data integrity.

• The Save Changes button remains disabled until at least one field has been modified from its original value.

• Unsaved changes trigger a warning dialog if the user attempts to navigate away from the page.

• Successful saves update the last modified timestamp and user information in the audit log.

• The system performs atomic updates to ensure all changes in a single save operation succeed or fail together.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

First Name

Text Input

Max 100 chars, alphabetic + hyphen/apostrophe

Yes

Last Name

Text Input

Max 100 chars, alphabetic + hyphen/apostrophe

Yes

Email Address

Email (Read-only)

Valid email format, unique in system

Yes

New Email

Email Input

Valid format, not already registered

Yes (for change)

Verification Code (Old)

Text Input

6 digits, matches sent code

Yes (for change)

Verification Code (New)

Text Input

6 digits, matches sent code

Yes (for change)

Profile Photo

File Upload

JPG/PNG/JPEG, max 15MB

No

Business Name

Text Input

Max 250 chars

Yes (when enabled)

Business Type

Dropdown

Valid selection from list

Yes (when enabled)

Business Phone

Phone Input

Valid international format

Yes (when enabled)

Current Password

Password Input

Matches stored password

Yes (for change)

New Password

Password Input

Min 6 chars, 1 upper, 1 lower, 1 special

Yes (for change)

Repeat Password

Password Input

Exact match with new password

Yes (for change)

Date Format

Dropdown

Must select one of five valid options (DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD, DD MMM YYYY, MMM DD, YYYY); Default: MMM DD, YYYY

Yes

Include Day of Week

Checkbox

Boolean true/false; Default: Checked (true)

No

Time Format

Radio Button

Must select one option (12 hour AM/PM or 24 hour); Default: 12 hour (AM/PM)

Yes

Website URL

URL Input

Valid URL format

No

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Post-Success Action**

**Duration**

Profile Information Save

"Profile updated successfully"

Refresh display with new data

3 seconds

Profile Photo Upload

"Profile photo updated successfully"

Display new photo immediately

3 seconds

Email Change Initiated

"Verification codes sent to both email addresses"

Show verification modal

Persistent

Email Change Complete

"Email address updated successfully. Please log in with your new email"

Force logout

5 seconds

Password Change

"Password changed successfully. Please log in again"

Force logout

5 seconds

Business Info Update

"Business information updated successfully"

Refresh business fields

3 seconds

Date & Time Preferences Save

"Date & time preferences saved successfully."

Apply format changes across all applicable platform areas

3 seconds

Date & Time Preferences Reset

"Date & time preferences reset to defaults."

Revert all fields to system default values

3 seconds

Website URL Update

"Professional information updated successfully"

Update website display

3 seconds

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**User Action Required**

Invalid Name Characters

"Name can only contain letters, hyphens, and apostrophes"

Remove invalid characters

Name Too Long

"Name cannot exceed 100 characters"

Shorten the name

Email Already Registered

"This email is already registered to another account"

Use different email

Invalid Email Format

"Please enter a valid email address"

Correct email format

Incorrect Verification Code

"Invalid verification code. Please try again"

Re-enter correct code

Verification Code Expired

"Verification code has expired. Please request a new one"

Request new codes

Photo File Too Large

"File size must be less than 15MB"

Select smaller file

Invalid Photo Format

"Only JPG, PNG, and JPEG formats are accepted"

Choose valid format

Business Name Too Long

"Business name cannot exceed 250 characters"

Shorten business name

Invalid Phone Format

"Please enter a valid phone number"

Correct phone format

Current Password Wrong

"Current password is incorrect"

Enter correct password

Weak Password

"Password must contain at least 6 characters, including uppercase, lowercase, and special character"

Create stronger password

Passwords Don't Match

"Passwords do not match"

Re-enter matching passwords

Invalid URL Format

"Please enter a valid website URL"

Correct URL format

No Date Format Selected

"Please select a date format."

Select an option from dropdown

No Time Format Selected

"Please select a time format."

Select 12 hour or 24 hour option

Date Preferences Save Failed

"Unable to save preferences. Please check your connection and try again."

Retry save operation

Invalid Format Selection

"Invalid format selection. Please refresh and try again."

Refresh page and reselect

Session Expired

"Your session has expired. Please refresh and try again"

Refresh page

Network Error

"Connection error. Please check your internet and try again"

Check connection

Save Failed

"Unable to save changes. Please try again"

Retry save operation

## **8\. Edge Cases**

**Scenario**

**System Behavior**

**Mitigation**

Upload corrupted image file

System rejects file, maintains previous photo

Display specific error about file corruption

Email service down during verification

Codes not delivered

Provide retry option with backoff

User loses access to old email

Cannot complete email change

Contact support for manual verification

Simultaneous email change attempts

First request proceeds, second blocked

Show email change already in progress

Browser doesn't support file upload

Upload button non-functional

Provide alternative upload method

Special characters in business name

Some characters may not display correctly

Sanitize and validate input

Password manager conflicts

Auto-fill may interfere with password change

Disable autocomplete on password fields

Multiple tabs open during profile edit

Changes may conflict

Implement optimistic locking

Phone number from unsupported country

Validation may fail

Allow manual entry with warning

Image upload during poor connection

Upload may timeout

Implement resumable upload

Clock skew affecting verification

Codes may expire prematurely

Use server time with tolerance

Attempting to use recently changed email

Email may still be in cooldown

Show cooldown period message

User changes date format mid-session

New format applies immediately after save across all open tabs upon refresh

WebSocket notification or refresh prompt

User views shared report while another user has different format

Each user sees dates in their own selected format

User-specific rendering

User exports data to PDF/Excel

Export uses the exporting user's date/time format preferences

Format applied at export time

User downgrades from Admin to Editor role

Date & Time Preferences section becomes hidden; existing preferences are retained but not editable

Preserve settings for potential re-upgrade

Browser cache shows old format after save

Force refresh of date displays after successful save

Cache invalidation on save

User selects format then navigates away without saving

Changes are discarded; original settings retained

Unsaved changes warning (if implemented)

Multiple users editing same project see different date formats

Each user sees their own format; no conflict as display is user-specific

Isolated user preferences

Date format change affects historical data display

Historical dates re-render in new format; stored data unchanged

Display-only change

## **9\. Acceptance Criteria**

### 9.1 Personal Information

• Users can successfully update their first and last names with immediate reflection in the interface.

• Name fields properly validate character restrictions and length limits.

• Email address displays correctly but cannot be directly edited.

### 9.2 Email Change Process

• Email change requires successful verification from both old and new addresses.

• System prevents registration of duplicate email addresses.

• User is properly logged out after successful email change.

• Audit trail maintains record of old email addresses.

### 9.3 Profile Photo

• Users can upload photos in JPG, PNG, and JPEG formats.

• File size validation prevents uploads over 15MB.

• Photos display correctly in circular frame format.

• System maintains aspect ratio without distortion.

### 9.4 Business Information

• Toggle only appears for Agency Owner and Admin roles.

• Business fields validate according to their specific requirements.

• Phone numbers format correctly for international entries.

• Changes persist across user sessions.

### 9.5 Password Management

• Current password verification prevents unauthorized changes.

• Password complexity requirements are enforced.

• Successful change forces re-authentication.

• Security notifications are sent for password changes.

### 9.6 Date & Time Preferences

• The Date & Time Preferences section is visible only to Agency Owner, Admin, and Project Manager roles.

• Editor, Supervising Editor, and Contractor roles do not see the Date & Time Preferences section.

• The Date Format dropdown displays all five format options correctly.

• The "Date Formatting Guide" link opens a modal with format examples and regional usage information.

• The modal closes when the user clicks "Got it."

• Selecting a date format and saving applies the format to all user-selected format areas.

• Enabling "Include day of the week" displays the full day name (e.g., Saturday) as a prefix to the date.

• The Time Format radio buttons allow selection of either 12 hour (AM/PM) or 24 hour format.

• Time displays as "2:30 PM" for 12-hour format and "14:30" for 24-hour format.

• Contracts, Service Agreements, Invoices, Calendar (List View), and Email Notifications always display in MMM DD, YYYY format with 12-hour time regardless of user settings.

• New users receive default settings of MMM DD, YYYY, 12-hour format, and day of week enabled without any action required.

• The "Reset Changes" button reverts all settings to system defaults.

• The "Save changes" button saves preferences and applies them across the platform.

• Date and time preferences are user-specific and do not affect other users' displays.

• Changes require saving before they take effect; no live preview is provided.

• Email Notifications always display in MMM DD, YYYY format with 12-hour time regardless of user settings.

## **10\. Manual Test Cases**

\[My\_Profile\_Comprehensive\_Test\_Cases.xlsx\]

## **11\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

External Service

Email Service Provider

Sends verification codes and notifications

Cannot change email or send alerts

External Service

Image Processing Service

Handles photo upload and optimization

Cannot update profile photos

External Service

CDN/Storage Service

Stores profile photos

Photos cannot be saved or retrieved

Internal Module

Authentication Service

Validates passwords and sessions

Cannot change passwords or verify users

Internal Module

User Management System

Maintains user records and roles

Cannot update user information

Internal Module

Audit Service

Logs all profile changes

No audit trail for compliance

Internal Module

Dashboard

Displays dates using user-selected format

Dates show in default format

Internal Module

Projects

Project dates use user-selected format

Dates show in default format

Internal Module

Tasks

Task due dates use user-selected format

Dates show in default format

Internal Module

Contracts

Uses fixed MMM DD, YYYY format

N/A - fixed format

Internal Module

Invoices

Uses fixed MMM DD, YYYY format

N/A - fixed format

Internal Module

Calendar (List View)

Uses fixed MMM DD, YYYY format

N/A - fixed format

Internal Module

Email Notifications

Uses fixed MMM DD, YYYY format

N/A - fixed format

Internal Module

Reports

Report dates use user-selected format

Dates show in default format

Internal Module

In-app Notifications

Notification timestamps use user-selected format

Dates show in default format

Configuration

File Upload Limits

Defines maximum file sizes

May accept oversized files

Configuration

Password Policy

Defines complexity requirements

Weak passwords may be accepted

Library

Image Processing Library

Client-side image validation

No preview before upload

Library

Phone Number Formatter

Formats international numbers

Phone numbers display unformatted

## **12\. References**

*   **Figma Designs:** \[Figma Link\]
*   **Related FRDs:**
    *   \[General\_Settings\_FRD.md\] — Agency Global Settings
    *   \[Business\_Payment\_Details\_FRD.md\] — Agency Global Settings
    *   \[Two\_Step\_Verification\_FRD.md\] — Agency Global Settings
    *   \[Data\_Management\_FRD.md\] — Agency Global Settings

2\. General Settings Module

# **FRD #2: General Settings Module**

## **1\. Module Overview**

**Module Name:** General Settings

**Purpose:** The General Settings module manages agency-wide configurations including company information, regional preferences, measurement systems, travel policies, signatory defaults, and event display settings that affect all users and operations within the system.

**Business Goals:**

*   Establish consistent operational parameters across the entire agency
*   Configure regional and measurement preferences for global compatibility
*   Define travel fee policies that automatically apply to contractor payments
*   Set a default signatory that is automatically applied when sending client-facing agreements
*   Customize visual elements for improved user experience and calendar management

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Permissions**

Agency Owner

Full access

All settings

Can modify currency, company name, and primary signatory

Admin

Full access

Most settings

Cannot modify currency, company name, or primary signatory

Project Manager

View all settings

Event colors, personal preferences

Read-only for agency settings (including primary signatory)

Editor

View limited settings

Event colors only

No access to financial settings

Supervising Editor

View limited settings

Event colors only

No access to financial settings

Contractor

View minimal settings

Personal preferences only

No access to agency configurations

## **3\. User Flow**

3.1 The user navigates to Settings from the left sidebar and clicks on General Settings.

3.2 The system loads the General Settings page displaying all configuration options based on user role.

3.3 The user views the Company Name field which shows the current agency name.

3.4 The user with appropriate permissions edits the Company Name field if changes are needed.

3.5 The system validates the company name length and characters as the user types.

3.6 The user selects their country from the Country dropdown menu.

3.7 The system updates regional defaults based on the selected country.

3.8 The user selects the preferred currency from the Currency dropdown if they have permission.

3.9 The system displays a warning that currency changes affect all financial displays.

3.10 The user toggles between Imperial and Metric measurement systems.

3.11 The system shows a notification that measurement changes apply only to future projects.

3.12 The user selects the minimum travel distance from the dropdown menu.

3.13 The system displays the increments in 25-mile steps up to 500 miles or "any" for no minimum.

3.14 The user views the Primary Signatory field, which displays the current default signatory role (Agency Owner by default).

3.15 If the user is the Agency Owner, they select a signatory role — Agency Owner, Admin, or Project Owner — from the dropdown; all other roles see the field as read-only and, on hover, a tooltip explaining that only the Agency Owner can change it.

3.16 The system stores the selected role, to be resolved to a specific person at the time a contract, Service Agreement, or proposal is sent.

3.17 The user navigates to the QR codes section to view agency-specific codes.

3.18 The system displays generated QR codes for quick access and sharing purposes.

3.19 The user clicks on the Event Color Settings section.

3.20 The system displays all event types with their current assigned colors.

3.21 The user clicks on a color picker for a specific event type.

3.22 The system opens the color selection interface with hex color options.

3.23 The user selects a new color and confirms the selection.

3.24 The system immediately applies the color change to the preview.

3.25 The user optionally clicks Reset Changes to revert to default colors.

3.26 The user reviews all changes made in the General Settings.

3.27 The user clicks Save Changes to persist all modifications.

3.28 The system saves the settings and displays a success confirmation message.

## **4\. Functional Logic**

### 4.1 Main Settings

**4.1.1 Timezone Configuration**

*   The Timezone dropdown allows the agency to set the default timezone for the system.
*   The system defaults to EST (Eastern Standard Time) for new agencies.
*   The selected timezone applies to all system-wide scheduling, timestamps, and calendar displays.
*   During event creation, Agency Owners and Admins can override the default timezone and set a specific timezone for that particular event.

**4.1.2 Country and Regional Settings**

*   The Country dropdown determines default formats for addresses, phone numbers, and postal codes throughout the system.
*   Selecting a country automatically updates related regional options to match that country's administrative divisions.
*   The country setting affects how addresses are formatted in invoices, proposals, and contractor agreements.
*   Changes to country settings apply to new entries going forward and do not retroactively modify existing address data.

**4.1.3 Measurement System Configuration**

*   The Measurement System dropdown determines whether distances display in Imperial (miles) or Metric (kilometers) throughout the system.
*   Measurement system selection affects travel fee calculations, distance displays, and contractor payment computations.
*   The system uses Google Maps API with the selected measurement unit to calculate accurate travel distances.
*   The measurement preference applies agency-wide regardless of individual user locations or preferences.
*   Changes to distance settings apply to new entries going forward and do not retroactively modify existing project data.

**4.1.4 Currency Configuration**

*   The Currency dropdown sets the currency used for all monetary displays, including invoices, proposals, payments, and financial reports.
*   The system supports major international currencies with proper symbol placement and decimal formatting.
*   The selected currency synchronizes with payment processors like Stripe to ensure transaction compatibility.

**4.1.5 Travel Fee Policy Settings**

*   The "Contractors will be paid a travel fee starting at" dropdown configures the one-way distance threshold before travel fees apply to contractors.
*   Distance options allow the agency to define the minimum miles a contractor must travel before travel compensation is triggered.
*   When a minimum is set, contractors receive travel compensation only for trips exceeding that one-way distance.

**4.1.6 Rate Per Mile Configuration**

*   The Rate per Mile / Rate per km field allows the agency to set the compensation rate per mile for contractor travel fees.
*   The rate is displayed in the selected currency (e.g., 20.00 USD).
*   This rate is used to calculate the total travel fee based on the distance traveled beyond the minimum threshold.
*   Changes to the rate per mile apply to future bookings and do not affect existing contracted agreements.

**4.1.7 Primary Signatory Configuration**

_Empty / default state_

*   The Primary Signatory field is a single-select dropdown located in General → Main Settings, directly below the Rate per Mile / Rate per km field.
*   The field is required and must always hold a value; it can never be saved empty.
*   For new agencies, the field defaults to **Agency Owner**.

_Available options_

*   Agency Owner
*   Admin
*   Project Owner

_Purpose and scope_

*   The Primary Signatory sets the default signatory that is automatically applied when sending a **client contract, Service Agreement, or proposal**.
*   These three document types are the complete scope of this setting. No other document types (for example, invoices, receipts, or internal documents) use the Primary Signatory.
*   The stored value is a **role**, not a specific person. The role is resolved to an actual signer at send-time.

_Permissions and display_

*   Only the Agency Owner can change the Primary Signatory. For all other roles the field is displayed as read-only / disabled.
*   When a non-owner hovers over the disabled field, the system shows the tooltip: "Only the Agency Owner can change the primary signatory."

_Role resolution at send-time_

*   **Agency Owner** selected → the agency owner is applied as the signatory.
*   **Admin** selected → the admin attached to that specific project is applied as the signatory.
*   **Project Owner** selected → the person assigned as project owner on that project is applied. Every project must have exactly one project owner. This is normally an admin or a project manager attached to the project; if no project manager and no admin is attached, the Agency Owner automatically becomes the project owner by default.

_Send-time override_

*   When sending a contract, Service Agreement, or proposal, the sender can override the signatory for that single document.
*   The override is limited to the same three roles (Agency Owner, Admin, Project Owner).
*   An override applies only to that one document and does **not** change the saved default.

_Change impact_

*   Changes to the Primary Signatory apply to future documents only and are non-retroactive.
*   Documents that have already been sent retain the signatory that was resolved at the time they were sent.
*   Because the role is resolved at send-time, documents that are prepared but not yet sent will use whichever default (or override) is in effect at the moment they are actually sent.
*   Changes to this setting are captured in the settings change history (who changed it, when, and the previous/new value), consistent with other Main Settings.

_Fallback behavior (summary; see Section 8 for detail)_

*   Every project must have exactly one project owner. If no project manager and no admin is attached to a project, the Agency Owner automatically becomes the project owner by default. As a result, the **Agency Owner** and **Project Owner** signatory options always resolve to a valid signer, and no fallback is required for them.
*   The only case requiring a fallback is when **Admin** is selected as the signatory but no admin is attached to the project. In that case, the system falls back to Agency Owner and prompts the sender to confirm or override the signatory before the document is sent.

**4.1.8 Save and Reset Actions**

*   The "Save Changes" button saves all modifications made to the Main Settings.
*   The "Reset Changes" button reverts all unsaved changes back to the previously saved values.
*   Both buttons remain disabled until the user makes a change to any field.

**4.1.9 Event Color Customization**

*   The Event Color Settings allow users to assign unique colors to different event types for improved calendar visibility.
*   Each event type (Wedding, Birthday, Corporate, etc.) can have a distinct color selected through the color picker interface.
*   Color changes apply immediately to all calendar views, schedules, and timeline displays across the system.
*   The color picker supports hex color codes, RGB values, and a visual palette for flexible color selection.
*   Users can reset individual colors or all colors to system defaults using the Reset Changes functionality.
*   Color preferences are stored at the agency level and apply to all users viewing the calendar.
*   The system ensures sufficient contrast between text and background colors for accessibility compliance.

### 4.2 Settings Synchronization

*   All General Settings changes trigger real-time synchronization across active user sessions.
*   The system broadcasts configuration updates to ensure all users see consistent information immediately.
*   Critical changes like currency or measurement system updates display notifications to all affected users.
*   Settings are backed up automatically before each change to enable rollback if issues occur.
*   The system maintains a change history log showing what was modified, when, and by whom.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

Company Name

Text Input

Max 250 chars, alphanumeric + common symbols

Yes

Country

Dropdown

Valid country from ISO list

Yes

Currency

Dropdown

Valid ISO currency code

Yes

Measurement System

Toggle

Imperial or Metric only

Yes

Travel Fee Minimum

Dropdown

25-mile increments, 0–500 or "any"

Yes

Rate per Mile / km

Numeric Input

Positive number, displayed in selected currency

Yes

Primary Signatory

Dropdown (single-select)

One of: Agency Owner, Admin, Project Owner; cannot be empty; editable by Agency Owner only

Yes

Event Colors

Color Picker

Valid hex code (#RRGGBB)

Yes

Imperial Distance

Radio Button

Miles or Kilometers

Yes

QR Code URL

Display Only

System-generated URL

N/A

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Post-Success Action**

**Duration**

Company Name Update

"Company name updated successfully"

Update all displays

3 seconds

Country Change

"Country settings updated successfully"

Refresh regional options

3 seconds

Currency Change

"Currency updated successfully. All amounts will display in \[currency\]"

Update financial displays

5 seconds

Measurement Change

"Measurement system updated to \[Imperial/Metric\]"

Apply to new projects

3 seconds

Travel Fee Update

"Travel fee minimum set to \[distance\]"

Update contractor policies

3 seconds

Primary Signatory Update

"Primary signatory updated successfully"

Apply to future documents

3 seconds

Event Color Change

"Event colors updated successfully"

Refresh calendar displays

3 seconds

Reset Colors

"Event colors reset to defaults"

Apply default palette

3 seconds

Save All Settings

"General settings saved successfully"

Apply all changes

3 seconds

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**User Action Required**

Company Name Too Long

"Company name cannot exceed 250 characters"

Shorten the name

Invalid Company Characters

"Company name contains invalid characters"

Remove special characters

Currency Change Blocked

"Only Agency Owners can change currency"

Contact Agency Owner

Primary Signatory Cleared

"Please select a primary signatory."

Select a signatory before saving

Signatory Edit Blocked (non-owner)

Tooltip: "Only the Agency Owner can change the primary signatory."

Contact the Agency Owner

Admin Signatory Unavailable (send-time)

"No admin is attached to this project. The Agency Owner will sign unless you select a different signatory."

Confirm or override the signatory before sending

Invalid Color Format

"Please enter a valid color code"

Use color picker or valid hex

Network Save Error

"Unable to save settings. Please try again"

Retry save operation

Permission Denied

"You don't have permission to modify this setting"

Request access from admin

Concurrent Edit Conflict

"Settings were modified by another user. Please refresh"

Refresh and retry

Invalid Travel Distance

"Please select a valid travel distance option"

Choose from dropdown

Session Timeout

"Your session has expired. Please log in again"

Re-authenticate

## **8\. Edge Cases**

**Scenario**

**System Behavior**

**Mitigation**

Multiple users editing simultaneously

Last save wins

Implement optimistic locking

Country with no states/provinces

State field hidden

Adjust form dynamically

Unsupported currency selected

Default to USD

Show supported currencies only

Project has no project manager or admin attached

Agency Owner automatically becomes the project owner (every project must have exactly one)

Enforce mandatory project owner; Project Owner and Agency Owner signatory options always resolve

Admin selected as signatory but no admin attached to project

Falls back to Agency Owner as signatory

Prompt sender to confirm or override before sending

Multiple admins attached to a project when "Admin" is the signatory

Ambiguous which admin signs

Define a tiebreaker rule (e.g., project-designated primary admin) — see open question

Resolved signatory (person) deactivated or removed before send

Person can no longer sign

Treat as unassigned — fall back to Agency Owner and allow override

Default signatory changed while a document is drafted but not yet sent

Send-time resolution uses the new default

Confirm intended behavior; optionally lock signatory at draft creation

Sender overrides signatory to Admin but no admin is attached

Selected override cannot resolve

Re-validate at send; fall back to Agency Owner and re-prompt

Color picker browser incompatibility

Fallback to text input

Provide hex code field

Travel distance in metric confusion

Show conversion tooltip

Display both units temporarily

Company name with Unicode characters

May display incorrectly

Validate and sanitize input

QR code generation failure

Display error message

Provide retry mechanism

Event type deleted after color set

Orphaned color setting

Clean up unused colors

Measurement change during active project

Confusion in calculations

Show warning before change

Currency symbol rendering issues

Display currency code

Use fallback text display

## **9\. Acceptance Criteria**

### Company Settings

*   Company name updates successfully with proper validation
*   Only authorized roles can modify restricted fields
*   Changes reflect immediately across the system

### Regional Configuration

*   Country selection properly updates dependent fields
*   Currency changes require appropriate permissions
*   Regional settings apply to new data entry

### Measurement System

*   Toggle between Imperial and Metric works correctly
*   Distance calculations use selected system
*   No retroactive changes to existing data

### Travel Policy

*   Minimum distance configuration saves properly
*   Travel fee calculations respect the threshold
*   Settings apply to future projects only

### Primary Signatory

*   Field defaults to Agency Owner and can never be saved empty
*   Only the Agency Owner can change the field; all other roles see it read-only with a tooltip on hover
*   The saved role is correctly resolved to the right person at send-time, for contracts, Service Agreements, and proposals only
*   Send-time override applies to a single document without altering the saved default
*   Changes apply to future documents only and are not retroactive
*   Every project always has exactly one project owner (the Agency Owner by default when no project manager or admin is attached), so Project Owner and Agency Owner always resolve
*   When Admin is selected but no admin is attached to the project, the system falls back to Agency Owner and prompts the sender before sending

### Event Colors

*   Color picker allows custom color selection
*   Changes apply immediately to calendar views
*   Reset functionality restores defaults

### Data Persistence

*   All settings save successfully
*   Changes persist across sessions
*   Audit trail captures all modifications

## **10\. Manual Test Cases**

[General\_Settings\_Comprehensive\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1foosgBYFcePE6v5z5ptO0OcPYYK8KmFz/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

External Service

Google Maps API

Calculate travel distances

Manual distance entry required

External Service

Currency Exchange API

Validate currency codes

Limited to hardcoded currencies

External Service

Country Database API

Provide country/state lists

Use static country list

Internal Module

Calendar Module

Display event colors

Colors won't apply to calendar

Internal Module

Financial Module

Apply currency settings

Currency display errors

Internal Module

Contractor Module

Enforce travel policies

Travel fees miscalculated

Internal Module

Reporting Module

Use measurement units

Incorrect distance reports

Internal Module

Document / E-Signature Module

Apply the resolved signatory to outgoing contracts, Service Agreements, and proposals

Signatory cannot be applied; documents cannot be sent for signature

Internal Module

Projects Module

Resolve Admin / Project Owner assignments per project at send-time

Role resolution fails; falls back to Agency Owner

Configuration

Localization Files

Regional format rules

Default to US formats

Library

Color Picker Library

Provide color selection UI

Fallback to text input

Library

QR Code Generator

Create QR codes

No QR code functionality

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=29490-142367&t=hlJPZKI33RrWvjz0-0)

3\. Business & Payment Details Module

# **FRD #3: Business & Payment Details Module**

**Module Name:** Business & Payment Details  
**Version:** 3.0  
**Date:** April 08, 2026

## **1\. Module Overview**

**Module Name:** Business & Payment Details

**Purpose:** The Business & Payment Details module enables agencies to configure payment processing by connecting each brand to a Stripe account. Brands can either create a new Stripe account or link to an existing Stripe account already connected to another brand. This flexible model allows agencies to receive client payments with automatic fee deduction based on their subscription plan.

**Business Goals:**

*   Enable agencies to receive client payments through Stripe Connect integration on a per-brand basis.
*   Provide flexibility for brands to share a single Stripe account or maintain independent accounts.
*   Facilitate secure Stripe onboarding with identity verification and bank account linking.
*   Support subscription-based platform fee structure for sustainable revenue model.
*   Ensure compliance with payment processor requirements through proper verification workflows.
*   Support scalable growth by allowing agencies to add new brands with quick account linking.

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Permissions**

Agency Owner

Full access

All fields

Can connect/disconnect Stripe, manage all brand connections

Admin

View only

None

Read-only access to all connection statuses

Project Manager

No access

None

Section not visible

Editor

No access

None

Section not visible

Supervising Editor

No access

None

Section not visible

Contractor

No access

None

Section not visible

**Access Rule:** The Business & Payment Details module is accessible to the Agency Owner with full control and to Admins in read-only mode. All other roles cannot view or access this section. If an unauthorized role attempts to navigate to this section, the system does not display the Business & Payment Details menu item in the left sidebar navigation.

## **3\. User Flow**

### Initial Access

3.1 The Agency Owner navigates to the Agency Global Settings from the left sidebar menu and clicks on "Business & Payment Details."

3.2 The system checks whether the agency has any brands configured.

3.3 If the agency has zero brands configured, the system displays an empty state with a message prompting the user to create a brand first before configuring payment settings.

3.4 If the agency has one or more brands, the system displays the Business and Payment Details page.

### Page Display

3.5 The system displays the page with the heading "Business and Payment Details" and the subtitle "Connect each brand to your Stripe account to receive payments from all your clients."

3.6 The system displays the "Connect with Stripe" card with the subtitle "One account per brand" and a connection counter badge showing "\[X\] of \[Y\] connected" (e.g., "2 of 3 connected").

3.7 The system displays four benefit checkmarks that are always visible:

*   Separate accounts per brand
*   Per-brand reporting
*   Independent payouts
*   Scale with new brands

3.8 Below the benefits, the system displays the "Your brands" section listing all agency brands as collapsible accordion rows with their connection status and appropriate action buttons.

### Brand Accordion Display

3.9 Each brand row is a collapsible accordion displaying:

*   Brand logo/avatar
*   Brand name
*   Connection status text
*   Status badge (when applicable)
*   Action button

3.10 When expanded, the accordion reveals:

*   Connected bank account details (e.g., "Bank Of America \*\*\*\* 4829")
*   "Disconnect" button (for connected brands)

### Brand Connection States

3.11 Each brand displays one of the following states:

**Not Connected State:**

*   Status text: "Not connected" (red)
*   Action button: "Connect" (yellow filled button)
*   Accordion is not expandable

**Connected State:**

*   Status text: "Connected" (green) with checkmark
*   Accordion expandable to show bank details and "Disconnect" button

**Under Review State:**

*   Status text: Shows bank account info (e.g., "Bank of America (\*\*\*\* 4829)")
*   Status badge: "Under Review" (yellow badge)
*   Action button: "Review" (outlined button)
*   Expandable section with message: "Your stripe account is under verification. It could take up to 24-48 hours"

**Restricted State:**

*   Status text: "Verification failed - \[X\] errors found" (red)
*   Status badge: "Restricted" (red badge with warning icon)
*   Action button: "Retry" (yellow filled button)
*   Expandable section with specific error messages from Stripe

### Connect Flow — Connection Type Selection

3.12 The Agency Owner clicks the "Connect" button next to a brand.

3.13 The system displays the "Connect Stripe account" modal with:

*   **Title:** "Connect Stripe account"
*   **Subtitle:** "How would you like to connect \[Brand Name\]?"
*   **Option 1:** "Create new account" — "Set up a new Stripe account" (radio button)
*   **Option 2:** "Use existing account" — "Link to another brand's account" (radio button)
*   **Button:** "Cancel"

3.14 If no other brands have Stripe connected yet, the "Use existing account" option is disabled or hidden.

### Connect Flow — Create New Account

3.15 The Agency Owner selects "Create new account" in the modal.

3.16 The system closes the modal and redirects the Agency Owner to the Stripe OAuth authorization page (external Stripe page).

3.17 The Agency Owner completes the Stripe Connect onboarding process, including:

*   Business information entry
*   Identity verification
*   Bank account linking

3.18 Upon successful authorization, Stripe redirects the Agency Owner back to the Pixally Business & Payment Details page.

3.19 The system stores the Stripe account connection data for that brand.

3.20 The system displays a success message: "Stripe account connected successfully for \[Brand Name\]."

3.21 The brand status updates based on Stripe's verification response:

*   If immediately verified: Status changes to "Connected"
*   If pending verification: Status changes to "Under Review"
*   If verification issues: Status changes to "Restricted"

3.22 The connection counter badge updates to reflect the new count.

### Connect Flow — Use Existing Account

3.23 The Agency Owner selects "Use existing account" in the modal.

3.24 The system displays the "Select account" modal with:

*   **Title:** "Select account"
*   **Subtitle:** "Choose which account to use for \[Brand Name\]"
*   List of brands that already have Stripe connected, showing brand name and "Stripe account" label
*   **Buttons:** "Cancel" | "Link account" (disabled until selection made)

3.25 The Agency Owner selects one of the existing connected brands.

3.26 The Agency Owner clicks the "Link account" button.

3.27 The system links the selected Stripe account to the current brand.

3.28 The brand immediately shows as "Connected" status (no verification required since the Stripe account is already verified).

3.29 The brand shares the same bank account and payout configuration as the selected source brand.

3.30 The system displays a success message: "Stripe account connected successfully for \[Brand Name\]."

3.31 The connection counter badge updates to reflect the new count.

### Review Flow (Under Review State)

3.32 When a brand is in "Under Review" status, the Agency Owner clicks the "Review" button.

3.33 The system opens a modal displaying the submitted business and bank account details.

3.34 The Agency Owner can view and edit the submitted information within the modal.

3.35 If the Agency Owner makes changes and saves, the system submits the updated information to Stripe.

3.36 The verification process restarts and may take an additional 24-48 hours.

3.37 If the Agency Owner clicks "Cancel" or closes the modal without saving, no changes are made.

3.38 The verification status automatically updates when Stripe completes verification (reflected on page refresh).

### Retry Flow (Restricted State)

3.39 When a brand is in "Restricted" status, the Agency Owner can expand the brand row to view specific error details.

3.40 The expanded section displays:

*   Error count: "Verification failed - \[X\] errors found"
*   Individual error messages in red boxes (pulled from Stripe API)
*   Footer message: "There was an issue completing your onboarding. Please review the highlighted details and try again."

3.41 The Agency Owner clicks the "Retry" button.

3.42 The system redirects the Agency Owner to the Stripe OAuth flow to restart the connection process.

3.43 The Agency Owner completes the Stripe onboarding again with corrected information.

3.44 Upon return, the brand status updates based on the new verification response.

### Disconnect Flow

3.45 The Agency Owner expands a connected brand's accordion row.

3.46 The Agency Owner clicks the "Disconnect" button within the expanded section.

3.47 The system checks whether any payments are currently in processing for that brand.

3.48 If NO payments are in processing, the system displays a confirmation dialog with the following content:

*   **Title:** "Disconnect Stripe Account"
*   **Message:** "Are you sure you want to disconnect Stripe for \[Brand Name\]? You will no longer be able to receive payments for this brand until you reconnect."
*   **Buttons:** "Cancel" (secondary) | "Disconnect" (primary/destructive)

3.49 If the Agency Owner clicks "Disconnect," the system disconnects the Stripe account for that brand only.

3.50 Other brands sharing the same Stripe account remain connected and unaffected.

3.51 The brand status changes to "Not connected" with the "Connect" button.

3.52 The system displays a success message: "Stripe account disconnected for \[Brand Name\]."

3.53 The connection counter badge updates to reflect the new count.

3.54 If the Agency Owner clicks "Cancel," the system closes the dialog and no changes are made.

3.55 If payments ARE in processing, the system displays an informational dialog with the following content:

*   **Title:** "Cannot Disconnect Stripe Account"
*   **Message:** "Unable to disconnect Stripe account. Payments are currently being processed for \[Brand Name\]. Please try again once all payments are complete."
*   **Buttons:** "Close" only

3.56 The Agency Owner clicks "Close" to dismiss the dialog; no changes are made and the account remains connected.

### Admin View Flow

3.57 When an Admin navigates to Business & Payment Details, the system displays the same page layout.

3.58 All action buttons (Connect, Disconnect, Review, Retry) are hidden or disabled for Admin users.

3.59 The Admin can view all brand connection statuses and expand accordions but cannot make any changes.

## **4\. Functional Logic**

### 4.1 Stripe Connect Architecture

• The Business & Payment Details module uses Stripe Connect to enable agencies to receive client payments on a per-brand basis.

• Each brand within an agency can either create a new Stripe account or link to an existing Stripe account from another brand.

• Multiple brands can share the same Stripe account, allowing flexible payment configuration.

• When brands share a Stripe account, they share the same bank account and payout configuration.

• Client payments are processed through Stripe and transferred to the agency's connected bank account.

• Platform fees are deducted based on the agency's subscription plan.

### 4.2 Brand Connection Options

**Create New Account:** • Initiates a new Stripe Connect OAuth flow. • User completes full Stripe onboarding including business info, identity verification, and bank account setup. • Results in a new, independent Stripe account for that brand. • Subject to Stripe's verification process (immediate, under review, or restricted).

**Use Existing Account:** • Links the brand to a Stripe account already connected to another brand. • No Stripe OAuth flow required. • Brand immediately becomes "Connected" since the Stripe account is already verified. • Brand shares the same bank account and payouts as the source brand. • Available only when at least one other brand has Stripe connected.

### 4.3 Shared Stripe Account Behavior

• When multiple brands share a Stripe account, they share:

*   The same Stripe account credentials
*   The same connected bank account
*   The same payout schedule and configuration

• Disconnecting one brand does NOT affect other brands sharing the same Stripe account.

• Each brand maintains independent transaction history and reporting within Pixally.

• Payouts from Stripe combine all transactions from brands sharing the account.

### 4.4 Connection Counter Logic

• The connection counter displays as "\[X\] of \[Y\] connected" format.

• X = Number of brands with "Connected" status only.

• Y = Total number of brands in the agency.

• Brands in "Under Review" or "Restricted" status are NOT counted as connected.

• Counter updates immediately when brands are connected or disconnected.

### 4.5 Connection Status Definitions

**Not Connected:** • No Stripe account has been linked to this brand. • The brand cannot receive any client payments. • Invoices and proposals can be created as templates but cannot be sent to clients. • Accordion is not expandable.

**Connected:** • Stripe account is fully verified and active. • The brand can receive all types of client payments (ACH, Credit Card). • Invoices and proposals can be created and sent. • Automatic payouts to the connected bank account are active. • Accordion expandable to show bank details and Disconnect button.

**Under Review:** • Stripe account connection is complete but verification is pending. • Verification typically takes 24-48 hours. • The brand CAN receive payments while under review. • The submitted bank account information is displayed (masked format). • The status automatically updates when Stripe completes verification (on page refresh).

**Restricted:** • Stripe verification has failed due to one or more errors. • The brand CANNOT receive payments until issues are resolved. • Specific error messages from Stripe API are displayed in an expandable section. • The user must retry the connection process with corrected information.

### 4.6 Platform Fee Structure

Platform fees are determined by the agency's subscription plan and are deducted from each transaction.

**Credit Card Fees by Plan:**

**Subscription Plan**

**Total CC Fee**

**Stripe Portion**

**Pixally Portion**

Free

3.3% + 30¢

2.9% + 30¢

0.4%

Basic

2.9% + 30¢

2.9% + 30¢

$0

Essentials

2.9% + 30¢

2.9% + 30¢

$0

Studio

2.9% + 30¢

2.9% + 30¢

$0

**ACH Fees by Plan:**

**Subscription Plan**

**Total ACH Fee to Agency**

**Stripe Portion**

**Pixally Platform Fee**

Free

1% (no cap)

$0 (waived)

1% of transaction

Basic

Stripe fee + 1%

0.8% with $5 cap

1% of transaction

Essentials

0.8% with $12 cap

0.8% with $5 cap

Up to $7

Studio

0.8% with $8 cap

0.8% with $5 cap

Up to $3

**Fee Calculation Logic:**

• **Free Plan:** Pixally absorbs/waives the Stripe ACH fee. Agency pays only 1% platform fee to Pixally (no cap).

• **Basic Plan:** Agency pays Stripe's standard ACH fee (0.8% with $5 cap) PLUS 1% platform fee to Pixally (no cap). Total = Stripe fee + 1%.

• **Essentials Plan:** Combined ACH fee cap is $12. Stripe takes up to $5, Pixally takes the remainder up to $7.

• **Studio Plan:** Combined ACH fee cap is $8. Stripe takes up to $5, Pixally takes the remainder up to $3.

• Platform fees are not displayed in this module but appear under Expenses and QuickBooks integration if connected.

### 4.7 Payment Processing Flow

**Step 1: Client Payment Initiation** • Client pays an invoice through the client portal or payment link. • The payment is associated with a specific brand based on the invoice.

**Step 2: Fee Calculation** • Stripe processing fees are applied based on the payment method. • Pixally platform fee is applied based on the agency's subscription plan.

**Step 3: Fund Transfer** • Payment is received in the brand's connected Stripe account. • Fees are automatically deducted. • Net amount is available for payout to the agency's bank account.

**Calculation:**

agency\_receives = payment\_amount - stripe\_fee - pixally\_platform\_fee

### 4.8 Blocked Actions for Unconnected Brands

• Brands without a connected Stripe account (status: "Not connected" or "Restricted") have restrictions on payment-related actions.

• **Invoices:** Can be created as templates but cannot be sent to clients. When attempting to send, the system displays: "Please connect your Stripe account for \[Brand Name\] before sending invoices."

• **Proposals:** Can be created as templates but cannot be sent to clients. When attempting to send, the system displays: "Please connect your Stripe account for \[Brand Name\] before sending proposals."

• **Payment Links:** Cannot be generated for brands without active Stripe connection.

• These restrictions do not apply to "Under Review" status, which allows payment processing.

### 4.9 Stripe Verification Error Handling

• When Stripe verification fails, the brand enters "Restricted" status.

• The system retrieves error details from the Stripe API and displays them in an expandable section.

• Common verification errors include:

*   Identity document not readable
*   Address mismatch between document and account
*   Expired government ID
*   Unsupported business type or country
*   Missing required information

• Each error is displayed in a red-highlighted box with clear instructions for resolution.

• The "Retry" button initiates a new Stripe OAuth flow to restart the onboarding process.

### 4.10 Review Modal Functionality

• The Review modal appears when the user clicks "Review" on an "Under Review" brand.

• The modal displays all submitted business and bank account details.

• Fields are editable, allowing the user to correct any information before verification completes.

• Saving changes submits the updated information to Stripe and restarts the verification process (24-48 hours).

• Closing without saving preserves the original submission.

### 4.11 Disconnect Process

• Disconnection is available for "Connected" brands via the expanded accordion section.

• Disconnecting a Stripe account for a brand does NOT affect other brands sharing the same Stripe account.

• Disconnecting does not delete the Stripe account itself, only removes the connection for that specific brand.

• After disconnection:

*   The brand cannot receive new payments
*   Pending/scheduled payments for that brand are blocked
*   Historical payment data remains in the system
*   The brand can be reconnected later

• Disconnection is blocked if any payments are currently in "processing" status for that brand.

### 4.12 Onboarding Integration

• The Business & Payment Details module is part of the agency onboarding process.

• New agencies see an onboarding wizard with 8 steps, including "Connect to Stripe."

• Clicking "Connect to Stripe" in the onboarding wizard navigates to the Business & Payment Details page.

• The "Connect to Stripe" step is optional and can be skipped during initial onboarding.

• The onboarding wizard remains visible until all steps are completed, including Stripe connection.

• Agencies can complete Stripe connection later from the Settings menu.

### 4.13 Real-Time Updates

• The connection counter updates immediately when brands are connected or disconnected.

• Verification status changes from Stripe (via webhooks) are reflected on page refresh.

• Brand statuses update automatically without requiring a full page reload for user-initiated actions.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Description**

**Display Location**

Page Title

Display Text

"Business and Payment Details"

Page header

Page Subtitle

Display Text

"Connect each brand to your Stripe account to receive payments from all your clients"

Below page title

Card Title

Display Text

"Connect with Stripe"

Card header

Card Subtitle

Display Text

"One account per brand"

Below card title

Connection Counter

Badge

"\[X\] of \[Y\] connected" format; counts only "Connected" status

Top-right of card

Benefit 1

Checkbox Text

"Separate accounts per brand"

Benefits section

Benefit 2

Checkbox Text

"Per-brand reporting"

Benefits section

Benefit 3

Checkbox Text

"Independent payouts"

Benefits section

Benefit 4

Checkbox Text

"Scale with new brands"

Benefits section

Brand Logo

Image/Avatar

Brand logo or initials

Brand accordion row

Brand Name

Display Text

Name of the brand

Brand accordion row

Connection Status

Status Text

"Not connected" / "Connected" / Bank info

Brand accordion row

Status Badge

Badge

"Under Review" (yellow) / "Restricted" (red)

Brand accordion row (when applicable)

Action Button

Button

"Connect" / "Review" / "Retry"

Brand accordion row

Bank Account (Expanded)

Display Text

Masked format: "Bank Of America \*\*\*\* 4829"

Expanded accordion section

Disconnect Button

Button

"Disconnect" (red outlined)

Expanded accordion section

Error Count

Display Text

"Verification failed - \[X\] errors found"

Expanded restricted section

Error Message

Alert Box

Specific error from Stripe API

Expanded restricted section

Error Footer

Display Text

"There was an issue completing your onboarding..."

Expanded restricted section

Under Review Message

Info Text

"Your stripe account is under verification. It could take up to 24-48 hours"

Expanded under review section

### Modal Fields

**Field Name**

**Field Type**

**Description**

**Modal**

Modal Title

Display Text

"Connect Stripe account"

Connect Stripe account modal

Modal Subtitle

Display Text

"How would you like to connect \[Brand Name\]?"

Connect Stripe account modal

Create New Account

Radio Option

"Set up a new Stripe account"

Connect Stripe account modal

Use Existing Account

Radio Option

"Link to another brand's account"

Connect Stripe account modal

Cancel Button

Button

Closes modal

Connect Stripe account modal

Select Account Title

Display Text

"Select account"

Select account modal

Select Account Subtitle

Display Text

"Choose which account to use for \[Brand Name\]"

Select account modal

Brand List Item

Radio Option

Brand name + "Stripe account"

Select account modal

Cancel Button

Button

Closes modal

Select account modal

Link Account Button

Button

Links selected account to brand

Select account modal

## **6\. Success Message Handling**

**Action**

**Success Message**

**Trigger Condition**

**Post-Success Behaviour**

Stripe Connected (New)

"Stripe account connected successfully for \[Brand Name\]."

Stripe OAuth completes and returns account data

Brand status updates; counter updates

Stripe Connected (Existing)

"Stripe account connected successfully for \[Brand Name\]."

User links existing account via Select account modal

Brand shows "Connected"; counter updates

Stripe Disconnected

"Stripe account disconnected for \[Brand Name\]."

User confirms disconnection; no payments processing

Brand status changes to "Not connected"; counter updates

Review Info Updated

"Information updated successfully. Verification will restart."

User saves changes in Review modal

Modal closes; verification restarts (24-48 hrs)

Verification Complete

"Stripe verification completed for \[Brand Name\]."

Stripe webhook indicates successful verification

Status changes to "Connected"

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger Condition**

**Required Action / System Response**

No brands configured

"Please create at least one brand before configuring payment settings."

User navigates to page with zero brands

Display empty state; link to Brand creation

Stripe OAuth cancelled

"Stripe connection was cancelled. Please try again to connect your account."

User closes or cancels Stripe OAuth flow

User returns to page; brand remains "Not connected"

Stripe OAuth failed

"Unable to connect to Stripe. Please check your internet connection and try again."

Network error during OAuth

User returns to page; can retry

Disconnect blocked - processing

"Unable to disconnect Stripe account. Payments are currently being processed for \[Brand Name\]. Please try again once all payments are complete."

User tries to disconnect while payments processing

Display dialog with "Close" button only

Verification rejected

"Verification failed - \[X\] errors found" + specific Stripe errors

Stripe returns verification errors

Display errors in expandable section; show "Retry" button

Send invoice blocked

"Please connect your Stripe account for \[Brand Name\] before sending invoices."

User tries to send invoice for brand without Stripe

Block send action; prompt to connect

Send proposal blocked

"Please connect your Stripe account for \[Brand Name\] before sending proposals."

User tries to send proposal for brand without Stripe

Block send action; prompt to connect

Permission denied

"You don't have permission to modify payment settings."

Non-owner user attempts to connect/disconnect

Display error; no action taken

Network error

"Unable to load payment configuration. Please refresh the page or try again later."

Network failure when loading page data

Display error with retry option

No existing accounts available

(Option disabled)

User clicks Connect but no other brands have Stripe

"Use existing account" option is disabled

## **8\. Edge Cases**

**Scenario**

**System Behaviour**

**Mitigation**

No brands configured

Display empty state with message to create brand first

Link to Brand Management

All brands connected

Counter shows "X of X connected"; all brands show expanded accordions with Disconnect

Normal operation

All brands not connected

Counter shows "0 of X connected"; all brands show "Connect" button

Onboarding wizard prompts connection

New brand added

Automatically appears in list as "Not connected"

No user action required

Brand deleted

Removed from list; Stripe connection preserved in Stripe

Historical payment data retained

First brand connecting

"Use existing account" option is disabled/hidden

Only "Create new account" available

Multiple brands share same Stripe

All share same bank and payouts

Disconnect affects only selected brand

Disconnect shared account brand

Only that brand disconnects; others remain connected

Clear confirmation message

All brands using shared account disconnect

Stripe account remains active in Stripe dashboard

User can reconnect any brand

Stripe service outage

OAuth flow fails; display error message

Queue for retry; show maintenance message

Webhook delivery failure

Status not updated automatically

Manual refresh required; implement webhook retry

Concurrent edit attempts

Data conflict possible

Session locking; last save wins

Browser blocks OAuth redirect

OAuth flow interrupted

Provide manual connection instructions

Verification takes longer than 48 hours

User may be concerned

Display "taking longer than expected" message

User retries during Under Review

May cause duplicate submissions

Disable Retry during Under Review; only show Review

Admin attempts to connect

Action buttons hidden/disabled

View-only access enforced

Disconnect then reconnect same account

Can link via "Use existing account" if another brand still uses it

Or create new connection via OAuth

Payment initiated during disconnect attempt

Disconnect blocked

Show "Cannot Disconnect" dialog

Multiple errors from Stripe

All errors displayed in expandable section

Each error in separate red box

Restricted brand added to invoice

Cannot send invoice

Block at send time with clear message

Under Review brand receives payment

Payment processed normally

Under Review allows payments

Link to existing account that becomes restricted

Linked brand also becomes restricted

Status syncs from source Stripe account

## **9\. Acceptance Criteria**

### Access Control

• Agency Owners can view and modify all brand Stripe connections.

• Admins can view all connection statuses and expand accordions but cannot connect, disconnect, review, or retry.

• Other roles (Project Manager, Editor, Supervising Editor, Contractor) cannot access this section.

### Page Display

• Page heading displays "Business and Payment Details" with correct subtitle.

• "Connect with Stripe" card displays with "One account per brand" subtitle.

• Connection counter shows accurate count of connected brands (not including Under Review).

• All four benefits display with checkmarks.

• All agency brands are listed as collapsible accordion rows.

### Connect Flow — Create New Account

• Clicking "Connect" opens "Connect Stripe account" modal with two options.

• Selecting "Create new account" redirects to Stripe OAuth flow.

• After successful OAuth, user returns to Pixally with success message.

• Brand status updates appropriately (Connected, Under Review, or Restricted).

• Connection counter updates immediately.

### Connect Flow — Use Existing Account

• "Use existing account" option is disabled when no other brands have Stripe connected.

• Selecting "Use existing account" opens "Select account" modal.

• Modal lists all brands with connected Stripe accounts.

• Selecting a brand and clicking "Link account" connects the current brand immediately.

• Brand shows "Connected" status without verification (already verified).

• Brand shares same bank account and payouts as source brand.

### Status States

• "Not connected" brands show red status text and yellow "Connect" button.

• "Connected" brands show green "Connected" text with checkmark; accordion expandable.

• Expanded accordion shows bank account details and "Disconnect" button.

• "Under Review" brands show bank info, yellow badge, "Review" button, and expandable info message.

• "Restricted" brands show red error text, red badge with warning icon, "Retry" button, and expandable error details.

### Shared Account Behavior

• Multiple brands can successfully link to the same Stripe account.

• Disconnecting one brand does not affect other brands sharing the account.

• All brands sharing an account display the same bank information.

### Review Flow

• Clicking "Review" opens modal with editable business/bank details.

• Saving changes restarts verification process.

• Closing without saving preserves original submission.

### Retry Flow

• Clicking "Retry" redirects to Stripe OAuth to restart onboarding.

• After successful retry, brand status updates appropriately.

### Disconnect Flow

• Disconnect button is inside expanded accordion section.

• Clicking "Disconnect" shows confirmation dialog with brand name.

• Confirming disconnection changes status to "Not connected" and updates counter.

• Other brands sharing the same Stripe account remain unaffected.

• Cancelling closes dialog with no changes.

• If payments processing, "Cannot Disconnect" dialog appears with only "Close" button.

### Blocked Actions

• Brands without active Stripe (Not connected or Restricted) cannot send invoices or proposals.

• Templates can be created but send action is blocked with appropriate message.

• "Under Review" brands CAN send invoices and proposals.

### Platform Fees

• Fees are calculated based on agency's subscription plan.

• Credit card and ACH fees follow the defined structure per plan.

• Fees are not displayed in this module but appear in Expenses/QuickBooks.

### Onboarding Integration

• "Connect to Stripe" step in onboarding wizard navigates to this page.

• Step is optional and can be skipped.

• Onboarding wizard persists until all steps completed.

## **10\. Manual Test Cases**

The comprehensive test cases for the Business & Payment Details module are provided in a separate Excel file for upload to the project management system.

**File:** \[Business\_Payment\_Details\_Test\_Cases.xlsx\]

## **11\. Dependencies**

**Module / System**

**Dependency Type**

**Description**

**Impact if Unavailable**

Stripe Connect API

External Service

OAuth authorization, account management, verification

Cannot connect Stripe accounts; no payment processing

Stripe OAuth

External Service

Account connection authorization flow

Cannot initiate new connections

Stripe Webhooks

External Service

Verification status updates

Manual status checks required; delayed updates

Brand Management

Internal Module

Provides list of agency brands

Cannot display brands; no connections possible

Invoice Module

Internal Module

Creates payable invoices

Invoice creation works but send blocked without Stripe

Proposal Module

Internal Module

Creates payable proposals

Proposal creation works but send blocked without Stripe

Subscription Module

Internal Module

Determines platform fee rates

Default fee structure applied

Onboarding Wizard

Internal Module

Initial agency setup flow

Connection step unavailable in onboarding

Authentication Service

Internal Service

Validates user roles and permissions

Unauthorized access possible

QuickBooks Integration

External Service

Expense tracking for platform fees

Fee tracking unavailable

Expenses Module

Internal Module

Displays platform fee deductions

Fee visibility unavailable

## **12\. References**

*   **Figma Designs:** \[Figma Link\]
*   **Related FRDs:**
    *   \[My\_Profile\_FRD.md\] — Agency Global Settings
    *   \[General\_Settings\_FRD.md\] — Agency Global Settings
    *   \[Accepted\_Payment\_Methods\_FRD.md\] — Agency Global Settings
    *   \[Two\_Step\_Verification\_FRD.md\] — Agency Global Settings
    *   \[Data\_Management\_FRD.md\] — Agency Global Settings
    *   \[Stripe\_Integration\_FRD.md\] — Agency Global Settings (Contractor Payments)
    *   \[Subscription\_Module\_FRD.md\] — Subscription Management
    *   \[Invoice\_Module\_FRD.md\] — Finance Module
    *   \[Proposal\_Module\_FRD.md\] — Projects Module

4\. Accepted Payment Methods Module

# **FRD #4: Accepted Payment Methods Module**

## **1\. Module Overview**

**Module Name:** Accepted Payment Methods

**Purpose:** The Accepted Payment Methods module enables agencies to configure which payment options are available to clients on invoices and proposals, including processing fee management and payment method availability controls.

**Business Goals:**

*   Provide flexibility in payment acceptance based on business needs
*   Display transparent processing fees to understand cost structure
*   Ensure at least one payment method is always available for client transactions
*   Integrate seamlessly with Stripe payment processing capabilities

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Permissions**

Agency Owner

Full access

All settings

Can enable/disable payment methods

Admin

View only

None

Can view settings and fees

Project Manager

View only

None

Can view enabled methods

Editor

No access

None

Section not visible

Supervising Editor

No access

None

Section not visible

Contractor

No access

None

Section not visible

## **3\. User Flow**

3.1 The Agency Owner navigates to Settings and clicks on Accepted Payment Methods.

3.2 The system displays the current payment method configuration and processing fees.

3.3 The user views the Card Payments section showing credit card acceptance options.

3.4 The user reads the description explaining that card payments work with major credit cards.

3.5 The system displays the current processing fee percentage based on the subscription plan.

3.6 The user toggles the Card Payments switch to enable or disable this method.

3.7 The system immediately updates the toggle state and shows visual feedback.

3.8 The user views the ACH Bank Transfers section below Card Payments.

3.9 The user reads the description about direct bank account payments.

3.10 The system displays the lower processing fee for ACH transfers.

3.11 The user toggles the ACH Bank Transfers switch as needed.

3.12 The system validates that at least one payment method remains enabled.

3.13 The user reviews the processing fee information for both methods.

3.14 The system shows how fees are calculated based on the current subscription tier.

3.15 The user attempts to disable all payment methods to test validation.

3.16 The system prevents disabling the last active payment method.

3.17 The user receives an error message about minimum requirements.

3.18 The system maintains at least one payment method as active.

3.19 The user makes final adjustments to payment method selections.

3.20 The user clicks Save to apply the payment method configuration.

3.21 The system saves the settings and confirms the changes.

3.22 The user navigates away knowing the settings are applied.

3.23 The system applies these payment options to all future invoices.

3.24 The user can return to modify settings as business needs change.

3.25 The system maintains the configuration across all brands under the agency.

## **4\. Functional Logic**

### Payment Method Configuration

*   The Accepted Payment Methods section controls which payment options appear on client-facing invoices and proposals.
*   Two primary payment methods are supported in Phase 1: Card Payments and ACH Bank Transfers.
*   Each payment method can be independently enabled or disabled based on business preferences and client needs.
*   The system enforces that at least one payment method must remain active to ensure clients can always make payments.
*   Changes to payment methods apply immediately to all new invoices and proposals but do not affect existing unpaid documents.
*   The configuration applies at the agency level and affects all brands under the agency umbrella.

### Card Payments Processing

*   Card Payments, when enabled, accepts all major credit cards including Visa, Mastercard, American Express, and Discover.
*   The processing fee for card payments displays dynamically based on the agency's current subscription plan.
*   Standard card processing fees typically show as a percentage (e.g., 2.9%) plus a fixed amount (e.g., $0.30) per transaction.
*   The system clearly displays these fees to help agencies understand their cost structure for accepting card payments.
*   Card payment processing occurs through the connected Stripe account with automatic fund transfers.
*   Enabling card payments requires an active and verified Stripe account connection.

### ACH Bank Transfer Processing

*   ACH Bank Transfers enable clients to pay directly from their bank accounts with lower processing fees.
*   The ACH processing fee is typically lower than card payments, often showing as a smaller percentage or flat fee.
*   ACH payments may take longer to process (3-5 business days) compared to instant card payments.
*   The system displays clear information about ACH processing times to set proper expectations.
*   ACH transfers require additional client verification for security and fraud prevention.
*   This payment method is ideal for larger invoices where lower fees provide significant savings.

### Processing Fee Management

*   Processing fees are determined by the agency's subscription plan and cannot be manually modified.
*   The system automatically updates fee displays when subscription plans change.
*   Fees are shown as informational only and do not affect the invoice amounts sent to clients.
*   Agencies absorb processing fees unless explicitly added to invoices as separate line items.
*   The fee structure helps agencies calculate true revenue after payment processing costs.
*   Different subscription tiers may offer reduced processing fees as a benefit.

### Payment Method Validation

*   The system prevents users from disabling all payment methods simultaneously.
*   When attempting to disable the last active method, an error message appears explaining the requirement.
*   The validation occurs both client-side for immediate feedback and server-side for security.
*   If Stripe is disconnected, all payment methods become unavailable regardless of toggle states.
*   The system checks Stripe account capabilities to ensure selected methods are actually available.

### Subscription Plan Integration

*   The displayed processing fees automatically adjust based on the current subscription plan.
*   Higher-tier subscriptions typically offer lower processing fees as an added benefit.
*   The system retrieves current fee rates from the subscription configuration.
*   Changes to subscription plans immediately reflect in the fee display.
*   Downgrading subscriptions may result in higher processing fees going forward.

### Invoice and Proposal Integration

*   Enabled payment methods automatically appear as options on all new invoices and proposals.
*   Clients see only the enabled methods when viewing payment options.
*   The system generates appropriate payment buttons and forms based on the configuration.
*   Disabled methods are completely hidden from client-facing documents.
*   Changes do not retroactively affect invoices already sent to clients.

### Multi-Brand Considerations

*   Payment method settings apply globally to all brands under the agency.
*   Individual brands cannot have different payment method configurations.
*   All brands must share the same Stripe account for payment processing.
*   This ensures consistent payment experience across all agency brands.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

Card Payments Toggle

Switch

Boolean on/off

No

Card Processing Fee

Display

Read-only, percentage + fixed

N/A

ACH Transfers Toggle

Switch

Boolean on/off

No

ACH Processing Fee

Display

Read-only, percentage or flat

N/A

Minimum Active Methods

System Rule

At least 1 method must be enabled

Yes

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Post-Success Action**

**Duration**

Enable Card Payments

"Card payments enabled successfully"

Update invoice options

3 seconds

Disable Card Payments

"Card payments disabled successfully"

Remove from invoices

3 seconds

Enable ACH Transfers

"ACH bank transfers enabled successfully"

Update invoice options

3 seconds

Disable ACH Transfers

"ACH bank transfers disabled successfully"

Remove from invoices

3 seconds

Save Configuration

"Payment methods updated successfully"

Apply to new invoices

3 seconds

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**User Action Required**

Disable All Methods

"At least one payment method must be enabled"

Keep one method active

No Stripe Connected

"Please connect Stripe account before configuring payment methods"

Connect Stripe first

Stripe Not Verified

"Stripe verification pending. Payment methods unavailable"

Wait for verification

Permission Denied

"Only Agency Owners can modify payment methods"

Contact Agency Owner

Save Failed

"Unable to save payment configuration. Please try again"

Retry save operation

Network Error

"Connection error. Please check your internet and try again"

Check connection

Invalid Configuration

"Invalid payment configuration detected"

Refresh and reconfigure

## **8\. Edge Cases**

**Scenario**

**System Behavior**

**Mitigation**

Stripe capabilities mismatch

Selected method not available in Stripe

Sync with Stripe capabilities

Subscription plan expired

Fee rates unavailable

Default to standard rates

Multiple users editing

Configuration conflicts

Last save wins

Browser compatibility issues

Toggle switches may not work

Provide fallback checkboxes

Payment method deprecated

Old method still showing

Hide deprecated options

Fee calculation errors

Incorrect fees displayed

Validate against source

Rapid toggle switching

State synchronization issues

Debounce toggle actions

## **9\. Acceptance Criteria**

### Payment Method Controls

*   Toggles enable/disable payment methods correctly
*   At least one method always remains active
*   Changes save and persist properly
*   Configuration applies to new invoices immediately

### Processing Fee Display

*   Fees display accurately based on subscription
*   Fee updates reflect plan changes
*   Information is clearly presented
*   Both percentage and fixed fees shown correctly

### Access Control

*   Only Agency Owners can modify settings
*   Other roles have appropriate view access
*   Permission errors display correctly
*   Unauthorized users cannot bypass restrictions

### Integration

*   Settings work with connected Stripe account
*   Payment options appear correctly on invoices
*   Configuration syncs across all brands
*   Changes don't affect existing invoices

## **10\. Manual Test Cases**

[Payment\_Methods\_Comprehensive\_Test\_Cases.xlsx](https://docs.google.com/spreadsheets/d/1NVT9islh9xxrR9rk59n3FlMCpcIYDmlj/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

External Service

Stripe API

Payment processing

No payments possible

Internal Module

Business & Payment Details

Stripe account connection

Cannot configure methods

Internal Module

Invoice Module

Display payment options

Methods won't appear on invoices

Internal Module

Proposal Module

Display payment options

Methods won't appear on proposals

Internal Module

Subscription Module

Determine processing fees

Default fees applied

Configuration

Payment Method List

Available payment types

Limited to hardcoded options

## **12\. References**

### 12.1 Figma Designs: [Figma](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=33604-20860&t=hlJPZKI33RrWvjz0-0)

5\. 2-Step Verification Module

# **2-Step Verification (Global Settings)**

## **1\. Module Overview**

*   **Module Name:** 2-Step Verification (Settings)  
    
*   **Purpose:** Provide users an in-app Settings page to view their 2FA status, verify contact methods (email & phone), and enable, disable, or combine Email and SMS as 2FA methods.  
    
*   **Business Goal:** Give users ongoing control over their 2FA configuration with clear status visibility, easy management, and a consistent password-confirmation security gate for all changes.  
    
*   **Scope:** This FRD covers:  
    *   Settings page UI ("Verification Required" + "Enable 2FA" sections)
    *   Verifying email and phone number from Settings
    *   Changing the verified phone number
    *   Enabling and disabling each 2FA method (Email and SMS) **independently**
    *   Per-action password confirmation as the security gate for all state changes
    *   Auto-activation of SMS 2FA when the verified phone number is changed (if previously active)
    *   Lost access / recovery path (high-level)
*   Note: First-login 2FA setup, login OTP verification (including dual-channel delivery when both methods are active), and login-time contact verification are covered in the **Agency Auth – Two-Factor Authentication (2FA) Setup** FRD.

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Notes**

User

Own 2FA settings

Own 2FA settings

Password confirmation required for each change

Google User

Own 2FA settings

Own 2FA settings (SMS only)

Email 2FA not available; no prompt required for actions (relies on Google OAuth session)

Agency Admin

Own 2FA settings

Own 2FA settings

Same as User; personal phone changes do not affect agency master data

All Other Roles

Own settings only

Own settings only

Standard 2FA flows apply

## **3\. User Flow**

### 3.1. Page Entry

*   User navigates to **Settings → 2-Step Verification**
*   The page loads immediately using the user's existing login session; no additional authentication is required to view the page
*   All state-changing actions trigger a password confirmation modal (regular users) or execute directly (Google users)

### 3.2. Viewing the Settings Page

The page shows two sections:

**Section A — Verification Required**

*   Caption: "Both email and phone number must be verified to secure the account."
*   **Email Address Verification:** shows the registered email + status badge (**Verified** / **Not Verified**) + "Verify Email" button (if not verified)
*   **Phone Number Verification:** shows masked phone (e.g., (\*\*\*) \*\*\*\*-6888) + status badge + "Change Phone Number" (if verified) or "Verify Phone Number" (if not verified)

**Section B — Enable 2FA**

*   **2FA with Email Address:** row with description + "Enable" or "Disable" button + "Activated" badge when active
*   **2FA with Phone Number:** row with description + "Enable" or "Disable" button + "Activated" badge when active
*   Each row's state is independent of the other

### 3.3. Verifying Email (Regular User)

*   User clicks "Verify Email"
*   Password confirmation modal appears
*   User enters password and clicks Confirm
*   On successful password validation, the email is marked as verified
*   Status badge updates to "Verified"; the "Enable" button on the 2FA with Email row becomes active
*   **Google users:** email is already verified via OAuth; "Verify Email" button is not shown

### 3.4. Verifying / Changing Phone Number (Regular User)

*   User clicks "Verify Phone Number" or "Change Phone Number"
*   Modal prompts for country code + phone number (pre-filled with current value when changing)
*   User enters the new number and clicks Save
*   Password confirmation modal appears
*   User enters password and clicks Confirm
*   On successful password validation, the phone number is saved to the user master as personal mobile and marked as verified
*   Status badge updates to "Verified"
*   **Auto-activation rule:** If SMS 2FA was previously active on the old number, it **automatically remains active** on the new number — no separate "Enable" step is required
*   **Google users:** password prompt is skipped; phone number is updated directly on Save

### 3.5. Enabling 2FA — Email (Regular User)

**Pre-condition:** Email must be verified. If not, the "Enable" button is disabled and prompts verification first.

*   User clicks "Enable" on the **2FA with Email Address** row
*   Password confirmation modal appears
*   User enters password and clicks Confirm
*   On successful password validation, Email 2FA is activated
*   Badge changes to "Activated"; button changes to "Disable"
*   SMS 2FA state is **not** affected
*   Success toast: "Email verification enabled successfully"
*   **Google users:** Email 2FA is not available (row hidden or disabled)

### 3.6. Enabling 2FA — SMS (Regular User)

**Pre-condition:** Phone must be verified. If not, the "Enable" button is disabled and prompts verification first.

*   User clicks "Enable" on the **2FA with Phone Number** row
*   Password confirmation modal appears
*   User enters password and clicks Confirm
*   On successful password validation, SMS 2FA is activated
*   Badge changes to "Activated"; button changes to "Disable"
*   Email 2FA state is **not** affected
*   Success toast: "SMS verification enabled successfully"
*   **Google users:** password prompt is skipped; SMS 2FA activates directly on click

### 3.7. Disabling a Method (Regular User)

*   User clicks "Disable" on a currently active method
*   Password confirmation modal appears
*   User enters password and clicks Confirm
*   On successful password validation, the method is deactivated
*   The other method's state is unchanged
*   **If the disabled method was the only active 2FA method**, 2FA is now off entirely:
    *   Toast: "Two-factor authentication disabled."
    *   Persistent warning banner: "Your account is less secure without 2FA. We recommend re-enabling."
*   **If the other method remains active**, 2FA is still on overall:
    *   Toast: "Email/SMS verification disabled. \[Other method\] is still active."
    *   No warning banner
*   **Google users:** password prompt is skipped; method deactivates directly on click

### 3.8. Both Methods Active

*   A user can have both Email and SMS 2FA active simultaneously
*   At each login, the system sends the **same OTP to both channels** (covered in the Agency Auth FRD, Section 3.4)
*   Either code (from email or SMS) is accepted; entering one completes verification

### 3.9. Google User Behavior (Summary)

*   **Email Address Verification row:** shows "Verified" automatically; no action button visible
*   **2FA with Email Address row:** "Enable" button is **hidden or disabled with a tooltip**: "Email 2FA is not available for Google-authenticated accounts."
*   **2FA with Phone Number row:** fully functional
*   **All Settings actions for Google users execute without a password prompt** — the existing Google OAuth session is the authorization
*   If the Google OAuth session has expired, the user is returned to the Google sign-in flow by the core authentication layer (not handled within this module)

### 3.10. Lost Access Recovery

*   **If only SMS is active and the phone is unreachable:** the user should use the login-time verification flow (see Agency Auth FRD) to update the phone number, or contact Pixally support
*   **If both methods are active:** the inaccessible channel is automatically mitigated — the user can complete login via the other channel, then disable or change the affected method from Settings
*   **If all channels are unreachable:** user must contact Pixally support. Support verifies identity through alternate means and disables 2FA from backend administrative tools
*   All recovery actions are logged in the audit trail

## **4\. Functional Logic**

### 4.1 Per-Action Password Confirmation (Security Gate)

*   Every state-changing action in Settings requires a password confirmation modal for regular users:
    *   Verify Email
    *   Verify Phone Number (first-time)
    *   Change Phone Number
    *   Enable Email 2FA
    *   Enable SMS 2FA
    *   Disable Email 2FA
    *   Disable SMS 2FA
*   The password modal is the **only** security gate for these actions — no OTP is sent or required
*   **Google users** bypass the password prompt entirely; actions execute based on the active OAuth session
*   Password validation is server-side against the user's current password hash

### 4.2 Password Attempt Limits

*   Users have a maximum of **5 password entry attempts** per session within Settings
*   After 5 wrong attempts: 2FA actions are restricted for **1 hour**
*   Automatic unlock after exactly 1 hour from the lockout time
*   The lockout is specific to 2FA-related actions and does not terminate the application session for unrelated functionality

### 4.3 Independent Method Activation (Both Methods Allowed)

*   Email 2FA and SMS 2FA are activated and disabled **independently**
*   A user may have: only Email active, only SMS active, both active, or neither active
*   Enabling one method has no effect on the state of the other; disabling one does not affect the other
*   Login behavior when both are active is governed by the Agency Auth FRD: same OTP, dual delivery

### 4.4 Verification Required Before 2FA Activation

*   A method (email or phone) must be verified before 2FA can be enabled on it
*   Until verified, the corresponding "Enable" button is disabled/grayed out, with a prompt to verify first
*   Verification of email or phone from Settings uses the **password** as the security gate (not OTP)

### 4.5 Phone Number Management & Auto-Activation on Change

*   User enters phone number during verification/change; saved to user master as personal mobile
*   Independent of agency-registered phone number
*   The same phone can be used across multiple user accounts; rate limit applies per phone number globally
*   **Auto-activation:** if SMS 2FA was active on the old number, it remains active on the new number immediately after the phone change is confirmed — the user does not need to click "Enable" again
*   If SMS 2FA was not active at the time of the change, its status remains off; the user must separately click "Enable" if they want to activate it

### 4.6 Status Display Logic

*   **"Verified"** badge: shown when the contact method is flagged as verified in user master
*   **"Not Verified"** badge: shown when no verification flag exists
*   **"Activated"** badge: shown on each 2FA row that is currently active (both rows can show "Activated" simultaneously)
*   UI updates synchronously on API success

### 4.7 Audit Logging

*   All state changes recorded with: user ID, timestamp, IP, action type (verify / change-phone / enable / disable / support-disable), target method, and source (settings / support)
*   Includes password-challenge results (success/failure) for security monitoring

### 4.8 Post-Disable Behavior

*   User retains full access immediately
*   If at least one 2FA method remains active, no warning banner is shown
*   If 2FA is now fully off:
    *   Persistent warning banner shown in Settings until at least one method is re-enabled
    *   No automatic re-prompt is shown at login (the first-login pop-up does **not** reappear — this is one-time-only per the Agency Auth FRD)

### 4.9 Lost Access / Fallback Logic

*   **Single-method active + that channel unreachable:**
    *   SMS-only and phone unreachable → user can update phone via login-time verification (Agency Auth FRD) or contact support
    *   Email-only and email unreachable → contact support
*   **Both methods active:** the inaccessible channel is automatically bypassed — the working channel handles login
*   **All available channels inaccessible:** support intervention only
*   Support-initiated disable notifies the user via available contact channels and is recorded in the audit log

### 4.10 Impact

*   Changes in Settings take effect immediately for subsequent logins
*   Disabling all 2FA removes the login OTP step on the next session
*   Adding a second method does not increase login friction (single OTP, dual delivery — see Agency Auth FRD)
*   Changing a verified phone while SMS 2FA is active preserves the 2FA-active state without requiring re-activation
*   With password-only confirmation (and no OTP), anyone with the user's password can modify 2FA settings; the password itself is the sole gate for Settings actions

## **5\. Field Details & Validations**

### Page Entry

No input fields required. The page loads directly from the user's existing authenticated session.

### Verification Required – Email

**Field Name**

**Type**

**Required**

**Validation Rules**

Email Address

Display

N/A

Read-only display of registered email

Status Badge

Display

N/A

"Verified" / "Not Verified"

Verify Email

Button

Conditional

Visible only if Not Verified; hidden for Google users

### Verification Required – Phone

**Field Name**

**Type**

**Required**

**Validation Rules**

Phone Number

Display

N/A

Masked format (e.g., (\*\*\*) \*\*\*\*-6888)

Status Badge

Display

N/A

"Verified" / "Not Verified"

Verify / Change Phone Number

Button

Yes

"Verify" if not verified; "Change" if verified

### Verify / Change Phone Modal

**Field Name**

**Type**

**Required**

**Validation Rules**

Country Code

Dropdown

Yes

Valid E.164 country code

Phone Number

Text

Yes

Numeric only, max 15 digits, format-valid, not on blocked list

Save

Button

Yes

Triggers password confirmation (regular users); updates user master on success

Cancel

Button

Optional

Discards changes

### Enable 2FA Section – Email Row

**Field Name**

**Type**

**Required**

**Validation Rules**

Method Label

Display

N/A

"2FA with Email Address" + description

Activated Badge

Display

Conditional

Shown only when Email 2FA is active

Enable / Disable

Button

Yes

"Enable" disabled if email not verified; **hidden/disabled for Google users** (tooltip explains)

### Enable 2FA Section – SMS Row

**Field Name**

**Type**

**Required**

**Validation Rules**

Method Label

Display

N/A

"2FA with Phone Number" + description

Activated Badge

Display

Conditional

Shown only when SMS 2FA is active

Enable / Disable

Button

Yes

"Enable" disabled if phone not verified

### Password Confirmation Modal (All Settings Actions — Regular Users Only)

**Field Name**

**Type**

**Required**

**Validation Rules**

Info Text

Display

Yes

"Please enter your password to confirm this change."

Password

Password

Yes

Must match current password; 6–20 chars; no spaces

Eye Icon Toggle

Toggle

Optional

Show/hide password; default hidden

Confirm

Button

Yes

Validates password; on success, performs the action

Cancel

Button

Optional

Closes modal without performing the action

## **6\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Password

Empty

"Please enter your password."

Password

Incorrect

"Incorrect password. Please try again."

Password

5 wrong attempts

"You have entered an incorrect password multiple times. Please try again after one hour."

Phone Number

Empty

"Please enter your phone number."

Phone Number

Invalid format

"Please enter a valid phone number."

Phone Number

Blocked/unsupported number

"This phone number cannot be used for verification."

Enable 2FA

Method not verified

"Please verify your \[email/phone\] before enabling 2FA."

General

Service unavailable

"Something went wrong. Please try again."

General

Network timeout

"Something went wrong. Please try again."

General

Concurrent state conflict

"The settings have changed. Please refresh the page."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

User refreshes the page

Page reloads using existing session; any in-flight modal is discarded

User disables both methods then closes the browser

2FA is fully off; no first-login pop-up reappears at next login; warning banner shown when user returns to Settings

User changes phone while SMS 2FA is active

After password confirm, new phone saved and verified; SMS 2FA remains active on the new number (no re-enable required)

User changes phone while SMS 2FA is NOT active

After password confirm, new phone saved and verified; SMS 2FA status remains off

User loses SMS access (only SMS active)

Recovery via login-time verification (change phone) or support intervention

User loses both email and SMS access

Must contact support for manual intervention

Google user signs out of Google mid-session

Application session terminates; handled by core authentication layer

User clicks Enable on Email while SMS already active

Email 2FA activates independently; SMS remains active; both rows show "Activated"

User clicks Disable on a method that is not currently active

Button not shown; defensive server check returns: "Method is not currently active."

Concurrent sessions (two tabs)

Last successful action wins; the other tab displays stale state until refreshed

User clicks Confirm in password modal with wrong password 5 times

Account is locked out of 2FA actions for 1 hour; other app functionality unaffected

User cancels the password modal

No action is performed; Settings state unchanged

User closes password modal mid-entry

No action is performed; Settings state unchanged

Support-initiated 2FA disable

User notified via available contact channels; recorded in audit log

User tries to verify a phone already verified on another account

Allowed (same phone across accounts is permitted); rate limit still enforced

## **8\. Acceptance Criteria**

*   **Accurate Status Display:** Settings page shows correct "Verified / Not Verified / Activated" statuses at all times; both 2FA rows can show "Activated" simultaneously
*   **Per-Action Password:** Every state-changing action (Verify Email, Verify/Change Phone, Enable 2FA, Disable 2FA) requires a password confirmation for regular users; no OTP is involved
*   **Google Users – No Prompt:** Google users execute all actions without a password prompt (rely on Google OAuth session)
*   **Verification Before Activation:** Email verification is required before Email 2FA can be enabled; phone verification required before SMS 2FA
*   **Google Restriction:** Google users do not see or cannot activate the Email 2FA Enable option
*   **Independent Methods:** Email and SMS 2FA can be enabled and disabled independently; either or both can be active
*   **Phone Change Auto-Activation:** If SMS 2FA was active on the old phone, it remains active on the new phone immediately after change (no re-enable)
*   **Post-Disable Behavior:** If 2FA remains on (other method active), no warning/banner; if fully off, warning banner appears in Settings
*   **Phone Storage Separation:** Phone changes save to the user master as personal mobile, not agency contact
*   **Support Recovery:** Support recovery path is available when all available channels are unreachable
*   **Audit Logging:** All state changes (including password challenge results) are recorded in the audit log
*   **Password Lockout:** 5 wrong password attempts trigger a 1-hour lockout on 2FA actions; auto-unlock after exactly 1 hour
*   **Rate Limiting:** SMS rate limiting per phone number across all accounts remains enforced for any future SMS-based actions (e.g., support-triggered notices)

## **9\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

User Authentication System

Internal Dependency

Cannot validate passwords or session state; page inaccessible or actions fail

Google OAuth Service

External Integration

Google users cannot maintain an authenticated session to reach or use the page

User Master Database

Data Dependency

Cannot read/write 2FA state, verification status, or phone number

Agency Master Database

Data Dependency

Cannot suggest agency phone numbers for pre-fill

Session Management

Internal Dependency

Application-level session handling

Audit Log Service

Internal Dependency

Changes not recorded; compliance impacted

Rate Limiting Service

Internal Dependency

Cannot enforce password-attempt lockouts

Phone Number Validation Service

External Integration

Cannot validate numbers or check blocked list

Support/Admin Tooling

Internal Dependency

Cannot perform manual 2FA reset for lost-access users

## **10\. References**

*   **Figma Designs:** [2-Step Verification Settings](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=29490-143171&t=hlJPZKI33RrWvjz0-0)
*   **Related FRD:** Agency Auth – Two-Factor Authentication (2FA) Setup (first-login setup, login verification with dual-channel delivery, login-time contact verification)

6\. Data Management Module

# **FRD #6: Data Management Module**

**Module Name:** Data Management  
**Version:** 2.1  
**Date:** April 30, 2026

## **1\. Module Overview**

**Module Name:** Data Management

**Purpose:** The Data Management module provides centralized configuration for system-wide dropdown options, custom fields, tags, and data structures that ensure consistency across all projects and modules.

**Business Goals:**

*   Enable customization of data collection fields without code changes
*   Maintain data integrity through controlled dropdown management
*   Provide flexible tagging and categorization capabilities with parent-child hierarchy support
*   Ensure consistent data structures across all system modules
*   Support tag management at project, event, and task levels with proper inheritance rules

**Page Structure:**

*   **Data Management** page contains two tabs: "Company Data" and "Custom Fields"
*   **Company Data tab** displays Lead Sources, Tags, Service Area, and Events sections
*   **Custom Fields tab** displays the custom fields list with creation capability
*   **Tag Management** is accessed via the "Edit" button on the Tags row, opening a sub-page with back navigation

## **2\. User Roles & Permissions**

**Role**

**View Access**

**Edit Access**

**Special Permissions**

Agency Owner

Full access

All settings

Can delete any data element

Admin

Full access

All settings

Can delete any data element

Project Manager

View only

None

Read-only access

Editor

View only

None

Read-only access

Supervising Editor

View only

None

Read-only access

Contractor

No access

None

Section not visible

## **3\. User Flow**

### Data Management Page Access

3.1 The user navigates to Settings and clicks on Data Management.

3.2 The system displays the Data Management page with the heading "Data Management" and subtitle "Easily organize and customize project, contact, and lead information with flexible fields, tags, and sources."

3.3 The system displays two tabs: "Company Data" (selected by default) and "Custom Fields".

### Company Data Tab Display

3.4 The Company Data tab displays four sections in a list format:

*   **Lead Sources** — Shows example text (e.g., "Instagram, Referral, Google Ads"), count badge (e.g., "15 Sources"), and "Edit" button
*   **Tags** — Shows description "Organize and categorize items with tags", count badge (e.g., "27 Tags" or "0 Tags"), and "Edit" button
*   **Service Area** — Shows "These are managed under the brand settings", count badge (e.g., "33 Areas"), and "View" button
*   **Events** — Shows "These are managed under the brand settings", count badge (e.g., "22 Events"), and "Edit" button

### Lead Source Management Flow

3.5 The user clicks the "Edit" button on the Lead Sources row.

3.6 The system opens the Lead Source management sub-page with back arrow navigation.

3.7 The user views the Lead Sources section showing current source options including system-locked defaults.

3.8 The user clicks the "Add" button to create a new lead source.

3.9 The system opens an input field for entering the source name.

3.10 The user enters a unique lead source name up to 100 characters.

3.11 The system validates uniqueness in real-time as the user types.

3.12 The user clicks Save to add the new lead source.

3.13 The system adds the source to the list and makes it available system-wide.

3.14 The user clicks the Delete icon next to a lead source to remove it.

3.15 The system checks if the lead source is attached to any projects.

3.16 If the lead source is NOT attached to any projects, the system displays a confirmation dialog titled "Delete Lead Source" with the message "Are you sure you want to delete this lead source? This action cannot be undone." and "Cancel" / "Delete" buttons.

3.17 If the lead source IS attached to one or more projects, the system displays a warning dialog titled "Delete Lead Source" with a warning icon and the message "This lead source is attached to one or more projects. Deleting it will remove the lead source from all associated projects, and the lead source field will become blank in those projects. This action cannot be undone." with "Cancel" / "Delete Anyway" buttons.

3.18 The user clicks "Delete" or "Delete Anyway" to confirm deletion, or "Cancel" to abort.

3.19 Upon confirmation, the system deletes the lead source and removes it from all associated projects, leaving the lead source field blank in those projects.

3.20 The system displays a success message confirming the deletion.

3.21 The user clicks the back arrow (←) to return to the Data Management > Company Data tab.

### Tag Management Flow

3.22 The user clicks the "Edit" button on the Tags row in the Company Data tab.

3.23 The system opens the Tag Management sub-page with:

*   Back arrow (←) for navigation
*   Title: "Tag Management"
*   Subtitle: "Tags help you identify where your leads originate"
*   Input field with placeholder "Type to add a new tag"
*   "Add New" button
*   List of existing tags (or empty state if no tags exist)

3.24 If no tags exist, the system displays the empty state message: "No tags yet. Add your first one above."

3.25 The user creates a new tag by entering a name in the input field and clicking the "Add New" button.

3.26 The system validates the tag name for uniqueness and adds the tag to the agency-level Tag Management repository.

3.27 The system makes the newly created tag available across all projects, events, and tasks within the agency.

3.28 The user clicks the Delete icon next to a tag to remove it.

3.29 The system checks if the tag is attached to any projects, events, or tasks.

3.30 If the tag is NOT attached to anything, the system displays a confirmation dialog titled "Delete Tag" with the message "Are you sure you want to delete this tag? This action cannot be undone." and "Cancel" / "Delete" buttons.

3.31 If the tag IS attached to one or more projects, events, or tasks, the system displays a warning dialog titled "Delete Tag" with a warning icon and the message "This tag is attached to one or more projects, events, or tasks. Deleting it will remove the tag from all associated items. Other tags on those items will remain unaffected. This action cannot be undone." with "Cancel" / "Delete Anyway" buttons.

3.32 The user clicks "Delete" or "Delete Anyway" to confirm deletion, or "Cancel" to abort.

3.33 Upon confirmation, the system deletes the tag and removes it from all associated projects, events, and tasks.

3.34 The system displays a success message confirming the deletion.

3.35 The user clicks the back arrow (←) to return to the Data Management > Company Data tab.

### Custom Fields Tab Flow

3.36 The user clicks the "Custom Fields" tab.

3.37 The system displays the Custom Fields tab with:

*   Helper text: "These fields will show up in your project details"
*   List of existing custom fields (or empty state if no custom fields exist)

3.38 If no custom fields exist, the system displays the empty state:

*   Icon graphic with avatars
*   Title: "No Custom Fields Yet"
*   Message: "Create custom fields to track the information that matters most to you."
*   Button: "+ Add Custom Field"

3.39 The user clicks "+ Add Custom Field" button (or "+ New Custom Field" if fields already exist).

3.40 The system opens the custom field configuration modal.

3.41 The user enters the field name and selects the field type from the dropdown.

3.42 The system shows configuration options based on selected field type.

3.43 The user sets visibility options by checking Client or Contractor boxes.

3.44 The system ensures Agency checkbox remains checked and disabled.

3.45 The user assigns the field to specific event-service combinations.

3.46 The system validates that all required field properties are configured.

3.47 The user clicks Save to create the custom field.

3.48 The system applies the field to all matching projects immediately.

3.49 The user clicks the Delete icon next to a custom field to remove it.

3.50 The system checks if the custom field is attached to any projects.

3.51 If the custom field is NOT attached to any projects, the system displays a confirmation dialog titled "Delete Custom Field" with the message "Are you sure you want to delete this custom field? This action cannot be undone." and "Cancel" / "Delete" buttons.

3.52 If the custom field IS attached to one or more projects, the system displays a warning dialog titled "Delete Custom Field" with a warning icon and the message "This custom field is attached to one or more projects. Deleting it will remove the field and its data from all associated projects. This action cannot be undone." with "Cancel" / "Delete Anyway" buttons.

3.53 The user clicks "Delete" or "Delete Anyway" to confirm deletion, or "Cancel" to abort.

3.54 Upon confirmation, the system deletes the custom field and removes it from all associated projects.

3.55 The system displays a success message confirming the deletion.

### Tag Application Flow (Projects, Events, Tasks)

3.56 The user navigates to a Project and opens the Overview tab to view and manage project-level tags.

3.57 The user clicks on the Tags field in the Project Overview and selects or creates a tag.

3.58 The system automatically applies the selected tag to all events within that project following the parent-child inheritance rule.

3.59 The user navigates to an individual Event within the project to manage event-specific tags.

3.60 The user adds a tag directly to the event from the Event Details view.

3.61 The system applies the tag only to that specific event and makes it visible in the project-level Overview tab under that event's tag list.

3.62 The user removes a tag from an individual event by clicking the remove icon next to the tag.

3.63 The system removes the tag only from that specific event without affecting other events or the project-level tag visibility.

3.64 The user removes a tag from the project-level Overview tab.

3.65 The system removes the tag from the project and cascades the removal to all events under that project.

3.66 The user navigates to the Tasks module and creates a new task.

3.67 The user adds tags to the task by selecting from existing tags or typing a new tag name in the Tags field.

3.68 The system displays the tags in the task form but does not create new tags in the repository until the task is saved.

3.69 The user clicks the Create or Save button to save the task.

3.70 The system creates any new tags in the agency-level Tag Management repository and associates all selected tags with the task.

3.71 The user returns to Tag Management Settings to view all tags including those created from projects, events, and tasks.

## **4\. Functional Logic**

### 4.1 Page Structure

• The Data Management page contains two tabs: "Company Data" and "Custom Fields".

• The "Company Data" tab is selected by default when navigating to Data Management.

• The Company Data tab displays four sections: Lead Sources, Tags, Service Area, and Events.

• Each section row shows a description/example, count badge, and action button (Edit or View).

• The Custom Fields tab displays the list of custom fields or the empty state if no fields exist.

• Sub-pages (Lead Source Management, Tag Management) include a back arrow (←) that returns to the Data Management > Company Data tab.

### 4.2 Empty States

**Tags Empty State (Tag Management Sub-page):** • When no tags exist in the agency, the system displays an empty state below the input field. • Empty state message: "No tags yet. Add your first one above." • The input field and "Add New" button remain visible above the empty state message. • Once a tag is added, the empty state disappears and the tag list appears.

**Custom Fields Empty State (Custom Fields Tab):** • When no custom fields exist, the system displays a centered empty state UI. • The empty state includes:

*   Icon graphic with decorative avatars
*   Title: "No Custom Fields Yet"
*   Message: "Create custom fields to track the information that matters most to you."
*   Button: "+ Add Custom Field" (yellow/primary button) • Once a custom field is created, the empty state is replaced by the custom fields list. • The helper text "These fields will show up in your project details" remains visible above the content area.

**Lead Sources:** • Lead Sources always contain system-locked defaults (e.g., Client Referral, Other) and never display an empty state. • System-locked lead sources cannot be deleted.

### 4.3 Count Display

• Each section in the Company Data tab displays a count badge showing the number of items.

• Count format examples:

*   Lead Sources: "15 Sources"
*   Tags: "27 Tags" or "0 Tags" (when empty)
*   Service Area: "33 Areas"
*   Events: "22 Events"

• The Tags count updates immediately when tags are added or deleted.

### 4.4 Lead Source Management

**Lead Sources:** • Lead sources define the origins of business leads and are essential for marketing analytics and ROI tracking.

• The system provides default lead sources including Google, Facebook, Instagram, Referral, Website, Email, Phone Call, Walk-in, and Other.

• Users can add unlimited custom lead sources to match their specific marketing channels and business needs.

**Adding Lead Source:** • To add a new lead source, the user types the name in the input field and clicks the "Add" button.

• The "Add" button remains disabled until the user types at least one character in the input field.

• Each lead source name must be unique within the system and can contain up to 100 characters.

• If the user tries to add a lead source with a name that already exists, the system displays a validation message: "Lead source already exists."

**Editing Lead Source:** • Each lead source has an "Edit" action available.

• When the user clicks "Edit," the lead source name becomes an editable text field with "Save" and "Cancel" options.

• Clicking "Save" updates the lead source name; clicking "Cancel" discards changes and reverts to view mode.

• Changes to lead source names update the display but maintain the underlying ID for data consistency.

• The system validates uniqueness in real-time to prevent duplicate entries.

**"Other" Lead Source Option:** • "Other" is a default lead source option that allows users to enter custom values during project creation or editing.

• When a user selects "Other" as the lead source in the project lead source dropdown, a text field appears allowing them to enter a custom value.

• The custom value entered is stored at the project level only and is displayed as the lead source for that specific project.

• The custom value entered for "Other" is NOT added to the Lead Sources list in Data Management.

• Each "Other" entry remains project-specific and does not create a new reusable lead source option in the master list.

• When viewing the project, the system displays the custom value only (not "Other" or "Other - \[value\]").

• For reporting purposes, custom values entered under "Other" are displayed separately, allowing for granular analytics while keeping the master Lead Sources list clean and controlled.

• Users who want a custom lead source to be reusable across multiple projects must add it to the Lead Sources list in Data Management.

**Deleting Lead Source:** • Users can delete any lead source from the system by clicking the Delete icon.

• The system checks whether the lead source is currently attached to any projects before displaying the appropriate confirmation message.

**When Lead Source is NOT Attached to Any Projects:** • The system displays a confirmation dialog with the following content:

*   Title: "Delete Lead Source"
*   Message: "Are you sure you want to delete this lead source? This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete" (primary)

• Clicking "Delete" removes the lead source from the system immediately.

• Clicking "Cancel" closes the dialog with no changes made.

**When Lead Source IS Attached to One or More Projects:** • The system displays a warning dialog with the following content:

*   Title: "Delete Lead Source"
*   Message: "This lead source is attached to one or more projects. Deleting it will remove the lead source from all associated projects, and the lead source field will become blank in those projects. This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete Anyway" (primary/destructive)

• Clicking "Delete Anyway" removes the lead source from the system and sets the lead source field to blank in all affected projects.

• Clicking "Cancel" closes the dialog with no changes made.

• Deletion is permanent and cannot be undone.

• Note: The "Other" lead source option cannot be deleted as it is a system default.

**General Behavior:** • The lead source list appears in dropdown menus throughout the system for consistent selection.

• When a lead source is deleted, all projects that had that lead source assigned will have their lead source field become blank/empty.

• Custom values entered via "Other" are preserved at the project level even if other lead sources are modified or deleted.

### 4.5 Custom Field Creation

• Custom fields act as a mini form builder allowing agencies to display additional project or event-specific information to clients or contractors.

• The system supports multiple field types including Short Text, Long Text, Single Select, Multi-select, Number field, Datepicker, and Link.

• Custom field names must be unique within the same field type. Two fields can have the same name if they are different field types (e.g., "Notes" as Short Text and "Notes" as Long Text are allowed, but two Short Text fields named "Notes" are not allowed).

• If a user attempts to create a custom field with a name that already exists for the selected field type, the system displays an inline error message: "A field with this name already exists for the selected field type. Change the field type or the field name to continue."

• Field types determine the display format and data presentation when showing information to clients or contractors.

• Each custom field can be configured as either optional or mandatory, and this setting applies universally across all projects within the agency.

• Dropdown fields require defining the available options that can be displayed.

• Number fields support decimal values and allow negative numbers. No minimum or maximum value restrictions are enforced.

• Date fields allow display of past, present, and future dates with no restrictions on date ranges.

• Short Text fields have a maximum character limit of 100 characters. Long Text fields have a maximum character limit of 5,000 characters. All character types are permitted for both.

### 4.5.1 Custom Field Value Entry

• Custom field values can only be entered and edited by agency-side users. Clients and contractors cannot enter or modify custom field values.

• The following roles can enter/edit custom field values:

*   Agency Owner: Can enter/edit values for all projects
*   Admin: Can enter/edit values for all projects
*   Project Manager: Can enter/edit values only for projects they are assigned to

• Custom field values are entered from the Project Details page within each project.

• Editors, Supervising Editors, and Contractors cannot enter or edit custom field values.

### 4.5.2 Custom Field Display for Clients and Contractors

• Custom fields appear as read-only in both the Client Portal and Contractor Portal.

• Clients and contractors can view custom field values but cannot edit them.

• If a custom field has no value entered by the agency, the field displays the field label with a blank/empty value (no placeholder text).

• Example: A field labeled "Wedding Theme" with no value entered displays as "Wedding Theme: " (blank after the colon).

• The visibility of each custom field to clients and contractors is controlled by the visibility checkboxes during field configuration.

### 4.6 Custom Field Visibility Controls

• Visibility settings determine who can view the custom field values across the system.

• The Agency checkbox is always selected and cannot be disabled, ensuring internal visibility.

• The Client checkbox controls whether the field appears in client-facing portals.

• The Contractor checkbox determines if contractors can view the field in their project assignments.

• Visibility settings apply immediately to all existing and future instances of the field.

• Hidden fields still collect and store data but are not displayed to restricted user types.

• Changes to visibility do not delete existing data but only affect its display permissions.

### 4.7 Custom Field Assignment

• Custom fields can be assigned to specific combinations of event types and service categories.

• This granular assignment ensures relevant fields appear only where they make business sense.

• A wedding photography project might have different custom fields than a corporate headshot session.

• Fields automatically appear on projects matching the assigned event-service combinations.

• The system applies fields to existing projects immediately upon configuration.

• Removing field assignments hides the field from future projects but preserves existing data.

• Multiple fields can be assigned to the same event-service combination for comprehensive data collection.

### 4.8 Custom Field Deletion

• Users can delete any custom field from the system by clicking the Delete icon.

• The system checks whether the custom field is currently attached to any projects before displaying the appropriate confirmation message.

**When Custom Field is NOT Attached to Any Projects:** • The system displays a confirmation dialog with the following content:

*   Title: "Delete Custom Field"
*   Message: "Are you sure you want to delete this custom field? This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete" (primary)

• Clicking "Delete" removes the custom field from the system immediately.

• Clicking "Cancel" closes the dialog with no changes made.

**When Custom Field IS Attached to One or More Projects:** • The system displays a warning dialog with the following content:

*   Title: "Delete Custom Field"
*   Message: "This custom field is attached to one or more projects. Deleting it will remove the field and its data from all associated projects. This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete Anyway" (primary/destructive)

• Clicking "Delete Anyway" removes the custom field from the system and removes the field and its data from all affected projects.

• Clicking "Cancel" closes the dialog with no changes made.

• Deletion is permanent and cannot be undone.

### 4.9 Event Types and Service Areas

• Event types and service areas are read-only in Data Management and redirect to Brand Management for editing.

• This separation ensures brand-specific configurations remain isolated from global data settings.

• The read-only display shows current options for reference when configuring custom fields.

• Users must navigate to Brand Management to add, edit, or delete event types and service areas.

• This architectural decision prevents accidental cross-brand data modifications.

### 4.10 Tag Management

**Agency-Level Tag Repository:** • Tags are managed at the agency level under Settings → Data Management → Tags (Edit) and are not brand-specific.

• When a new tag is created from any location including project overview, event details, or task creation, the tag is automatically added to the agency-level Tag Management repository.

• Tags can only be permanently deleted from the Tag Management sub-page; they cannot be deleted from Projects, Events, or Tasks (only removed/unassigned).

• Tags support special characters, numbers, and spaces, allowing natural language labels such as "VIP Client" or "Rush Order - 2024".

• The system maintains a central tag repository to ensure consistency and enable filtering across all modules.

• Tag names must be unique within the agency, and the system validates uniqueness in real-time during tag creation.

• Tags have a maximum character limit of 50 characters.

**Deleting Tags:** • Users with the Owner or Admin role can permanently delete a tag from the Tag Management sub-page.

• The system checks whether the tag is currently attached to any projects, events, or tasks before displaying the appropriate confirmation message.

**When Tag is NOT Attached to Anything:** • The system displays a confirmation dialog with the following content:

*   Title: "Delete Tag"
*   Message: "Are you sure you want to delete this tag? This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete" (primary)

• Clicking "Delete" removes the tag from the system immediately.

• Clicking "Cancel" closes the dialog with no changes made.

**When Tag IS Attached to One or More Projects, Events, or Tasks:** • The system displays a warning dialog with the following content:

*   Title: "Delete Tag"
*   Message: "This tag is attached to one or more projects, events, or tasks. Deleting it will remove the tag from all associated items. Other tags on those items will remain unaffected. This action cannot be undone."
*   Buttons: "Cancel" (secondary) | "Delete Anyway" (primary/destructive)

• Clicking "Delete Anyway" removes the tag from the system and removes it from all associated projects, events, and tasks. Other tags on those items remain unaffected.

• Clicking "Cancel" closes the dialog with no changes made.

• Deletion is permanent and cannot be undone.

**Parent-Child Hierarchy (Project → Events):** • Tags managed at the project level through the Overview tab are treated as the master set for that project.

• When a tag is added at the project level, the system automatically applies that tag to all events under the project.

• When a tag is removed from the project level, the system cascades the removal to all events under that project.

• This parent-child inheritance ensures consistent tagging across the entire project scope without requiring manual updates to each event.

• The cascade operation happens immediately and does not require page refresh for changes to take effect.

**Event-Level Tag Isolation:** • Event-level tag changes are isolated and do not cascade sideways to other events or upward to the project level.

• If a tag exists in the project and is applied to multiple events, removing that tag from one specific event does not remove it from other events within the same project.

• Removing a tag at the event level does not remove it from the project-level tag list or affect its visibility in the project Overview tab.

• If a new tag is created inside an event, the tag becomes visible in the project Overview tab under that specific event's tag list.

• If an event-created tag is later removed from that event, the tag remains visible in the project-level view because event-level removal does not delete the tag from project-level visibility.

• This isolation ensures that event-specific tagging decisions do not unintentionally impact other events or the overall project taxonomy.

**Project Overview Tag Selection and Promotion:** • Tags that are visible in the project Overview tab include both project-level tags and tags that were originally created via individual events.

• When a user selects a tag from the project Overview tab, the system applies that tag across all events in the project regardless of where the tag was originally created.

• This functionality allows users to promote event-specific tags to project-wide tags through the Overview interface without navigating to each event individually.

• The tag promotion is immediate and applies to all current events under the project.

**Single-Event Projects:** • Projects with only one event follow the same parent-child rules as multi-event projects.

• No special logic or exceptions exist for single-event projects.

• Adding a tag at the project level applies it to the single event, and adding a tag at the event level makes it visible in the project Overview.

• This consistency ensures predictable behavior regardless of project structure.

**Task Module Tag Creation Rules:** • In the Tasks module, tags are created in the agency-level Tag Management repository only when the task is saved.

• This rule applies to both the Create Task operation and the Edit Task operation.

• Until the user clicks Save or Create to save the task, any new tags entered in the tag field exist only in the form and are not created in the system.

• Once the task is saved, the system simultaneously creates any new tags in the Tag Management repository and associates all selected tags with the task.

• If the user closes the task form without saving, any new tags that were typed but not saved are discarded and not created in the system.

• Users can select from existing tags in the repository or type new tag names during task creation and editing.

• This save-dependent creation prevents orphan tags from being created when users abandon task creation.

**Tag Application Scope Summary:** • Tags added from the Project Overview tab apply to the entire project and cascade to all events within that project.

• Tags added from an individual Event Details view apply only to that specific event and become visible in the project Overview without affecting other events.

• Tags added to Tasks are associated only with that specific task and do not affect project or event tags.

• All tag changes propagate immediately across the platform through WebSocket connections without requiring page refreshes.

• Tags created from any location (Data Management, project, event, or task) are stored centrally in the agency-level Tag Management repository and become available for selection across all modules.

### 4.11 Data Validation and Integrity

• All data modifications undergo validation before saving to prevent corruption or conflicts.

• The system prevents creation of duplicate entries through real-time validation.

• Unique name constraints are enforced at the database level for absolute consistency.

• Changes are logged with timestamps and user information for audit compliance.

• The system performs referential integrity checks before allowing deletions.

• Bulk operations are wrapped in transactions to ensure all-or-nothing execution.

### 4.12 Real-time Propagation

• All data management changes propagate immediately across active user sessions.

• The system uses WebSocket connections to push updates to connected clients.

• Dropdown lists refresh automatically when new options are added or removed.

• Custom field changes apply instantly without requiring page refreshes.

• Cache invalidation ensures all users see the most current configuration.

• Background jobs handle updating large datasets when structural changes occur.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

Lead Source Name

Text Input

Max 100 chars, unique

Yes

Lead Source "Other" Custom Value

Text Input

Max 100 chars, stored at project level only, not added to Data Management list

No

Custom Field Name

Text Input

Max 100 chars, unique within same field type

Yes

Custom Field Type

Dropdown

Valid type selection

Yes

Field Options

Text List

Required for dropdowns

Conditional

Agency Visibility

Checkbox

Always checked, disabled

Yes

Client Visibility

Checkbox

Boolean true/false

No

Contractor Visibility

Checkbox

Boolean true/false

No

Event Assignment

Multi-select

Valid event types

Yes

Service Assignment

Multi-select

Valid service types

Yes

Tag Name

Text Input

Max 50 chars, unique within agency

Yes

Tag Assignment Level

System-Determined

Project-level, Event-level, or Task-level based on creation context

Yes

Field Required

Checkbox

Boolean true/false

No

Default Value

Varies

Based on field type

No

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Post-Success Action**

**Duration**

Add Lead Source

"Lead source added successfully"

Refresh dropdown lists

3 seconds

Edit Lead Source

"Lead source updated successfully"

Update all dropdowns

3 seconds

Delete Lead Source (not attached)

"Lead source deleted successfully"

Remove from list

3 seconds

Delete Lead Source (attached)

"Lead source deleted successfully. It has been removed from all associated projects."

Remove from list, clear field in affected projects

3 seconds

Create Custom Field

"Custom field created successfully"

Apply to projects

3 seconds

Update Custom Field

"Custom field updated successfully"

Refresh field instances

3 seconds

Delete Custom Field (not attached)

"Custom field deleted successfully"

Remove from list

3 seconds

Delete Custom Field (attached)

"Custom field deleted successfully. It has been removed from all associated projects."

Remove from list and all project instances

3 seconds

Create Tag

"Tag created successfully"

Add to tag list

3 seconds

Delete Tag (not attached)

"Tag deleted successfully"

Remove from list

3 seconds

Delete Tag (attached)

"Tag deleted successfully. It has been removed from all associated projects, events, and tasks."

Remove from list and all associations

3 seconds

Tag Added to Project

"Tag added successfully"

Cascade to all events

3 seconds

Tag Removed from Project

"Tag removed successfully"

Cascade removal

3 seconds

Tag Added to Event

"Tag added successfully "

Update event and project view

3 seconds

Tag Removed from Event

"Tag removed successfully"

Update event only

3 seconds

Task Saved with New Tags

"Task saved successfully"

Create tags and save task

3 seconds

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**User Action Required**

Duplicate Lead Source

"A lead source with this name already exists"

Choose unique name

Duplicate Field Name

"A field with this name already exists for the selected field type. Change the field type or the field name to continue."

Change field type or choose unique name

Invalid Field Type

"Please select a valid field type"

Select from dropdown

No Options Provided

"Dropdown fields require at least one option"

Add options

Tag Too Long

"Tag name cannot exceed 50 characters"

Shorten tag

Duplicate Tag Name

"A tag with this name already exists"

Use the existing tag or choose a different name

Tag Cascade Failure

"Unable to apply tag changes to all events. Please try again."

Retry operation

Tag Creation Pending

"Tags will be created when the task is saved."

Save the task to create tags

Tag Removal Cascade Failure

"Unable to remove tag from all events. Please try again."

Retry operation

Lead Source Deletion Failed

"Unable to delete lead source. Please try again."

Retry operation

Custom Field Deletion Failed

"Unable to delete custom field. Please try again."

Retry operation

Tag Deletion Failed

"Unable to delete tag. Please try again."

Retry operation

Cannot Delete "Other"

"The 'Other' lead source is a system default and cannot be deleted."

N/A

Permission Denied

"You don't have permission to modify data settings"

Contact admin

Network Error

"Unable to save changes. Please try again"

Retry operation

Validation Failed

"Please correct the errors before saving"

Fix highlighted fields

## **8\. Edge Cases**

**Scenario**

**System Behavior**

**Mitigation**

Circular field dependencies

Validation prevents creation

Check dependencies

Mass deletion attempt

Confirmation required for each item

Batch validation

Special characters in names

Some may cause issues

Sanitize input

Field type change after data exists

Blocked to prevent data loss

Create new field

Dropdown with 100+ options

Performance impact

Implement search

Simultaneous field creation

Possible duplicates

Real-time validation

Import/export conflicts

Data mapping issues

Validation on import

Cache synchronization

Stale data possible

Force refresh option

Lead source deleted while user is editing a project

Project saves with blank lead source

Real-time sync notification

Custom field deleted while user is editing a project

Field disappears from project form

Real-time sync via WebSocket

Tag deleted while user is viewing project with that tag

Tag disappears from project view

Real-time sync via WebSocket

Tag removed from one event while project-level tag exists

Tag is removed only from that specific event; other events and project-level retain the tag

Parent-child isolation rule

Tag created in event then deleted from that event

Tag remains visible in project Overview tab; event removal does not delete from project visibility

Visibility preservation rule

Task form closed without saving after adding new tags

New tags are not created in the system; only saved tasks create tags

Save-dependent creation rule

Same tag selected at both project and event level

Single tag instance maintained; no duplicate associations created

Uniqueness validation at assignment

Project-level tag removal with large number of events (50+)

System cascades removal to all events using background processing

Batch processing with progress indicator

Tag renamed in Tag Management Settings

Updated name reflects immediately across all associated projects, events, and tasks

Referential integrity maintained via tag ID

User adds tag to project while another user adds same tag to event

System prevents duplicate; first save wins and second user sees existing tag

Real-time uniqueness validation

Network failure during tag cascade operation

System rolls back partial changes and displays error

Transaction-based operations with retry option

User cancels deletion after viewing warning

No changes made; dialog closes

Cancel button available

Multiple users attempt to delete same lead source/tag/custom field

First deletion succeeds; second user sees "not found" error

Real-time sync

User selects "Other" and enters custom value matching existing lead source

Custom value is stored at project level only; does not affect Data Management list

Project-level isolation

User attempts to delete "Other" lead source

System prevents deletion with error message

"Other" is protected as system default

Multiple projects use "Other" with same custom value

Each project stores its own instance; no consolidation occurs

Project-level storage

Report generated with multiple "Other" custom values

Each custom value displayed separately in reports

Granular analytics support

Tags empty state displayed

"No tags yet. Add your first one above." message shown

Input field remains visible above message

Custom fields empty state displayed

"No Custom Fields Yet" with button displayed

"+ Add Custom Field" button available

Tags count shows 0

"0 Tags" displayed in Company Data tab

Clicking Edit opens Tag Management sub-page with empty state

Same custom field name with different field types

System allows creation; both fields exist independently

Names are unique per field type, not globally

Same custom field name with same field type

System blocks creation; displays inline error message

User must change name or field type

Custom field with no value viewed by client

Field displays with label and blank value

No placeholder shown

Project Manager tries to edit custom field on unassigned project

Edit action blocked or field not editable

Permission restricted to assigned projects

Client attempts to edit custom field value

Field is read-only; no edit option available

Read-only display enforced

## **9\. Acceptance Criteria**

### 9.1 Page Structure

• Data Management page displays with two tabs: "Company Data" and "Custom Fields".

• Company Data tab is selected by default.

• Company Data tab shows Lead Sources, Tags, Service Area, and Events sections with count badges and action buttons.

• Custom Fields tab shows the list of custom fields or empty state.

• Sub-pages (Lead Source Management, Tag Management) include back arrow navigation returning to Company Data tab.

### 9.2 Empty States

• When no tags exist, Tag Management sub-page displays: "No tags yet. Add your first one above."

• The tag input field and "Add New" button remain visible above the empty state message.

• When no custom fields exist, Custom Fields tab displays:

*   Title: "No Custom Fields Yet"
*   Message: "Create custom fields to track the information that matters most to you."
*   Button: "+ Add Custom Field"

• Lead Sources never display an empty state as system defaults always exist.

### 9.3 Lead Source Management

• Users can add, edit, and delete lead sources.

• Uniqueness is enforced for lead source names.

• When deleting a lead source not attached to any projects, a confirmation dialog is displayed with title "Delete Lead Source" and "Cancel" / "Delete" buttons.

• When deleting a lead source attached to projects, a warning dialog is displayed with title "Delete Lead Source" explaining the impact, with "Cancel" / "Delete Anyway" buttons.

• Upon deletion of an attached lead source, the lead source field becomes blank in all affected projects.

• The "Other" lead source option cannot be deleted.

• Changes reflect immediately across the platform.

### 9.4 Lead Source "Other" Option

• When "Other" is selected as the lead source during project creation/editing, a text field appears for custom value entry.

• Custom values entered for "Other" are stored at the project level only.

• Custom values entered for "Other" do NOT appear in the Lead Sources list in Data Management.

• The project displays the custom value only (not "Other" or "Other - \[value\]").

• Reports display "Other" custom values separately for granular analytics.

• Users who want reusable lead sources must add them to Data Management.

### 9.5 Custom Field Configuration

• All field types work correctly.

• Custom field names must be unique within the same field type.

• Duplicate names are allowed across different field types.

• When a duplicate name is entered for the same field type, an inline error message displays: "A field with this name already exists for the selected field type. Change the field type or the field name to continue."

• Visibility controls function properly.

• Assignment to event-service combinations works.

• Fields appear on appropriate projects.

### 9.5.1 Custom Field Value Entry

• Custom field values can only be entered by Agency Owner, Admin, and Project Manager (on assigned projects).

• Custom field values are entered from the Project Details page.

• Editors, Supervising Editors, and Contractors cannot enter or edit custom field values.

### 9.5.2 Custom Field Display

• Custom fields appear as read-only in both Client Portal and Contractor Portal.

• Clients and contractors can view but cannot edit custom field values.

• If no value is entered, the field displays the field label with a blank value (no placeholder).

### 9.6 Custom Field Deletion

• When deleting a custom field not attached to any projects, a confirmation dialog is displayed with title "Delete Custom Field" and "Cancel" / "Delete" buttons.

• When deleting a custom field attached to projects, a warning dialog is displayed with title "Delete Custom Field" explaining the impact, with "Cancel" / "Delete Anyway" buttons.

• Upon deletion of an attached custom field, the field and its data are removed from all affected projects.

• Deletion is permanent and cannot be undone.

### 9.7 Tag Hierarchy Management

• Tags added at the project level through the Overview tab automatically apply to all events within that project.

• Tags removed at the project level cascade removal to all events under that project.

• Tags added at the event level apply only to that specific event and do not affect other events.

• Tags removed at the event level do not affect other events or project-level tag visibility.

• Tags created within an event are visible in the project Overview tab under that event's tag list.

• Event-level tag deletion does not remove the tag from project-level visibility.

• Selecting a tag from the project Overview applies it across all events in the project.

• Tags in the Task module are created in the system only when the task is saved, not during form entry.

• All tag hierarchy rules apply consistently regardless of the number of events in a project.

• Tags created from any module appear in the agency-level Tag Management Settings.

### 9.8 Tag Deletion

• Tags can only be permanently deleted from the Tag Management sub-page.

• When deleting a tag not attached to anything, a confirmation dialog is displayed with title "Delete Tag" and "Cancel" / "Delete" buttons.

• When deleting a tag attached to projects, events, or tasks, a warning dialog is displayed with title "Delete Tag" explaining the impact, with "Cancel" / "Delete Anyway" buttons.

• Upon deletion of an attached tag, the tag is removed from all associated items while other tags remain unaffected.

• Deletion is permanent and cannot be undone.

### 9.9 Data Integrity

• Deletion protection displays appropriate warnings for attached items.

• Unique constraints are enforced.

• Changes propagate correctly across all modules.

• Audit trail captures modifications.

### 9.10 User Experience

• Real-time validation provides clear feedback.

• Error messages are helpful and actionable.

• Success confirmations display after each operation.

• Delete dialogs use consistent title format "Delete \[Item Type\]" without question marks.

• Delete dialogs clearly explain the impact of deletions.

• Interface remains responsive during operations.

• Empty states provide clear guidance on next steps.

## **10\. Manual Test Cases**

The comprehensive test cases for the Data Management module are provided in a separate Excel file for upload to the project management system.

**File:** \[Data\_Management\_Comprehensive\_Test\_Cases.xlsx\]

## **11\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Project Module

Uses configured data fields; Lead sources, custom fields, and tags applied at project level

Fields won't appear; Lead source, custom field, and tag management unavailable

Internal Module

Event Module

Tags applied at event level with isolation rules

Event tagging unavailable

Internal Module

Task Module

Tasks use tags from Tag Management; new tags created on task save

Tags cannot be assigned to tasks; task-created tags not available

Internal Module

Brand Management

Event and service types

Cannot assign custom fields

Internal Module

Reporting Module

Uses lead sources for analytics; Displays "Other" custom values separately

Reports incomplete without lead source data

Internal Module

Client Portal

Shows visible custom fields

Fields hidden

Internal Module

Contractor Portal

Shows permitted fields

Fields hidden

Configuration

Database Schema

Stores configurations

Cannot save changes

Library

Form Builder Library

Renders custom fields

Manual field creation

## **12\. References**

*   **Figma Designs:** \[Figma Link\]
*   **Related FRDs:**
    *   \[My\_Profile\_FRD.md\] — Agency Global Settings
    *   \[General\_Settings\_FRD.md\] — Agency Global Settings
    *   \[Business\_Payment\_Details\_FRD.md\] — Agency Global Settings
    *   \[Accepted\_Payment\_Methods\_FRD.md\] — Agency Global Settings
    *   \[Two\_Step\_Verification\_FRD.md\] — Agency Global Settings

7\. Stripe Integration

# **Stripe Integration — Agency Global Settings - FRD**

**Module Name:** Stripe Integration **Version:** 1.5 **Date:** June 25, 2026

## **1\. Module Overview**

**Module Name:** Stripe Integration

**Purpose:** The Stripe Integration module enables agencies to connect their Stripe account(s) to the Pixally CRM platform in order to automate contractor payments. This module provides a flexible configuration system that supports both unified (single Stripe account for all brands) and individual (separate Stripe account per brand) setups, allowing agencies to manage payment infrastructure at the brand level as they scale.

**Business Goals:**

*   Enable agencies to connect Stripe for automated contractor payment processing, eliminating the need for manual payment workflows.  
    
*   Provide flexible brand-level Stripe configuration to support agencies operating multiple brands with distinct or shared financial operations.  
    
*   Facilitate secure bank account linking via Stripe Financial Connections for reliable payout processing.  
    
*   Ensure transactional integrity by enforcing configuration change restrictions during active payment processing.  
    
*   Support seamless brand growth by automatically inheriting Stripe credentials for newly created brands under the shared configuration model.

## **2\. User Roles & Permissions**

**Role**

**Access Level**

**Permissions**

Agency Owner

Full Access

View, configure, edit, switch, disconnect, and manage all Stripe Integration settings including Stripe keys, bank accounts, and configuration mode switching

Admin

No Access

Cannot view or access the Stripe Integration section

Project Manager

No Access

Cannot view or access the Stripe Integration section

**Access Rule:** The Stripe Integration module is exclusively accessible to the Agency Owner. No other role within the agency can view, access, or modify any Stripe Integration settings. If a non-owner role attempts to navigate to this section, the system does not display the Stripe Integration menu item in the left sidebar navigation.

## **3\. User Flow**

### Initial Access & Setup Mode Selection

3.1 The Agency Owner navigates to the Agency Global Settings from the left sidebar menu and clicks on "Stripe Integration."

3.2 The system loads the Stripe Integration page with the heading "Stripe Integration" and the subtitle "Connect your Stripe account to automate payment to your contractors and manage agency billing seamlessly."

3.3 The system displays a persistent yellow helper banner at the top titled "Need Your Stripe Keys?" with descriptive text and an "Open Stripe Dashboard" button that opens the Stripe dashboard in a new browser tab.

3.3a If the Agency Owner navigates to Stripe Integration and the agency has zero brands configured, the system displays the "No Brands Found" empty state. The Agency Owner clicks the "+ Create Brand" button which redirects them to the Brand Creation module. No further steps in the Stripe Integration flow are accessible until at least one brand is created.

3.4 The system checks whether the agency has more than one brand configured in the system.

3.5 If the agency has only one brand, the system skips the setup mode selection and directly displays the Stripe key entry screen for that single brand (proceed to Step 3.10).

3.6 If the agency has more than one brand, the system displays two selectable cards: "One Account for All" (use the same Stripe account across all brands) and "Separate Accounts" (each brand has its own Stripe account).

3.7 The Agency Owner selects one of the two configuration options by clicking on the respective card, which highlights with a border to indicate selection.

3.8 The Agency Owner clicks the "Continue to Next Step →" button to proceed with the selected configuration mode.

3.9 If the user clicks "Continue to Next Step" without selecting a configuration mode, the system displays an error message prompting the user to select an option before proceeding.

### One Account for All — Stripe Key Entry

3.10 The system displays the "Connect Your Payment Account" page with the subtitle "Let's set up Stripe so you can pay your freelancers and contractors automatically."

3.11 The system displays a 3-step instruction guide within a bordered section titled "Enter Your Stripe Keys" explaining how to find Stripe API keys: (1) Log in to Stripe dashboard and click "Developers," (2) Click "API Keys" from the sidebar, and (3) Copy both keys ensuring "Live keys" are used, not "Test keys."

3.12 The Agency Owner enters the Publishable Key in the first input field (placeholder: "pk\_live\_your\_stripe\_publishable\_key").

3.13 The Agency Owner enters the Secret Key in the second input field (placeholder: masked with asterisks).

3.14 The Agency Owner clicks the "Save" button to submit the Stripe keys for validation, or clicks "Cancel" to discard and return to the previous screen.

3.15 The system sends the entered keys to the Stripe API for real-time validation.

3.16 If validation fails, the system displays an error message indicating the keys are invalid and prompts the user to verify and re-enter the correct keys.

3.17 If validation succeeds, the system displays a "✓ Verified & Active" badge next to "Your Connected Credentials," shows all connected brand chips at the top of the section, and displays the Publishable Key (partially masked) and Secret Key (fully masked) in read-only fields.

3.18 The system displays a yellow informational banner stating "Future Brands Automatically Connected — Great news! Any new brands you create in the future will automatically be connected to this Stripe account. No need to set it up again!"

3.19 The system displays two action buttons below the credentials: "Update Credentials" and "Switch to Individual Setup."

### One Account for All — Bank Account Connection (First Brand)

3.20 The system displays the bank account section(s) below the credentials section, with structure and informational messages based on the current connection state (see Section 4.5 for detailed logic).

3.21 The system lists all agency brands with their logo, name, and a "Connect" button for each brand that does not yet have a bank account connected.

3.22 The Agency Owner clicks the "Connect" button next to the first brand to initiate bank account linking.

3.23 The system launches the Stripe Financial Connections external modal, which displays a bank selection interface with a search field and a list of available banks.

3.24 The Agency Owner selects a bank from the Stripe-provided list, completes the authentication and account linking process within the Stripe Financial Connections interface.

3.25 Upon successful bank account connection, the system closes the Stripe modal and updates the display to show the bank name and last four digits of the account number (e.g., "Bank of America (\*\*\*\* 6021)") with brands grouped under the bank accordion, each with a trash icon and "Delete" label for removal.

3.26 The system displays a popup titled "Complete your bank account setup" asking the Agency Owner "Would you like to use this bank account for all your brands?" with "No" and "Yes" buttons.

3.27 If the Agency Owner selects "Yes" in the popup, the system automatically populates the same bank account details for all remaining brands, and the bank accordion updates to show all brands grouped under the same bank.

3.28 If the Agency Owner selects "No" in the popup, the system keeps the bank account connected only for the selected brand, and other brands remain in the "Bank Account Setup" section with "Connect" buttons.

### One Account for All — Bank Account Connection (Subsequent Brands)

3.29 For any brand that needs bank connection after the first brand has been connected (either because the user selected "No" in the first popup, or a new brand was added later), the Agency Owner clicks the "Connect" button next to that brand.

3.30 The system displays the "Connect your Bank account" modal with two radio button options: "Use existing Bank account" (selected by default) and "Create a new Bank account", along with "Cancel" and "Connect Bank" buttons.

3.31 If the Agency Owner selects "Use existing Bank account" and clicks "Connect Bank," the system displays a list of banks already connected to other brands for selection.

3.32 The Agency Owner selects an existing bank from the list and confirms.

3.33 The system immediately connects the selected bank to the brand and moves the brand under that bank's accordion in the "Connected Bank Accounts" section.

3.34 If the Agency Owner selects "Create a new Bank account" and clicks "Connect Bank," the system launches the Stripe Financial Connections external modal for a new bank connection.

3.35 The Agency Owner completes the new bank connection through Stripe Financial Connections.

3.36 Upon successful connection, the system creates a new bank accordion (if different from existing banks) and places the brand under it.

3.37 If the Agency Owner clicks "Cancel," the modal closes and no changes are made.

### Update Credentials Flow (Shared Mode)

3.38 The Agency Owner clicks the "Update Credentials" button on the connected state screen.

3.39 The system makes the Publishable Key and Secret Key fields editable, allowing the user to enter new Stripe keys.

3.40 The Agency Owner enters the new keys and clicks "Save" to re-validate, or clicks "Cancel" to discard changes.

3.41 The system validates the new keys with the Stripe API and updates the credentials upon successful validation, displaying the updated "✓ Verified & Active" status.

### Switch to Individual Setup Flow

3.42 The Agency Owner clicks the "Switch to Individual Setup" button on the shared mode connected state screen.

3.43 The system displays a modal titled "Where Should These Credentials Be Transferred?" with a warning banner stating "Important: You're About to Change Your Setup" and explaining that by switching to individual setup, each brand will need its own Stripe account.

3.44 The modal lists all agency brands under "Your Connected Credentials" with a checkbox next to each brand, allowing the Agency Owner to select which brands should retain the current Stripe credentials.

3.45 The modal displays an informational section titled "What Happens to Your Current Credentials?" explaining three key points: credentials can be kept for selected brands, new credentials must be set up for other brands, and bank accounts connected to selected brands will also be transferred.

3.46 The Agency Owner selects one or more brands to retain the existing credentials by checking the corresponding checkboxes.

3.47 The Agency Owner clicks "Confirm & Continue" to execute the switch, or "Cancel" to abort and return to the shared configuration screen.

3.48 The system processes the configuration switch: selected brands retain the existing Stripe keys and associated bank accounts; unselected brands are set to "Not Connected" status requiring separate key entry.

3.49 The system triggers an automatic contractor re-onboarding notification for all contractors associated with brands whose Stripe keys have changed as a result of the switch.

3.50 The system redirects the Agency Owner to the Individual Setup screen showing the per-brand accordion layout.

### Individual/Separate Accounts — Setup Flow

3.51 The system displays the "Connect Your Payment Account" page with the heading "Set Up Each Brand Separately" and the subtitle "Its Stripe keys and connect a bank account. You can set them up one at a time."

3.52 The system lists all agency brands as collapsible accordion cards, each displaying the brand logo, brand name, and a connection status badge ("✓ Stripe Connected" in green or "Not Connected" in red).

3.53 The system displays an informational message appropriate to the current bank connection state (see Section 4.8 for detailed logic).

3.54 The system also displays a "Switch to One Account" button on this screen to allow the reverse configuration switch.

3.55 The Agency Owner clicks on a brand accordion card to expand it and view the Stripe key entry fields for that specific brand.

3.56 For a brand that is not connected, the expanded section displays "Stripe Keys" heading, empty Publishable Key and Secret Key input fields, and a "Connect Stripe" button.

3.57 The Agency Owner enters the Publishable Key and Secret Key for the selected brand and clicks "Connect Stripe."

3.58 The system validates the entered keys with the Stripe API for that specific brand.

3.59 If validation succeeds, the system updates the brand's status to "✓ Stripe Connected," displays a "✓ Connected" badge next to the Stripe Keys heading, shows the keys in partially masked read-only fields, and replaces the "Connect Stripe" button with a "Connect Bank Account →" button and a red "Disconnect Stripe" button.

3.60 If validation fails, the system displays an error message indicating invalid keys for that brand and prompts the user to re-enter valid credentials.

### Individual Setup — Bank Account Connection

3.61 The Agency Owner clicks the "Connect Bank Account →" button for a connected brand.

3.62 The system launches the Stripe Financial Connections external modal for bank selection and authentication (no "Use existing / Create new" modal appears in Individual mode).

3.63 Upon successful connection, the system displays the connected bank account details (bank name and last four digits) within the brand's accordion section, along with a trash icon with "Delete" label for removal.

### Individual Setup — Disconnect Stripe

3.64 The Agency Owner clicks the red "Disconnect Stripe" button within a connected brand's expanded accordion section.

3.65 The system displays a confirmation dialog asking the Agency Owner to confirm the disconnection of Stripe for the selected brand.

3.66 If the Agency Owner confirms, the system disconnects the Stripe keys for that specific brand, reverts the brand's status to "Not Connected," and restores the empty key entry fields with the "Connect Stripe" button.

3.67 The system preserves any previously connected bank account for that brand; the bank account is not disconnected when Stripe keys are removed.

3.68 If the Agency Owner cancels, the system closes the confirmation dialog and no changes are made.

### Switch to One Account (Reverse Flow)

3.69 The Agency Owner clicks the "Switch to One Account" button on the Individual Setup screen.

3.70 The system displays a modal similar to the forward switch, asking the Agency Owner which existing credentials they want to use for all brands, or whether they want to enter entirely new Stripe keys.

3.71 The Agency Owner selects the brand whose credentials should be applied to all brands, or chooses to enter new keys.

3.72 For brands that are not selected to retain their bank accounts, the system performs a soft delete of the bank account from the UI display while preserving the data in the backend database.

3.73 The Agency Owner clicks "Confirm & Continue" to execute the reverse switch, or "Cancel" to abort.

3.74 The system processes the configuration change, applies the selected or new Stripe keys to all brands, and redirects the Agency Owner to the shared configuration connected state screen.

3.75 The system triggers an automatic contractor re-onboarding notification for all contractors associated with brands whose Stripe keys have changed during the reverse switch.

### Bank Account Deletion

3.76 The Agency Owner clicks the trash icon with "Delete" label next to a connected bank account (available in both shared and individual modes).

3.77 The system checks whether any payments are currently in processing for that brand.

3.78 If NO payments are in processing, the system displays a confirmation dialog with the following content:

*   **Title:** "Delete Bank Account"  
    
*   **Message:** "Are you sure you want to delete this bank account?"  
    
*   **Buttons:** "Cancel" (secondary) | "Delete" (primary)  
    

3.79 If the Agency Owner clicks "Delete," the system deletes the bank account from the brand and updates the display accordingly (brand moves to "Bank Account Setup" section in shared mode, or shows "Connect Bank Account" button in individual mode).

3.80 If the Agency Owner clicks "Cancel," the system closes the confirmation dialog and no changes are made.

3.81 If payments ARE in processing, the system displays an informational dialog with the following content:

*   **Title:** "Cannot Delete Bank Account"  
    
*   **Message:** "Unable to delete bank account. Payments are currently being processed. Please try again once all payments are complete."  
    
*   **Buttons:** "Close" only  
    

3.82 The Agency Owner clicks "Close" to dismiss the dialog; no changes are made and the bank account remains connected.

### Bank Account Verification (Micro-Deposit Fallback)

3.83 If a bank account cannot be linked instantly through Stripe Financial Connections, the Agency Owner is offered manual verification. Stripe sends a micro-deposit to the bank account and the system displays a verification code field with a "Verify" button. Verification is by bank-statement descriptor code only — there is no OTP.

3.84 The system displays the on-screen instruction: "Check your bank statement for a $0.01 deposit from ACCTVERIFY. The deposit contains a 6-character code." The micro-deposit can take 1-2 business days to appear on the statement.

3.85 The Agency Owner enters the 6-character descriptor code and clicks "Verify."

3.86 If the code is correct, the bank account connects immediately, the system displays "Bank account connected successfully," and the bank moves to the "Connected" state with no pending wait.

3.87 If the code is incorrect, the system displays "Invalid verification code. Please check your bank statement and try again." and the Agency Owner may retry, up to Stripe's attempt limit.

3.88 If Stripe's attempt limit (10 attempts) is reached, the system displays "Bank account verification failed. Please delete this payment method and add it again," disables the "Verify" button, and keeps the Delete (trash icon) enabled so the Agency Owner can delete and re-add the bank account. This applies to both the per-brand (Individual) and unified (One Account for All) verification steps; in the unified step only the failed account(s) are affected while others proceed.

### Disconnect Stripe (Connected Credentials)

3.89 The Agency Owner clicks "Disconnect" in the "Your Connected Credentials" section.

3.90 If Stripe is "Verified & Active" and at least one bank account is connected, the system displays the full "Disconnect Stripe?" confirmation modal listing the consequences (stop all payment processing for connected brands, re-authentication required to reconnect, linked bank accounts disconnected), with "Cancel" and "Yes, disconnect" buttons.

3.91 If the Agency Owner chose manual verification and verification is still pending (no bank fully connected), the system instead displays the simple "Disconnect Stripe?" modal stating that the pending bank verification will not be completed, with "Cancel" and "Yes, disconnect" buttons and no consequence bullets.

3.92 If the Agency Owner clicks "Yes, disconnect," the system removes the Stripe connection (and any linked bank accounts, in the full-modal case) and displays "Stripe account disconnected successfully." If the Agency Owner clicks "Cancel," the modal closes and no changes are made.

## **4\. Functional Logic**

### 4.1 Empty State & Initial Setup

*   When the Agency Owner navigates to Stripe Integration for the first time and no Stripe account has been configured, the system displays the setup mode selection screen if the agency has multiple brands, or the direct key entry screen if the agency has only one brand.  
    
*   If the agency has exactly one brand, the system bypasses the mode selection entirely and presents the "Connect Your Payment Account" screen with the Stripe key entry form for the single brand.  
    
*   If a user who is not the Agency Owner attempts to initiate a contractor payment and no Stripe account is connected, the system displays a popup message informing them that the Stripe account must be connected first by the Agency Owner before any online payment can be processed.  
    
*   The "Need Your Stripe Keys?" helper banner remains visible at the top of the Stripe Integration page across all states (empty, setup, connected) to provide persistent access to the Stripe Dashboard via the "Open Stripe Dashboard" button.  
    
*   The "Open Stripe Dashboard" button opens the Stripe dashboard (https://dashboard.stripe.com) in a new browser tab when clicked.  
    
*   If the Agency Owner navigates to Stripe Integration and the agency has no brands configured at all, the system displays an empty state screen with the message "No Brands Found" and the subtitle "Create at least one brand before connecting Stripe credentials." A "+ Create Brand" button is displayed which redirects the Agency Owner to the Brand Creation module. The Stripe key entry and setup mode selection screens are not accessible until at least one brand exists.

### 4.2 Setup Mode Selection (Multi-Brand Agencies)

*   The setup mode selection screen presents two mutually exclusive card options: "One Account for All" and "Separate Accounts."  
    
*   The "One Account for All" card displays a play icon with the description "Use the same Stripe account across all your brands. Simpler to manage!" to indicate a unified configuration.  
    
*   The "Separate Accounts" card displays a grid icon with the description "Each brand has its own Stripe account. Better for tracking finances separately." to indicate per-brand configuration.  
    
*   When the user clicks on a card, the selected card receives a highlighted border (orange/yellow dashed border) to visually indicate the active selection, while the other card reverts to the default unselected state.  
    
*   Only one card can be selected at a time; clicking one card automatically deselects the other.  
    
*   The "Continue to Next Step →" button at the bottom of the screen remains disabled or triggers an error if no card has been selected.  
    
*   The system persists the selected configuration mode and uses it to determine the subsequent setup flow and UI layout.

### 4.3 One Account for All — Key Entry & Validation

*   The key entry screen displays under the heading "Enter Your Stripe Keys" with a 3-step instructional guide that walks the user through finding their Stripe API keys.  
    
*   Step 1 instructs the user to log in to their Stripe dashboard and click on "Developers" in the top menu.  
    
*   Step 2 instructs the user to click on "API Keys" from the left sidebar within the Stripe Developers section.  
    
*   Step 3 instructs the user to copy both the Publishable Key and Secret Key, with an explicit warning to use "Live keys" and not "Test keys."  
    
*   The Publishable Key input field accepts text input with a placeholder value of "pk\_live\_your\_stripe\_publishable\_key" to guide the user on the expected format.  
    
*   The Secret Key input field accepts text input with the value masked using asterisks to maintain security, with a placeholder of "lk\_live\_your\_stripe\_secret\_key."  
    
*   The system performs client-side format validation to check that the Publishable Key begins with the "pk\_live\_" prefix and the Secret Key begins with the "sk\_live\_" prefix before sending the keys for server-side validation.  
    
*   If the user enters keys with "pk\_test\_" or "sk\_test\_" prefixes, the system displays a warning message informing the user that test keys are not accepted and that live keys are required for production payment processing.  
    
*   Upon clicking "Save," the system sends both keys to the Stripe API for real-time server-side validation to confirm the keys are valid, active, and associated with a legitimate Stripe account.  
    
*   If the Stripe API returns a successful validation response, the system stores the encrypted keys in the database and transitions the UI to the connected state.  
    
*   If the Stripe API returns a validation failure, the system displays an error message and the key entry fields remain editable for the user to correct and re-submit.  
    
*   The "Cancel" button discards any entered key values and returns the user to the previous screen (setup mode selection for multi-brand agencies, or the empty state for single-brand agencies).

### 4.4 One Account for All — Connected State

*   Upon successful key validation, the system displays all agency brands as chips at the top of the "Enter Your Stripe Keys" section, visually confirming that all brands are linked to the single Stripe account.  
    
*   The system displays a "✓ Verified & Active" badge in green next to the "Your Connected Credentials" heading to indicate the active connection status.  
    
*   The Publishable Key is displayed in a read-only field with partial masking (e.g., "pk\_live\_\*\*\*\*\*\*\*\*\*\*\*\*\*6666...") showing only the prefix and last few characters for identification purposes.  
    
*   The Secret Key is displayed in a read-only field with full masking (e.g., "sk\_live\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*") to protect the sensitive key value.  
    
*   A yellow informational banner appears below the brand chips stating "Future Brands Automatically Connected" with the message that any new brands created in the future will automatically be connected to this Stripe account without requiring manual setup.  
    
*   When a new brand is created in the Brands module while the shared configuration is active, the system automatically associates the new brand with the existing Stripe credentials and adds a new chip for that brand on the Stripe Integration screen.  
    
*   The "Update Credentials" button allows the Agency Owner to modify the existing Stripe keys while maintaining the shared configuration mode.  
    
*   The "Switch to Individual Setup" button allows the Agency Owner to transition from the shared configuration to per-brand individual Stripe setups.

### 4.5 Bank Account Connection — Shared Mode

The Bank Accounts area appears below the Stripe credentials section and is only visible after the Stripe keys have been successfully validated and connected. The section structure and informational messages vary based on the current bank connection state.

#### **Section Structure Logic**

**Connection State**

**Sections Displayed**

All brands have the SAME bank connected

Single section: "Connected Bank Accounts"

Brands have DIFFERENT banks connected

Single section: "Connected Bank Accounts"

Mixed state (some connected, some not)

Two sections: "Connected Bank Accounts" + "Bank Account Setup"

NO brands have bank connected

Single section: "Bank Account Setup"

#### **Bank Grouping Display**

*   Connected banks are displayed as collapsible accordion headers showing the bank name and last four digits (e.g., "Bank of America \*\*\*\* 6021").  
    
*   Brands using the same bank are grouped under that bank's accordion.  
    
*   Each brand row within a bank accordion displays the brand logo, brand name, and a trash icon with "Delete" label for removal.  
    
*   When multiple brands use different banks, each bank gets its own accordion with its respective brands listed underneath.

#### **Informational Messages by State**

**Scenario 1: All Brands → SAME Bank Connected**

*   Section: "Connected Bank Accounts" (single section) • Info Message: "Please Note: All your brands are currently using the same bank account for payouts. If you ever need to use different bank accounts, you can switch to Individual Setup."

**Scenario 2: Brands → DIFFERENT Banks Connected**

*   Section: "Connected Bank Accounts" (single section) • Info Message: "Please Note: These are the bank accounts currently connected to your brands. Brands using the same bank account are grouped together."

**Scenario 3: Mixed State (Some Connected, Some Not)**

*   Section 1: "Connected Bank Accounts" • Connected Section Info Message: "Please Note: These are the bank accounts currently connected to your brands. Brands using the same bank account are grouped together."  
    
*   Section 2: "Bank Account Setup" • Setup Section Info Message: "Please Note: To receive payouts, you'll need to connect bank details for these brands. You can use an existing bank account or connect a new one."  
    

**Scenario 4: NO Brands Have Bank Connected Yet**

*   Section: "Bank Account Setup" (single section) • Info Message: "Please Note: To receive payouts, you'll need to connect bank details for each brand. You can use the same bank account for multiple brands or connect different accounts."

#### **First Brand Connection**

*   When connecting a bank account for the very first brand under the shared configuration, clicking the "Connect" button launches the Stripe Financial Connections external interface directly.  
    
*   The Stripe Financial Connections modal displays options including various bank types (OAuth, Non-OAuth, Ownership Accounts, etc.) and a search field for the user to find their specific bank.  
    
*   The bank connection process, including authentication and account verification, is handled entirely by Stripe's external service; the Pixally system does not manage any bank authentication logic.  
    
*   Upon successful bank account connection via Stripe Financial Connections, the system receives the bank name and masked account number from Stripe and creates a bank accordion with the brand listed underneath.  
    
*   After the first successful bank connection, the system displays a popup titled "Complete your bank account setup" with the message "Would you like to use this bank account for all your brands?" and "No" / "Yes" buttons.  
    
*   If the Agency Owner selects "Yes," the system automatically applies the same bank account details to all remaining brands, groups all brands under the same bank accordion, and updates the info message to Scenario 1.  
    
*   If the Agency Owner selects "No," the system retains the bank account connection only for the brand that was just configured. The section structure changes to Scenario 3 (mixed state) with the connected brand in "Connected Bank Accounts" and remaining brands in "Bank Account Setup."

#### **Subsequent Brand Connections (After "No" or New Brands)**

*   For any brand connection after the first (when the user selected "No" in the first popup) or for newly added brands, clicking the "Connect" button displays the "Connect your Bank account" modal.  
    
*   The modal presents two radio button options:  
    
*   **"Use existing Bank account"** (selected by default) — Lists bank accounts already connected to other brands  
    
*   **"Create a new Bank account"** — Opens Stripe Financial Connections for a new bank  
    
*   The modal includes "Cancel" and "Connect Bank" buttons.  
    
*   If the Agency Owner selects "Use existing Bank account," the system displays a list of banks already in use across other brands.  
    
*   Selecting an existing bank and clicking "Connect Bank" immediately connects that bank to the brand without launching Stripe Financial Connections. The brand is moved under that bank's accordion.  
    
*   If the Agency Owner selects "Create a new Bank account" and clicks "Connect Bank," the system launches the Stripe Financial Connections external modal for a new bank connection.  
    
*   Upon successful new bank connection, the system creates a new bank accordion (if different from existing banks) and places the brand under it.  
    
*   Clicking "Cancel" closes the modal with no changes made.

#### **Modal Availability**

*   The "Connect your Bank account" modal (with "Use existing / Create new" options) only appears in "One Account for All" mode when at least one brand already has a bank connected.  
    
*   In "Individual/Separate Accounts" mode, clicking "Connect Bank Account →" launches Stripe Financial Connections directly without the intermediate modal.  
    
*   Each brand can have only one bank account connected at a time; connecting a new bank account replaces the existing one after confirmation.

### 4.6 Update Credentials — Shared Mode

*   Clicking the "Update Credentials" button transitions the Publishable Key and Secret Key fields from read-only to editable mode, allowing the Agency Owner to enter new Stripe API keys.  
    
*   The system pre-clears the existing key values in the editable fields to ensure the user enters fresh credentials rather than modifying partially masked values.  
    
*   Upon clicking "Save," the system re-validates the newly entered keys with the Stripe API using the same validation process as the initial key entry.  
    
*   If the new keys pass validation, the system updates the stored credentials, refreshes the "✓ Verified & Active" status, and returns the fields to read-only mode with the new partially masked values.  
    
*   If the new keys fail validation, the system displays an error message and the fields remain editable for correction.  
    
*   Clicking "Cancel" during the update process discards the changes and restores the previously saved credentials in read-only mode.  
    
*   Updating Stripe credentials does not affect the connected bank accounts; bank accounts remain linked regardless of credential changes.  
    
*   If the updated Stripe keys belong to a different Stripe account than the original, the system triggers a contractor re-onboarding notification for all contractors associated with the agency's brands, as the underlying payment infrastructure has changed.

### 4.7 Switch to Individual Setup

*   The switch modal displays with the title "Where Should These Credentials Be Transferred?" and includes a warning banner titled "Important: You're About to Change Your Setup" explaining the impact of the transition.  
    
*   The modal presents all agency brands in a list with a checkbox next to each, accompanied by the brand logo, brand name, and the bank account information (if connected) for context.  
    
*   Brands that currently have bank accounts connected display the bank name and masked account number next to the brand name within the modal.  
    
*   The Agency Owner selects one or more brands by checking the corresponding checkboxes to indicate which brands should retain the existing shared Stripe credentials after the switch.  
    
*   An informational section at the bottom of the modal titled "What Happens to Your Current Credentials?" explains three rules: (1) the current credentials can be kept for one or more specific brands, (2) new credentials must be set up for the other brands, and (3) bank accounts connected to selected brands will also be transferred.  
    
*   Clicking "Confirm & Continue" executes the switch: selected brands retain their Stripe keys and bank accounts; unselected brands transition to "Not Connected" status.  
    
*   Clicking "Cancel" closes the modal with no changes applied to the existing shared configuration.  
    
*   After the switch is confirmed, the system transitions the UI to the Individual Setup view, displaying the per-brand accordion layout with the appropriate connection statuses.  
    
*   The system triggers automatic contractor re-onboarding notifications specifically for contractors associated with brands whose Stripe keys have changed (i.e., brands that were not selected to retain the existing credentials).  
    
*   Contractors associated with brands that retained the existing credentials are not affected and do not receive re-onboarding notifications.  
    
*   The switch operation is blocked and cannot be initiated if any contractor payments are currently in the processing stage to prevent transactional integrity issues.  
    
*   If the Agency Owner attempts to switch while payments are processing, the system displays an error message explaining that the configuration cannot be changed until all in-progress payments are completed.

### 4.8 Individual/Separate Accounts — Setup & Management

*   The Individual Setup screen displays under the heading "Set Up Each Brand Separately" with the subtitle "Its Stripe keys and connect a bank account. You can set them up one at a time."  
    
*   Each agency brand is displayed as a collapsible accordion card with the brand logo, brand name, and a connection status badge.  
    
*   Connected brands display a "✓ Stripe Connected" badge in green, while unconnected brands display a "Not Connected" badge in red.  
    
*   Accordion cards are collapsed by default; clicking on a card expands it to reveal the Stripe key fields and bank account section for that specific brand.  
    
*   Only one accordion card can be expanded at a time; expanding a new card collapses the previously expanded card.

#### **Bank Account Display in Individual Mode**

*   In Individual mode, bank account details are displayed INSIDE each brand's accordion (not as a separate grouped section).  
    
*   Each brand's expanded accordion shows its own Stripe credentials and bank account status independently.  
    
*   If the brand has a bank connected, the bank name and last four digits are displayed with a trash icon and "Delete" label.  
    
*   If the brand does not have a bank connected, a "Connect Bank Account →" button is displayed.

#### **Informational Messages by State**

**Scenario 5: All Brands Have Bank Connected**

*   Info Message (displayed above the brand accordions): "Please Note: Each brand has its own Stripe account and bank details for independent payout processing."

**Scenario 6: Mixed State (Some Connected, Some Not)**

*   Info Message: "Please Note: Each brand requires its own bank account for payouts. Connect bank details within each brand's settings below."

**Scenario 7: NO Brands Have Bank Connected Yet**

*   Info Message: "Please Note: Each brand requires its own bank account for payouts. Connect bank details within each brand's settings below."

#### **Key Entry & Validation**

*   For an unconnected brand, the expanded section displays the "Stripe Keys" heading, empty Publishable Key and Secret Key input fields with placeholder text, and a "Connect Stripe" button.  
    
*   The key validation process for individual brands follows the same logic as the shared mode: client-side prefix validation followed by server-side Stripe API validation.  
    
*   Upon successful validation for an individual brand, the system updates that brand's accordion to display: "✓ Connected" badge, partially masked Publishable Key, fully masked Secret Key, a "Connect Bank Account →" button, and a red "Disconnect Stripe" button.

#### **Bank Connection**

*   The "Connect Bank Account →" button launches the Stripe Financial Connections modal directly for that specific brand (no "Use existing / Create new" modal in Individual mode).  
    
*   Upon successful bank connection, the bank details (bank name and last four digits) appear within the brand's accordion section with a trash icon and "Delete" label for removal.

#### **Disconnect Stripe**

*   The "Disconnect Stripe" button displays a confirmation dialog before disconnecting the Stripe keys for the selected brand.  
    
*   Upon confirmed disconnection, the brand's status reverts to "Not Connected," the Stripe keys are removed, and the empty key entry fields with the "Connect Stripe" button are restored.  
    
*   Disconnecting Stripe keys for a brand does NOT disconnect or remove the bank account that was previously connected for that brand; the bank account data is preserved.  
    
*   A "Switch to One Account" button is displayed on the Individual Setup screen to allow the Agency Owner to reverse the configuration back to shared mode.

### 4.9 Switch to One Account (Reverse Flow)

*   The reverse switch modal functions similarly to the forward switch modal, allowing the Agency Owner to select which existing brand credentials should be applied across all brands.  
    
*   The modal presents all brands with their current connection status and credentials, allowing the Agency Owner to choose one set of existing credentials to use as the shared Stripe keys.  
    
*   Alternatively, the Agency Owner can opt to enter entirely new Stripe keys for the shared configuration rather than using any existing brand's credentials.  
    
*   For brands whose bank accounts are not selected to be retained during the reverse switch, the system performs a soft delete of the bank account from the UI display while preserving the bank account data in the backend database for potential future restoration.  
    
*   Brands that require new bank account configuration after the reverse switch display the standard "Connect" button in the Bank Accounts section.  
    
*   The system triggers automatic contractor re-onboarding notifications for contractors associated with brands whose Stripe keys changed during the reverse switch.  
    
*   The reverse switch is also blocked if any contractor payments are currently in the processing stage, following the same transactional integrity rule as the forward switch.  
    
*   After confirmation, the system redirects the Agency Owner to the shared configuration connected state screen with all brands linked to the selected or newly entered Stripe credentials.

### 4.10 Bank Account Deletion

*   Clicking the trash icon with "Delete" label next to a connected bank account initiates the deletion process.  
    
*   The system first checks whether any payments are currently in processing for the brand associated with the bank account.  
    

**When NO Payments Are in Processing (Deletion Allowed):**

*   The system displays a confirmation dialog with the following content:  
    
*   **Title:** "Delete Bank Account"  
    
*   **Message:** "Are you sure you want to delete this bank account?"  
    
*   **Buttons:** "Cancel" (secondary) | "Delete" (primary)  
    
*   Clicking "Delete" removes the bank account association for that specific brand and updates the UI accordingly:  
    
*   In Shared mode: Brand moves from "Connected Bank Accounts" section to "Bank Account Setup" section (if applicable), and the section structure/info messages update based on new state  
    
*   In Individual mode: Brand's accordion updates to show "Connect Bank Account →" button  
    
*   Clicking "Cancel" closes the dialog and retains the bank account connection with no changes.  
    
*   Note: Unpaid invoices do NOT block bank account deletion. The confirmation dialog is shown regardless of whether the brand has unpaid invoices.  
    

**When Payments ARE in Processing (Deletion Blocked):**

*   The system displays an informational dialog with the following content:  
    
*   **Title:** "Cannot Delete Bank Account"  
    
*   **Message:** "Unable to delete bank account. Payments are currently being processed. Please try again once all payments are complete."  
    
*   **Buttons:** "Close" only  
    
*   Clicking "Close" dismisses the dialog; no changes are made and the bank account remains connected.  
    
*   The user must wait until all in-progress payments are completed before attempting to delete the bank account again.  
    

**Post-Deletion Behavior:**

*   After successful deletion, the brand returns to a Stripe-connected state without bank details.  
    
*   The appropriate section/accordion displays the "Connect" button allowing the Agency Owner to link a new bank account.  
    
*   If the brand has scheduled (but not yet processing) contractor payments, those payments will be blocked until a new bank account is connected.

### 4.11 Single-Brand Agency Flow

*   Agencies with exactly one brand configured in the system bypass the setup mode selection screen entirely upon navigating to Stripe Integration.  
    
*   The system directly presents the "Connect Your Payment Account" key entry screen for the single brand, following the same validation and connection flow as the shared mode.  
    
*   After successful Stripe key validation, the Bank Accounts section displays only the single brand with a "Connect" button for bank account linking.  
    
*   The info message displayed is: "Please Note: To receive payouts, you'll need to connect bank details for each brand. You can use the same bank account for multiple brands or connect different accounts."  
    
*   The first-connection bank account popup ("Would you like to use this bank account for all your brands?") does not appear for single-brand agencies since there is only one brand.  
    
*   If a single-brand agency later adds a second brand, the system dynamically updates the Stripe Integration screen to reflect the multi-brand configuration, and the new brand automatically inherits the existing Stripe credentials.

### 4.12 Contractor Re-Onboarding Trigger

*   When an agency switches from shared to individual Stripe configuration or from individual to shared configuration, the system identifies all contractors associated with brands whose Stripe keys have changed.  
    
*   An automatic system notification is sent to each affected contractor informing them that they need to complete the Stripe re-onboarding process for the changed brand(s).  
    
*   Contractors associated with brands that retained their existing Stripe keys during the switch are not notified and do not need to re-onboard.  
    
*   The re-onboarding requirement ensures that contractor payment flows are correctly aligned with the updated Stripe account credentials for each brand.

### 4.13 Payment Processing Restrictions

*   The system prevents the Agency Owner from switching between shared and individual Stripe configurations (in either direction) if any contractor payments are currently in the "processing" stage.  
    
*   Before displaying the switch modal, the system checks for any active processing payments across all agency brands.  
    
*   If processing payments are detected, the system displays an error message stating that the configuration cannot be changed until all in-progress payments have been completed or cancelled.  
    
*   This restriction enforces transactional integrity and prevents payment failures or misrouting that could occur if Stripe credentials change mid-transaction.  
    
*   If a contractor has not connected their Stripe account for onboarding, the agency is unable to process online payments to that contractor; the system displays an appropriate notification when a payment is attempted.

### 4.14 Dynamic Brand Syncing

*   When a new brand is created in the Brands module while the shared Stripe configuration is active, the new brand is automatically associated with the existing shared Stripe credentials without requiring any manual action from the Agency Owner.  
    
*   The new brand appears as an additional chip on the Stripe Integration connected state screen and is listed in the "Bank Account Setup" section with a "Connect" button for bank account setup.  
    
*   When connecting a bank for a newly added brand in shared mode, the "Connect your Bank account" modal appears (with "Use existing / Create new" options) since at least one brand already has a bank connected.  
    
*   When a new brand is created while the individual Stripe configuration is active, the new brand appears as a new accordion card with "Not Connected" status, requiring separate Stripe key entry.  
    
*   When a brand is removed or deactivated from the Brands module, the system updates the Stripe Integration screen to remove the corresponding brand from the brand list, chips, or accordion cards.  
    
*   All dynamic brand additions and removals are reflected in real-time on the Stripe Integration screen without requiring a page refresh.

### 4.15 Helper Banner & Instructions

*   The "Need Your Stripe Keys?" helper banner is displayed persistently across all states of the Stripe Integration page (empty, setup mode selection, key entry, connected state, individual setup).  
    
*   The banner includes a warning icon, the title text, descriptive text ("Don't worry! We'll show you exactly where to find them. It's simple and takes less than 2 minutes."), and the "Open Stripe Dashboard" button.  
    
*   The "Open Stripe Dashboard" button opens the Stripe dashboard at https://dashboard.stripe.com in a new browser tab using target="\_blank."  
    
*   The 3-step instruction guide within the key entry section provides visual step numbers (circled 1, 2, 3) with clear instructions for locating API keys within the Stripe dashboard.

### 4.16 Bank Account Verification — Micro-Deposit / Descriptor Code

*   This logic applies to bank account verification in BOTH configuration modes: the unified "One Account for All" step and the per-brand "Individual/Separate Accounts" step.  
    
*   Default behavior: Bank accounts typically connect instantly via Stripe Financial Connections. When a bank connects instantly, no manual verification step is required and the account moves straight to the "Connected" state.  
    
*   There is NO OTP-based verification. When manual verification is needed, it is performed exclusively via the bank-statement descriptor code (micro-deposit), not a one-time passcode.  
    
*   Manual fallback: If an account cannot be connected instantly and the user opts for manual verification, Stripe sends a micro-deposit to the bank account and the system displays a verification code field with a "Verify" button.  
    
*   On-screen instruction: "Check your bank statement for a $0.01 deposit from ACCTVERIFY. The deposit contains a 6-character code."  
    
*   The Agency Owner enters the 6-character descriptor code and clicks "Verify."  
    
*   On successful code entry, the bank account connects immediately — there is no extended pending wait or "under verification" hold. The bank moves to the "Connected" state and the system displays "Bank account connected successfully."  
    
*   Timing note: Micro-deposits can take 1-2 business days to appear on the customer's bank statement; the descriptor code can only be entered once the deposit is visible.  
    
*   Per-brand (Individual) step: Each brand completes its own micro-deposit verification independently within its accordion; the verification code field and "Verify" button appear inline next to that brand's bank entry.  
    
*   Unified (One Account for All) step: Accounts verify independently. Only the account(s) that fail verification display the disabled "Verify" button and the failure message; all other accounts proceed to "Connected" normally.

### 4.17 Verification Attempt Limit (Stripe-Handled)

*   The verification attempt limit is enforced by Stripe, not by the Pixally platform; it is documented here for awareness.  
    
*   The user is allowed up to 10 attempts to enter the descriptor code for micro-deposit verification.  
    
*   When the attempt limit is reached, Stripe blocks further verification for that bank account, and the account cannot be reused.  
    
*   On limit reached, the system displays Stripe's failure message: "Bank account verification failed. Please delete this payment method and add it again."  
    
*   Resulting UI behavior: the "Verify" button is DISABLED, while the Delete (trash icon) action remains ENABLED, giving the user a delete-and-re-add path.  
    
*   The user deletes the blocked bank account and adds it again; re-adding repeats the same micro-deposit verification flow described in Section 4.16. There is no separate reverification journey.

### 4.18 Reverification

*   There is no separate reverification flow. If a bank account's verification is incomplete, the user completes it through the same micro-deposit / descriptor-code process described in Section 4.16.  
    
*   No distinct reverification status, screen, or UI is required; the standard verification code field is reused.

### 4.19 Post-Verification Pending State

*   Bank accounts connect instantly on confirmation; there is no post-verification pending state, so no "under verification" or wait-time message is displayed at any point.

### 4.20 Disconnect Stripe — Confirmation Modals

*   When the Agency Owner clicks "Disconnect" in the "Your Connected Credentials" section, the system displays one of two confirmation modals depending on the current connection/verification state.

#### **Full Modal — Stripe Verified & Active**

*   Triggered when Stripe is "Verified & Active" and at least one bank account is actively connected.  
    
*   Title: "Disconnect Stripe?"  
    
*   Description: "Are you sure you want to disconnect your Stripe account? This will:" followed by three consequence points: (1) Stop all payment processing for connected brands; (2) Require re-authentication to reconnect; (3) Disconnect linked bank accounts.  
    
*   CTAs: "Cancel" (secondary) | "Yes, disconnect" (primary/destructive).  
    
*   On confirm: Stripe is disconnected, all linked bank accounts are removed, reconnection requires full re-authentication, and the system displays "Stripe account disconnected successfully."  
    
*   On "Cancel": the modal closes and no changes are made.

#### **Simple Modal — Manual Verification Pending**

*   Triggered when the user chose manual (micro-deposit) verification, the bank verification is not yet complete (bank not fully connected), and the user clicks "Disconnect" before verifying.  
    
*   Because no bank account is fully connected, the payment-processing and linked-bank consequence points are intentionally omitted.  
    
*   Title: "Disconnect Stripe?"  
    
*   Description: "Are you sure you want to disconnect? Your bank verification is still pending and will not be completed."  
    
*   CTAs: "Cancel" (secondary) | "Yes, disconnect" (primary/destructive).  
    
*   On confirm: the pending verification is abandoned, the Stripe connection is removed, and the system displays "Stripe account disconnected successfully."  
    
*   On "Cancel": the modal closes and no changes are made.

#### **Modal Selection in the Unified Step (Mixed State)**

*   If the Agency Owner clicks "Disconnect" during a unified bank-verification step in which some accounts are verified/connected and others are still pending, the system displays the FULL modal, because at least one bank account is actively connected and the disconnect therefore carries the full payment-processing and linked-account consequences.  
    
*   Note: This account-level "Disconnect" (in the Connected Credentials section) is distinct from the per-brand "Disconnect Stripe" action in Section 4.8, which removes only a single brand's Stripe keys and preserves that brand's bank account. The account-level disconnect removes the Stripe connection and all linked bank accounts.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Section**

Publishable Key

Text Input

Required; Must start with "pk\_live\_" prefix; Cannot start with "pk\_test\_"; Maximum 255 characters; No whitespace allowed; Validated against Stripe API

Key Entry (Shared & Individual)

Secret Key

Text Input (Masked)

Required; Must start with "sk\_live\_" prefix; Cannot start with "sk\_test\_"; Maximum 255 characters; No whitespace allowed; Validated against Stripe API

Key Entry (Shared & Individual)

Configuration Mode

Card Selection (Radio)

Required for multi-brand agencies; Exactly one option must be selected before proceeding; Options: "One Account for All" or "Separate Accounts"

Setup Mode Selection

Brand Checkbox (Switch Modal)

Checkbox

Optional; At least one brand may be selected; Multiple selections allowed

Switch Configuration Modal

Bank Account Selection

Radio Button

Required when "Connect your Bank account" modal is shown; Options: "Use existing Bank account" or "Create a new Bank account"; Default: "Use existing Bank account"

Bank Connection Modal (Shared Mode Only)

Bank Account

External (Stripe Financial Connections)

Managed entirely by Stripe; One bank account per brand; Connection requires successful Stripe Financial Connections authentication

Bank Accounts Section

Bank Verification Code

Text Input

Required for manual (micro-deposit) verification; 6 characters; Validated by Stripe; Up to 10 attempts (Stripe-enforced)

Bank Account Verification (Shared & Individual)

## **6\. Success Message Handling**

**Action**

**Success Message**

**Trigger Condition**

**Post-Success Behaviour**

Stripe keys validated (Shared Mode)

"Stripe account connected successfully. All brands are now linked to this account."

Stripe API returns successful validation for entered Publishable Key and Secret Key

UI transitions to connected state; brand chips displayed; "✓ Verified & Active" badge shown

Stripe keys validated (Individual Mode)

"Stripe account connected successfully for \[Brand Name\]."

Stripe API returns successful validation for a specific brand's keys

Brand accordion updates to connected state; "✓ Connected" badge shown

Stripe credentials updated

"Stripe credentials have been updated successfully."

Agency Owner updates existing keys and Stripe API validates the new keys

UI refreshes with new masked key values; "✓ Verified & Active" status retained

Bank account connected

"Bank account connected successfully for \[Brand Name\]."

Stripe Financial Connections returns successful bank linking

Brand moves to "Connected Bank Accounts" section under appropriate bank accordion; info message updates

Bank account connected via existing

"Bank account connected successfully for \[Brand Name\]."

Agency Owner selects existing bank from "Connect your Bank account" modal

Brand moves under selected bank's accordion; section structure updates if needed

Bank account applied to all brands

"Bank account has been applied to all brands successfully."

Agency Owner selects "Yes" when prompted to use the same bank for all brands

All brands grouped under single bank accordion; info message updates to Scenario 1

Configuration switched to Individual

"Configuration switched to individual setup successfully. Please set up Stripe keys for brands marked as 'Not Connected'."

Agency Owner confirms the switch from shared to individual via the modal

UI transitions to individual setup accordion view

Configuration switched to One Account

"Configuration switched to one account for all brands successfully."

Agency Owner confirms the reverse switch from individual to shared via the modal

UI transitions to shared connected state view

Stripe disconnected (Individual Mode)

"Stripe has been disconnected for \[Brand Name\]."

Agency Owner confirms disconnection of a specific brand's Stripe keys

Brand reverts to "Not Connected" status with empty key entry fields

Bank account deleted

"Bank account has been deleted for \[Brand Name\]."

Agency Owner confirms deletion of a bank account via the confirmation dialog

Brand moves to "Bank Account Setup" section (shared) or shows "Connect" button (individual); section structure/info messages update

Bank account connected (micro-deposit verified)

"Bank account connected successfully"

Agency Owner enters the correct micro-deposit descriptor code and clicks "Verify," or the bank connects instantly via Stripe Financial Connections

Toast displayed for 3 seconds; bank account moves to the "Connected" state; applies to both the verified and instant-connect cases

Stripe account disconnected

"Stripe account disconnected successfully"

Agency Owner confirms disconnection via the "Yes, disconnect" button in either the full (Verified & Active) or simple (verification pending) modal

Toast displayed for 3 seconds; Stripe connection removed; linked bank accounts removed in the full-modal case

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger Condition**

**Required Action / System Response**

No configuration mode selected

"Please select a configuration option before proceeding."

Agency Owner clicks "Continue to Next Step" without selecting "One Account for All" or "Separate Accounts"

System highlights the selection area; user must select an option

Empty Publishable Key

"Publishable Key is required. Please enter your Stripe Publishable Key."

Agency Owner clicks "Save" or "Connect Stripe" with the Publishable Key field empty

System highlights the Publishable Key field; user must enter a valid key

Empty Secret Key

"Secret Key is required. Please enter your Stripe Secret Key."

Agency Owner clicks "Save" or "Connect Stripe" with the Secret Key field empty

System highlights the Secret Key field; user must enter a valid key

Invalid key prefix — Test keys entered

"Test keys are not accepted. Please enter your Live Stripe keys (starting with pk\_live\_ and sk\_live\_)."

System detects that the entered Publishable Key starts with "pk\_test\_" or the Secret Key starts with "sk\_test\_"

Client-side validation prevents submission; user must enter live keys

Invalid key format

"The entered key format is invalid. Please verify your Stripe API key and try again."

System detects that the key does not match expected Stripe key format patterns

Client-side validation prevents submission; user must correct the key format

Stripe API validation failure

"The entered Stripe keys are invalid or could not be verified. Please check your keys and try again."

Stripe API returns an authentication or validation error for the submitted keys

System keeps fields editable; user must re-enter valid keys

Stripe API connection timeout

"Unable to connect to Stripe at this time. Please check your internet connection and try again."

System cannot reach the Stripe API due to network or service unavailability

System retains entered values; user may retry after connectivity is restored

Switch blocked — payments processing

"Configuration cannot be changed while payments are being processed. Please wait until all in-progress payments are completed."

Agency Owner attempts to switch configuration (either direction) while contractor payments are in "processing" stage

System blocks the switch modal from opening; no changes permitted

Bank account deletion blocked — payments processing

(Displayed in dialog) "Unable to delete bank account. Payments are currently being processed. Please try again once all payments are complete."

Agency Owner attempts to delete a bank account while payments are in "processing" stage for that brand

System displays informational dialog with "Close" button; no deletion permitted

Payment blocked — contractor not onboarded

"Payment cannot be processed. \[Contractor Name\] has not completed Stripe onboarding for \[Brand Name\]. Please contact the contractor to complete their setup."

Agency attempts to process a payment to a contractor who has not completed Stripe onboarding

System blocks the payment initiation; agency must wait for contractor onboarding

Payment blocked — no Stripe connected

"Please connect your Stripe account first to initiate contractor payments."

Any user attempts to process a contractor payment when no Stripe account is connected for the brand

System displays popup message; user must navigate to Stripe Integration to connect

Payment blocked — no bank account

"Bank account is not connected for \[Brand Name\]. Please connect a bank account before processing payments."

Agency attempts to process a payment for a brand that has Stripe keys but no bank account connected

System blocks payment; user must connect bank account

Bank connection failed

"Bank account connection was unsuccessful. Please try again or select a different bank."

Stripe Financial Connections returns a failure response during bank account linking

System retains current state; user may retry the connection

Duplicate Stripe key across brands

"These Stripe keys are already in use by \[Brand Name\]. Each brand requires unique Stripe credentials in Individual Setup mode."

Agency Owner enters Stripe keys for a brand in individual mode that match keys already assigned to another brand

System prevents saving; user must enter unique keys for each brand

Bank verification attempt limit reached

"Bank account verification failed. Please delete this payment method and add it again."

Stripe blocks the bank account after the 10-attempt descriptor-code limit is reached

System disables the "Verify" button and keeps Delete (trash icon) enabled; user must delete the payment method and add it again

Invalid bank verification code

"Invalid verification code. Please check your bank statement and try again."

Agency Owner enters a descriptor code that does not match the micro-deposit code

System keeps the code field editable for retry within Stripe's attempt limit

## **8\. Edge Cases**

**Edge Case**

**Scenario Description**

**Expected System Behaviour**

Single brand becomes multi-brand

Agency has one brand with Stripe connected, then creates a second brand in the Brands module

System dynamically updates Stripe Integration to reflect multi-brand status; new brand auto-inherits existing Stripe keys; new brand appears in "Bank Account Setup" section with "Connect" button

New brand added — bank connection

Agency has multiple brands with banks connected via "One Account for All," then adds a new brand

New brand shows in "Bank Account Setup" section; clicking "Connect" displays "Connect your Bank account" modal with "Use existing / Create new" options; section structure changes to mixed state

All brands disconnected in Individual mode

Agency Owner disconnects Stripe for every brand in individual setup mode

System displays all brands as "Not Connected"; the "Switch to One Account" button remains available; no payments can be processed

Brand deleted with active Stripe connection

A brand that has Stripe keys and a bank account connected is deleted from the Brands module

System removes the brand from the Stripe Integration screen; associated Stripe and bank data is archived; no impact on other brands; section structure/info messages update accordingly

Concurrent session — configuration change

Agency Owner has Stripe Integration open in two browser tabs and makes changes in one

System applies the last saved change; the other tab should reflect updated state upon refresh or display a stale data warning

Network failure during key validation

Internet connection drops while the system is validating Stripe keys with the API

System displays a timeout error message; entered key values are preserved in the fields; user can retry when connectivity is restored

Network failure during bank connection

Internet connection drops while the Stripe Financial Connections modal is active

Stripe's external modal handles the error; upon failure, the system retains the previous bank connection state; user can retry

Switch attempted with zero brands selected

Agency Owner opens the switch-to-individual modal but does not select any brand to retain credentials and clicks "Confirm & Continue"

System allows the switch; all brands transition to "Not Connected" status; Agency Owner must enter new keys for every brand

Rapid repeated key validation

Agency Owner clicks "Save" or "Connect Stripe" multiple times in quick succession

System disables the button after the first click to prevent duplicate API calls; button re-enables after the validation response is received

Stripe account deactivated externally

The connected Stripe account is deactivated or suspended directly on the Stripe dashboard

System should detect the invalid status on the next API interaction and display a warning to the Agency Owner to reconnect with valid credentials

Keys changed via Update Credentials to a different Stripe account

Agency Owner uses "Update Credentials" to enter keys from an entirely different Stripe account

System validates new keys, updates credentials, and triggers contractor re-onboarding notifications since the underlying Stripe account has changed

Bank account deletion attempted while payment is processing

Agency Owner attempts to delete a bank account for a brand that has payments currently in "processing" stage

System displays "Cannot Delete Bank Account" dialog with explanation that payments are processing; deletion is blocked until payments complete

Bank account deletion with unpaid invoices

Agency Owner attempts to delete a bank account for a brand that has unpaid invoices (but no processing payments)

System allows deletion; displays standard confirmation dialog "Are you sure you want to delete this bank account?" with "Cancel" / "Delete" buttons

Bank account deleted while payment is scheduled

Agency Owner deletes a bank account for a brand that has scheduled (but not yet processing) contractor payments

System displays confirmation dialog; upon confirmation, the bank is deleted and scheduled payments are blocked until a new bank is connected

Soft-deleted bank account during reverse switch

Bank account was soft-deleted from the UI during an Individual-to-Shared switch but preserved in the backend

Data remains in the backend database; if the user switches back to individual setup later, the bank account data is not automatically restored to the UI — the user must reconnect manually

Agency Owner role transferred

Agency ownership is transferred to a new user while Stripe is configured

New Agency Owner inherits full access to the Stripe Integration module and can view/modify all existing configurations

No brands configured

Agency Owner navigates to Stripe Integration before creating any brand

System displays the "No Brands Found" empty state with a "+ Create Brand" button; all Stripe configuration options are hidden until at least one brand is created; clicking the button redirects to the Brand Creation module

User selects "Use existing" with multiple banks available

Multiple brands have different banks connected; user connecting new brand selects "Use existing Bank account"

System displays list of all unique banks connected across brands; user can select any one; selected brand moves under chosen bank's accordion

User cancels bank connection modal

User clicks "Cancel" on "Connect your Bank account" modal

Modal closes; no changes made; brand retains "Connect" button in current section

Last connected brand's bank deleted

Only one brand had bank connected; user deletes that bank

System transitions from Scenario 3 (mixed) to Scenario 4 (none connected); section changes from two sections to single "Bank Account Setup" section

All brands get bank connected

User connects banks for all remaining brands in "Bank Account Setup"

"Bank Account Setup" section disappears; only "Connected Bank Accounts" section remains; info message updates to Scenario 1 or 2 depending on bank variety

Bank verification attempt limit reached

Agency Owner exhausts the 10 descriptor-code attempts for a bank account

Stripe blocks the account (cannot be reused); system shows "Bank account verification failed. Please delete this payment method and add it again," disables "Verify," and keeps Delete enabled for a delete-and-re-add path

Disconnect during unified step with mixed verification states

In the unified (One Account for All) step, some bank accounts are verified/connected and others are still pending when the Agency Owner clicks "Disconnect"

System displays the FULL disconnect modal (with consequence bullets), because at least one bank account is actively connected

## **9\. Acceptance Criteria**

*   The Stripe Integration module must be accessible exclusively to the Agency Owner role; no other role should be able to view, access, or modify any Stripe settings.  
    
*   Agencies with a single brand must bypass the setup mode selection screen and be directed to the Stripe key entry screen immediately.  
    
*   Agencies with multiple brands must be presented with the "One Account for All" and "Separate Accounts" selection options before proceeding to key entry.  
    
*   Stripe Publishable Key and Secret Key fields must enforce client-side format validation (prefix check for "pk\_live\_" and "sk\_live\_") before server-side API validation.  
    
*   Keys with "pk\_test\_" or "sk\_test\_" prefixes must be rejected with an appropriate error message informing the user to use live keys.  
    
*   Successfully validated Stripe keys must display the "✓ Verified & Active" status, and key values must be masked appropriately in read-only mode.  
    
*   In shared mode, all existing brands must be automatically linked to the validated Stripe account, and future brands must automatically inherit the same credentials.  
    
*   The first bank account connection in shared mode must trigger a popup ("Would you like to use this bank account for all your brands?") with "No" / "Yes" buttons.  
    
*   Subsequent bank connections in shared mode (after "No" or for new brands) must display the "Connect your Bank account" modal with "Use existing Bank account" and "Create a new Bank account" options.  
    
*   Selecting "Use existing Bank account" must immediately connect the selected bank without launching Stripe Financial Connections.  
    
*   Selecting "Create a new Bank account" must launch Stripe Financial Connections for a new bank setup.  
    
*   The "Connect your Bank account" modal must NOT appear in Individual/Separate Accounts mode; Stripe Financial Connections should launch directly.  
    
*   Bank account connection must be handled entirely by Stripe Financial Connections, with the system receiving and displaying bank name and last four account digits upon success.  
    
*   Each brand must support exactly one bank account at a time.  
    
*   Connected bank accounts must display a trash icon with "Delete" label for removal.

### Bank Account Section Structure (Shared Mode)

*   When all brands have the SAME bank connected, display single "Connected Bank Accounts" section with appropriate info message.  
    
*   When brands have DIFFERENT banks connected, display single "Connected Bank Accounts" section with banks grouped as accordions.  
    
*   When some brands connected and some not (mixed state), display TWO sections: "Connected Bank Accounts" and "Bank Account Setup" with respective info messages.  
    
*   When NO brands have bank connected, display single "Bank Account Setup" section with appropriate info message.  
    
*   Info messages must update dynamically when connection state changes.

### Bank Account Display (Individual Mode)

*   Bank details must appear INSIDE each brand's accordion (not as a separate grouped section).  
    
*   Info message must display above brand accordions based on current connection state.  
    
*   When all brands connected: "Please Note: Each brand has its own Stripe account and bank details for independent payout processing."  
    
*   When mixed or none connected: "Please Note: Each brand requires its own bank account for payouts. Connect bank details within each brand's settings below."

### General Acceptance Criteria (Continued)

*   The "Update Credentials" flow must allow re-entry and re-validation of Stripe keys without changing the configuration mode.  
    
*   The "Switch to Individual Setup" flow must display a modal allowing brand-level credential transfer selection with clear informational messaging.  
    
*   The "Switch to One Account" reverse flow must be available on the Individual Setup screen and function symmetrically to the forward switch.  
    
*   Configuration switches (both directions) must be blocked if any contractor payments are in the "processing" stage, with a clear error message displayed.  
    
*   Switching configurations must trigger automatic contractor re-onboarding notifications only for contractors associated with brands whose Stripe keys have changed.  
    
*   Disconnecting Stripe in individual mode must revert the brand to "Not Connected" status while preserving the connected bank account.  
    
*   Bank account deletion must display a confirmation dialog titled "Delete Bank Account" with "Cancel" / "Delete" buttons when no payments are processing.  
    
*   Bank account deletion must be blocked with an informational dialog titled "Cannot Delete Bank Account" when payments are in processing, showing only a "Close" button.  
    
*   Unpaid invoices must NOT block bank account deletion; only payments in processing stage block deletion.  
    
*   After successful bank account deletion, the brand must move to appropriate section (shared) or show "Connect" button (individual).  
    
*   All dynamic brand additions and removals from the Brands module must be reflected on the Stripe Integration screen in real-time.  
    
*   All success, error, and warning messages must be displayed as defined in the Success Message Handling and Error Message Handling sections.  
    
*   The helper banner with "Open Stripe Dashboard" must persist across all Stripe Integration states.  
    
*   If the agency has no brands configured, the Stripe Integration page must display the "No Brands Found" empty state with a "+ Create Brand" button that redirects to the Brand Creation module; no Stripe setup options should be visible in this state.  
    
*   Bank account verification must use the micro-deposit / descriptor-code method only (no OTP). The on-screen instruction must reference the $0.01 ACCTVERIFY deposit and the 6-character code, and a correct code must connect the bank immediately with no pending wait.  
    
*   The system must not display any post-verification pending or "under verification / 24-48 hours" message; bank accounts connect instantly on confirmation.  
    
*   On reaching Stripe's verification attempt limit (10 attempts), the "Verify" button must be disabled while Delete (trash icon) remains enabled, supporting a delete-and-re-add path. Incomplete verification must be completed through the same micro-deposit process (no separate reverification flow).  
    
*   The Disconnect action in the Connected Credentials section must show the full modal (with consequence bullets) when Stripe is Verified & Active or at least one bank is connected, and the simple modal (no consequence bullets) when manual verification is still pending.

In a unified step with mixed states, the full modal must be shown.  
    
*   These behaviors must apply to both the per-brand (Individual) and unified (One Account for All) verification steps.

## **10\. Manual Test Cases**

The comprehensive test cases for the Stripe Integration module are provided in a separate Excel file for upload to the project management system.

**File:** \[Stripe\_Integration\_Test\_Cases.xlsx\]

## **11\. Dependencies**

**Module / System**

**Dependency Type**

**Description**

**Impact if Unavailable**

Stripe API

External Service

Real-time validation of Publishable Key and Secret Key; authentication and account verification

Stripe keys cannot be validated; connection cannot be established; all payment processing is blocked

Stripe Financial Connections

External Service

Bank account selection, authentication, and linking for payout processing

Bank accounts cannot be connected; payments cannot be processed even with valid Stripe keys

Brands Module

Internal Module

Provides the list of agency brands, brand logos, and brand names displayed on the Stripe Integration screen; triggers dynamic updates when brands are added or removed

Brand list cannot be populated; setup mode selection cannot determine single vs. multi-brand; new brands cannot auto-inherit credentials. If no brands exist, Stripe Integration is completely inaccessible beyond the empty state screen.

Contractor Payment Module

Internal Module

Relies on Stripe Integration configuration to process contractor payments; checks for active Stripe and bank account connections before initiating payments

Payments cannot be processed if Stripe is not connected; payment module must validate connection status before each transaction

Accepted Payment Methods Module

Internal Module

Works alongside Stripe Integration to define which payment methods are available for contractor payments; may share Stripe credential dependencies

Payment method configuration may be incomplete without Stripe Integration; invoice generation may be affected

Authentication Service

Internal Service

Validates that the current user is the Agency Owner before granting access to the Stripe Integration module

Unauthorized users may access sensitive financial configurations if role validation fails

Notification System

Internal Service

Sends automatic contractor re-onboarding notifications when Stripe configurations change; sends payment-related alerts

Contractors may not be notified of required re-onboarding; delayed payment processing

Invoice Module

Internal Module

Uses Stripe configuration for payment processing on contractor invoices; references the connected Stripe account for transaction execution

Invoice payments cannot be processed; manual payment workflows may be required as fallback

Brands Management — Brand Creation/Deletion

Internal Process

Triggers dynamic updates to the Stripe Integration screen when brands are created or removed

New brands may not appear on the Stripe Integration screen; deleted brands may persist in the UI

## **12\. References**

*   **Figma Designs:** \[Figma Link\]  
    
*   **Related FRDs:  
    **
*   \[My\_Profile\_FRD.md\] — Agency Global Settings  
    
*   \[General\_Settings\_FRD.md\] — Agency Global Settings  
    
*   \[Business\_Payment\_Details\_FRD.md\] — Agency Global Settings  
    
*   \[Accepted\_Payment\_Methods\_FRD.md\] — Agency Global Settings  
    
*   \[Two\_Step\_Verification\_FRD.md\] — Agency Global Settings  
    
*   \[Data\_Management\_FRD.md\] — Agency Global Settings  
    

8\. Placeholder FRD Documents

# **FRD #7: Placeholder FRD Documents**

### The following modules require separate, dedicated FRD documents. This file contains placeholders for reference.

###

## **Team Management Module**

### Status: Separate FRD Required  
Link: [28\. Team Management](https://drive.google.com/drive/folders/1P0h9VI2L246XK_7_6yn--QX3EPXq1zA8?usp=drive_link)

###

## **Referral System Module**

### Status: Separate FRD Required  
Link: [Referral](https://docs.google.com/document/d/1ufd4KylxqdQnM8FF7UOwZvEEskqmTZHofZ8YujvNpRk/edit?usp=sharing)

###

## **Notifications Module**

### Status: Separate FRD Required  
Link: [27\. Notifications](https://drive.google.com/drive/folders/1p3mgymFA-DuVQZfJZFmTbz9L2hAxbYV9?usp=drive_link)

###

## **Brands Module**

### Status: Separate FRD Required  
Link:

###

## **Subscription Module**

### Status: Separate FRD Required  
Link:

###