# Technical Proposal: Acquirer Role & Simplified Merchant Onboarding

## 1. Executive Summary
This proposal outlines the architectural changes and implementation plan required to introduce a new **"Acquirer"** administrative role. This role is designed to manage a specific portfolio of merchants, enabling rapid, friction-free onboarding. Unlike the standard self-service flow, Acquirers can instantly provision merchants by bypassing standard KYC/OCR workflows, while maintaining strict data isolation and security.

## 2. Architectural Gap Analysis & Required Modifications

| Domain | Current State | Required Modifications |
| :--- | :--- | :--- |
| **Database & Security** | Optimized for self-service merchants requiring heavy compliance (KYC/OCR) and a global Admin view. | • **RBAC Expansion:** Implementation of a new `acquirer` role with granular permissions (`merchant-create`, `merchant-manage`, `merchant-list`).<br>• **Data Isolation:** Strict "Owner-Child" logic in `UserMerchantAssignment` to ensure Acquirers only access their own merchants.<br>• **Metadata Schema:** Updates to `user_metadata` to distinguish "Managed" vs "Independent" merchants. |
| **Backend Core Logic** | Merchant creation is tightly coupled with a multi-step compliance wizard. | • **Dedicated Controller:** `AcquirerMerchantController` for "Lite" creation logic, separate from the complex wizard.<br>• **Service Refactoring:** Decoupling ID generation for synchronous, instant provisioning of `Mercury_ID`s.<br>• **Global Scoping:** Middleware to automatically filter database queries based on the logged-in Acquirer's ID. |
| **Frontend UI/UX** | Dashboards are focused on compliance approval queues and global analytics. | • **Acquirer Dashboard:** Specialized view removing compliance widgets, focusing on Portfolio Management.<br>• **Instant Onboarding:** Single-page "Quick Add" form replacing the multi-step wizard.<br>• **Management Console:** Simplified table allowing instant status toggling (Active/Suspend). |

## 3. Acquirer Feature Set

The Acquirer role comes equipped with a specialized suite of tools designed for high-volume, low-friction merchant management.

### A. Merchant Onboarding & Provisioning
*   **Instant "Lite" Onboarding:** A simplified, single-page form to register merchants using only essential data (Business Name, Email, Currency, Country).
*   **KYC Bypass:** Automatically skips standard compliance checks (OCR, Document Uploads) for trusted Acquirer-managed merchants.
*   **Synchronous ID Generation:** Instantly generates and assigns a production-ready `Mercury_ID` upon form submission.
*   **Auto-Assignment:** Newly created merchants are automatically linked to the creating Acquirer's portfolio.

### B. Portfolio Management
*   **Dedicated Dashboard:** A focused view displaying total merchant count, active status, and recent onboarding activity.
*   **Merchant List View:** A searchable, filterable table of all merchants under the Acquirer's management.
*   **Status Control:** One-click toggle to **Activate** or **Suspend** a merchant's ability to process transactions immediately.
*   **Profile Editing:** Ability to update basic merchant contact information and settings without triggering re-verification flows.

### C. Security & Access Control
*   **Strict Data Isolation:** Acquirers can *only* view and manage merchants they have explicitly onboarded.
*   **Role-Based Limits:** Restricted from accessing global system settings or other Acquirers' portfolios.
*   **Audit Logging:** All actions (creation, status changes) are logged for system administrators to review.

## 4. Implementation Project Plan

### Phase 1: Architecture & Security Foundation (Est. 1 Week)
*   Database migrations for new roles and permissions.
*   Refactoring of ID generation services to support "Instant Provisioning".
*   Setup of Data Isolation Middleware and Global Scopes.

### Phase 2: Backend Logic Development (Est. 1 Week)
*   API development for "Lite" merchant creation (bypassing KYC).
*   Integration with existing Transaction/Cloud layers to ensure new merchants are transaction-ready immediately.
*   Automated status handling (programmatically skipping KYC stages).

### Phase 3: Frontend Interface Construction (Est. 1 Week)
*   Development of the specific Acquirer Dashboard view.
*   Implementation of "Quick Add" forms with real-time validation.
*   Portfolio list views and management actions (Edit/Suspend).

### Phase 4: QA, Integration & Deployment (Est. 1 Week)
*   **Security Auditing:** Verification of Access Control Lists (ACL) to ensure Acquirers cannot access global data.
*   **End-to-End Testing:** Validating the flow: *Acquirer Login -> Create Merchant -> Merchant Login -> Process Transaction*.
*   Production deployment and documentation.

## 5. Strategic Value & ROI
*   **Scalability:** Enables the platform to scale via partners (Acquirers) without increasing the operational load on the central admin team.
*   **Security:** Leverages the existing robust security infrastructure while adding a new layer of multi-tenancy.
*   **Speed to Market:** Reduces merchant onboarding time from days (KYC process) to seconds, enabling immediate revenue generation.