Work in Progress
Feature details in this document may change during investigation, discussion, design, and implementation phases.
Organization / Tổ chức
Business entity and company-level management.
Overview
| Attribute | Value |
|---|---|
| Module ID | CORE-03 |
| Phase | Phase 2 |
| Priority | HIGH |
| Dependencies | User Management |
The Organization module manages the top-level business entity (Hộ kinh doanh / Doanh nghiệp). This is the parent container for all stores, users, and operations. Organizations can be created through self-registration by owners or sales-assisted registration, both requiring internal operator verification before activation.
┌─────────────────────────────────────────────────────────────────┐
│ ORGANIZATION HIERARCHY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ ORGANIZATION │ │
│ │ (Hộ kinh doanh / Doanh nghiệp) │ │
│ │ │ │
│ │ - Business Registration │ │
│ │ - Tax ID (MST) │ │
│ │ - Onboarding Status │ │
│ │ - Company Settings │ │
│ └─────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ │
│ │ Merchant 1│ │ Merchant 2│ → See Merchant Module│
│ │ (Store) │ │ (Store) │ │
│ │ (MO #1) │ │ (MO #2) │ → Each can have MO │
│ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘Registration Methods
| Method | Description | Initiator |
|---|---|---|
| Self-Registration | Owner registers directly in PMBH app/web | Owner |
| Sales-Assisted | Sales person registers on behalf of owner | Sales Person |
Both methods follow the same onboarding process after registration.
Onboarding Status
Organizations go through a manual onboarding process before becoming fully operational:
| Status | Description | Can Operate | Features Available |
|---|---|---|---|
PENDING | Registered in PMBH, awaiting VNPAY MO submission | No | View status only |
MO_SUBMITTED | Submitted to VNPAY MO, awaiting approval | No | View status only |
MO_APPROVED | VNPAY approved, awaiting operator activation | No | View status only |
ACTIVATED | Fully activated, ready to use | Yes | All features |
SUSPENDED | Temporarily disabled | No | View only |
Note: Each Merchant under an Organization can have its own MO registration. If the owner wants payment capabilities for multiple stores, they need to register separate MO accounts for each Merchant in VNPAY.
User Stories
Self-Registration (Owner)
| ID | As a... | I want to... | So that... |
|---|---|---|---|
| US-REG-01 | Business owner | Register myself and my organization | I can start the onboarding process |
| US-REG-02 | Business owner | Enter my business information (MST, address) | My organization is properly set up |
| US-REG-03 | Business owner | See my registration status | I know where I am in the process |
| US-REG-04 | Business owner | Receive notifications on status changes | I know when I can start using the system |
| US-REG-05 | Business owner | Access full features after activation | I can operate my business |
Sales-Assisted Registration
| ID | As a... | I want to... | So that... |
|---|---|---|---|
| US-SALES-01 | Sales person | Register organization on behalf of owner | Owner doesn't need to do it themselves |
| US-SALES-02 | Sales person | Submit organization to VNPAY MO | Approval process can begin |
| US-SALES-03 | Sales person | Track organizations I registered | I know their onboarding status |
Onboarding (Internal Users)
| ID | As a... | I want to... | So that... |
|---|---|---|---|
| US-INT-01 | Operator | See pending organizations awaiting processing | I know which need attention |
| US-INT-02 | Operator | Submit organization to VNPAY MO | Approval process can begin |
| US-INT-03 | Operator | Sync MO approval data | Organization info is updated |
| US-INT-04 | Operator | Complete organization details | All required info is filled |
| US-INT-05 | Operator | Activate organization | Owner can start using full features |
| US-INT-06 | Admin | View onboarding dashboard | I can monitor the pipeline |
| US-INT-07 | Admin | Suspend/reactivate organizations | I can manage compliance issues |
Organization Management (After Activation)
| ID | As a... | I want to... | So that... |
|---|---|---|---|
| US-OWN-01 | Business owner | Configure company-wide settings | All stores follow consistent rules |
| US-OWN-02 | Business owner | Manage business licenses | Compliance requirements are met |
| US-OWN-03 | Business owner | Set default tax rates | Invoices use correct VAT rates |
| US-OWN-04 | Business owner | Configure invoice templates | Invoices match brand identity |
| US-OWN-05 | Business owner | View organization dashboard | I see overall business performance |
| US-OWN-06 | Business owner | Request additional MO for merchants | Each store can process payments |
Feature Matrix
Registration & Onboarding
| Feature | P1 | P2 | P3 | Description |
|---|---|---|---|---|
| Owner self-registration | ✓ | Owner registers directly in app/web | ||
| Sales-assisted registration | ✓ | Sales registers on behalf of owner | ||
| Onboarding status tracking | ✓ | Track PENDING → MO_SUBMITTED → MO_APPROVED → ACTIVATED | ||
| Status notifications | ✓ | Notify owner on status changes | ||
| MO submission (Operator) | ✓ | Operator submits to VNPAY MO | ||
| MO sync (Operator) | ✓ | Operator syncs MO approval data | ||
| Organization activation | ✓ | Operator activates for full access | ||
| Onboarding dashboard (Admin) | ✓ | View all pending onboardings |
Organization Management (After Activation)
| Feature | P1 | P2 | P3 | Description |
|---|---|---|---|---|
| Full organization profile | ✓ | Complete business entity setup | ||
| Company-wide settings | ✓ | Default settings for all stores | ||
| Invoice template config | ✓ | Customize invoice appearance | ||
| Multiple MO per merchant | ✓ | Register separate MO for each store | ||
| License management | ✓ | Track business licenses | ||
| Multi-brand support | ✓ | Multiple brands under one org |
Key Flows
Owner Self-Registration Flow
Sales-Assisted Registration Flow
Onboarding State Diagram
What Owner Can Do at Each Status
┌─────────────────────────────────────────────────────────────────────────────┐
│ FEATURE ACCESS BY STATUS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PENDING / MO_SUBMITTED / MO_APPROVED: │
│ ├── ✓ View onboarding status │
│ ├── ✓ View/edit basic profile │
│ ├── ✗ Create merchants/stores │
│ ├── ✗ Create products │
│ ├── ✗ Process orders │
│ └── ✗ Access reports │
│ │
│ ACTIVATED: │
│ ├── ✓ Full organization management │
│ ├── ✓ Create merchants/stores │
│ ├── ✓ Manage products & inventory │
│ ├── ✓ Process orders & payments │
│ ├── ✓ Issue invoices │
│ ├── ✓ Access all reports │
│ └── ✓ Manage users & permissions │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Multiple MO Registration Flow
Organization Setup Flow (After Onboarding)
Business Rules
Registration Rules
| Rule ID | Rule | Description |
|---|---|---|
| BR-REG-01 | Self-registration allowed | Owner can register themselves directly |
| BR-REG-02 | Sales-assisted allowed | Sales can register on behalf of owner |
| BR-REG-03 | MST required at registration | Tax ID (MST) must be provided during registration |
| BR-REG-04 | MST unique | MST must be unique system-wide |
| BR-REG-05 | Phone verification | Owner phone must be verified during registration |
| BR-REG-06 | Initial status PENDING | New registrations start with PENDING status |
Onboarding Rules
| Rule ID | Rule | Description |
|---|---|---|
| BR-ONB-01 | Operator submits to MO | Only Operator can submit organization to VNPAY MO |
| BR-ONB-02 | Cannot operate until ACTIVATED | Full features only available after ACTIVATED status |
| BR-ONB-03 | Operator activates | Only internal Operator can activate organization |
| BR-ONB-04 | Status notifications | Owner notified on each status change |
| BR-ONB-05 | Sequential status | Status must follow: PENDING → MO_SUBMITTED → MO_APPROVED → ACTIVATED |
| BR-ONB-06 | Limited access before activation | Owner can only view status and edit basic profile before ACTIVATED |
Organization Rules
| Rule ID | Rule | Description |
|---|---|---|
| BR-ORG-01 | Single organization | Each owner has exactly one organization |
| BR-ORG-02 | Cascading settings | Org settings cascade to merchants |
| BR-ORG-03 | VAT rate validation | VAT rates must be valid Vietnam rates |
| BR-ORG-04 | Address required | Business address is mandatory |
| BR-ORG-05 | Owner immutable | Organization owner cannot be changed |
| BR-ORG-06 | Soft delete only | Organizations can only be suspended, not deleted |
| BR-ORG-07 | Audit trail | All changes are logged for compliance |
MO Registration Rules
| Rule ID | Rule | Description |
|---|---|---|
| BR-MO-01 | MO per merchant | Each Merchant can have its own MO registration |
| BR-MO-02 | Multiple MO allowed | Owner can register multiple MO for multiple merchants |
| BR-MO-03 | MO required for payment | Merchant needs MO to process payments |
| BR-MO-04 | MO linked by Operator | Operator links MO approval to specific Merchant |
Acceptance Criteria
Self-Registration
AC-REG-01: Owner Self-Registration
GIVEN a business owner wants to use PMBH
WHEN they register themselves on app/web
THEN - Owner account is created
- Organization is created with status PENDING
- Owner receives registration confirmation
- Owner can view their onboarding status
- Owner cannot access operational featuresAC-REG-02: Registration Data Validation
GIVEN a user registering organization
WHEN they submit registration form
THEN - MST format is validated
- MST uniqueness is checked
- Phone number is verified
- Required fields are enforced
- Clear error messages on validation failureSales-Assisted Registration
AC-REG-03: Sales Registers Organization
GIVEN a sales person with business owner info
WHEN they register organization in PMBH
THEN - Organization is created with status PENDING
- Owner account is created with temporary credentials
- Owner receives account creation notification
- Sales can track registration statusOnboarding (Internal Processing)
AC-ONB-01: Operator Submits to MO
GIVEN an organization with status PENDING
WHEN operator submits to VNPAY MO
THEN - Organization status changes to MO_SUBMITTED
- Submission timestamp is recorded
- Owner is notified of status change
- Organization still cannot operateAC-ONB-02: Operator Syncs MO Approval
GIVEN VNPAY has approved MO and notified sales by email
WHEN operator syncs MO approval in Admin Portal
THEN - Organization status changes to MO_APPROVED
- MO reference ID is linked
- Approval data is recorded
- Owner is notified of status change
- Organization still cannot operateAC-ONB-03: Operator Activates Organization
GIVEN an organization with status MO_APPROVED
WHEN operator fills details and activates
THEN - All required fields are complete
- Organization status changes to ACTIVATED
- Activation timestamp is recorded
- Owner is notified of activation
- Organization can now operate fullyAC-ONB-04: Status Notifications
GIVEN an organization undergoing onboarding
WHEN status changes (any transition)
THEN - Owner receives push notification
- Owner receives email notification (if configured)
- Status change is logged with timestamp
- Previous status is preserved in historyMO Registration
AC-MO-01: Multiple MO Registration
GIVEN an owner wanting payment for additional merchant
WHEN sales registers new MO in VNPAY
THEN - New MO can be linked to specific merchant
- Operator links MO to merchant
- Merchant can process payments
- MO details are recorded per merchantOrganization Management (After Activation)
AC-ORG-01: Organization Profile Setup
GIVEN an owner with ACTIVATED organization
WHEN they access organization settings
THEN - Existing data is displayed
- Required fields are clearly marked
- MST format is validated
- Profile can be updated
- Changes are loggedAC-ORG-02: Company-wide Settings
GIVEN an owner configuring organization settings
WHEN they set default values (tax rate, currency, etc.)
THEN - Settings apply to all merchants by default
- Merchants can override if permitted
- Changes are loggedAC-ORG-03: Invoice Template Configuration
GIVEN an owner setting up invoice template
WHEN they configure logo, footer, terms
THEN - Template preview shows changes
- All merchants use this template
- Changes apply to new invoices onlySuspension & Reactivation
AC-SUS-01: Organization Suspension
GIVEN an ACTIVATED organization with compliance issue
WHEN admin suspends the organization
THEN - Organization status changes to SUSPENDED
- Owner is notified immediately
- All operational features are disabled
- Historical data remains accessible
- Reason is recorded in audit logAC-SUS-02: Organization Reactivation
GIVEN a SUSPENDED organization
WHEN admin reactivates the organization
THEN - Organization status changes to ACTIVATED
- Owner is notified immediately
- All operational features are restored
- Reactivation is loggedDependencies
Organization
├── Requires: User Management (Owner)
├── Required by: Merchant, Permissions, Reports
└── Integrates: VNPAY MO, CA Provider| Module | Relationship |
|---|---|
| User Management | Owner belongs to Org |
| Permissions | Roles scoped to Org |
| Merchant | Stores belong to Org |
| Tax & Invoice | Tax settings from Org |
Integration Points
VNPAY Management Office (MO)
┌─────────────────────────────────────────────────────────────────┐
│ VNPAY MO INTEGRATION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CURRENT PROCESS: Manual (No automatic sync) │
│ │
│ Self-Registration Flow: │
│ 1. Owner registers in PMBH (status: PENDING) │
│ 2. Operator reviews and submits to VNPAY MO │
│ 3. VNPAY reviews and approves │
│ 4. VNPAY notifies Operator via EMAIL │
│ 5. Operator syncs approval in Admin Portal (status: MO_APPROVED)│
│ 6. Operator activates organization (status: ACTIVATED) │
│ │
│ Sales-Assisted Flow: │
│ 1. Sales registers org in PMBH (status: PENDING) │
│ 2. Operator submits to VNPAY MO (status: MO_SUBMITTED) │
│ 3. VNPAY reviews and approves │
│ 4. VNPAY notifies Operator via EMAIL │
│ 5. Operator syncs approval (status: MO_APPROVED) │
│ 6. Operator activates organization (status: ACTIVATED) │
│ │
│ MO Data (manually synced): │
│ ├── MO Reference ID │
│ ├── Business registration details │
│ ├── Tax ID (MST) │
│ ├── Approved payment methods │
│ └── Merchant/outlet information │
│ │
│ MO Registration: │
│ ├── One MO per Merchant (for payment capability) │
│ ├── Owner can have multiple MO (one per store) │
│ └── Each MO linked to specific Merchant by Operator │
│ │
└─────────────────────────────────────────────────────────────────┘Admin Portal (Internal Users)
┌─────────────────────────────────────────────────────────────────┐
│ ADMIN PORTAL - ONBOARDING │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Operator Functions: │
│ ├── View pending organizations (PENDING status) │
│ ├── Submit organization to VNPAY MO │
│ ├── Sync MO approval data │
│ ├── Fill organization details │
│ ├── Link MO to Merchants │
│ └── Activate organization (status: ACTIVATED) │
│ │
│ Admin Functions: │
│ ├── Onboarding dashboard (all statuses) │
│ ├── Suspend/reactivate organizations │
│ └── Override/correct organization data │
│ │
└─────────────────────────────────────────────────────────────────┘CA Provider (Certificate Authority)
┌─────────────────────────────────────────────────────────┐
│ CA PROVIDER INTEGRATION │
├─────────────────────────────────────────────────────────┤
│ │
│ Purpose: E-Invoice certificate management │
│ │
│ Data Exchange: │
│ ├── Organization MST │
│ ├── Business registration │
│ ├── Digital certificate request │
│ └── Certificate status │
│ │
│ Status: Managed through Tax & Invoice module │
│ │
└─────────────────────────────────────────────────────────┘Screenshots
Screenshots
Screenshots will be added after UI implementation.
Related Modules
- User Management - Owner account
- Permissions - Organization-level roles
- Merchant - Stores under organization
- Tax & Invoice - Tax configuration
- Reports - Organization-wide reports