# Merchant Management

## Purpose
Merchant Management handles CRUD operations for all registered merchants on the platform. It provides merchant creation, editing, commission settings, balance management, and account configuration. Each merchant is assigned to an agent and can have multiple currency accounts.

## Components
- Page header with icon and title
- Statistics cards (6 metrics)
- Action bar with Create, Delete, Export, Refresh buttons
- Search input
- Search & Filter section
- Merchant list data table
- Business Rules section
- Create Merchant modal
- Edit Merchant modal
- View Merchant modal
- Manual Balance Adjustment modal

## Header
- **Title**: "Merchant Management"
- **Subtitle**: "Manage all merchants, their commission settings, balances and account configurations"
- **Page Icon**: Blue background with store icon

### Statistics Cards
| Card | ID | Description |
|------|-----|-------------|
| Total Merchants | `totalMerchants` | All registered merchants |
| Active Merchants | `activeMerchants` | Currently active accounts |
| Inactive Merchants | `inactiveMerchants` | Inactive accounts |
| Total Merchant Balance | `totalBalance` | Combined balance across all merchants |
| Today's Transactions | `todayTransactions` | Transactions processed today |
| Pending Settlements | `pendingSettlements` | Settlements awaiting processing |

## Filters
| Filter | ID | Type | Options |
|--------|-----|------|---------|
| Merchant Name | `filterName` | text | — |
| Merchant ID | `filterId` | text | — |
| Agent | `filterAgent` | select | All Agents, Agent Alpha, Agent Beta, Agent Gamma |
| Currency | `filterCurrency` | select | All Currencies, USD, UGX, NGN, KES, GHS |
| Status | `filterStatus` | select | All Status, Active, Inactive, Suspended |
| Date From | `filterDateFrom` | date | — |
| Date To | `filterDateTo` | date | — |

## Search
- **Input ID**: `searchInput`
- **Placeholder**: "Search merchants..."
- **Searches**: Name, email, ID, agent

## Buttons
| Button | Action | Location |
|--------|--------|----------|
| Create Merchant | Opens create modal | Action bar |
| Delete Merchant | Deletes selected merchants | Action bar |
| Export | Exports merchant list to CSV | Action bar |
| Refresh | Reloads merchant list | Action bar |
| Clear Filters | Resets all filters | Filter section |

## Forms

### Create Merchant Modal (`createModal`)
| Field | ID | Type | Required | Options/Notes |
|-------|-----|------|----------|---------------|
| User ID | `newUserId` | text | Yes | placeholder: "USR-001" |
| Merchant Name | `newMerchantName` | text | Yes | — |
| Assigned Agent | `newAssignedAgent` | select | Yes | Select Agent, Agent Alpha, Agent Beta, Agent Gamma |
| Domain | `newDomain` | text | No | placeholder: "example.com" |
| Balance | `newBalance` | number | No | value="0" |
| Currency Type | `newCurrency` | select | No | USD, UGX, NGN, KES, GHS |
| Collection % | `newCollectionPct` | number | No | step=0.1, value="2.5" |
| Payout % | `newPayoutPct` | number | No | step=0.1, value="1.5" |
| Role | `newRole` | select | No | Merchant, Sub-Merchant, Partner |
| Commission | `newCommission` | number | No | step=0.1, value="5.0" |
| Administrator | `newAdministrator` | text | No | — |
| Contact Information | `newContact` | text | No | — |
| Account Status | `newStatus` | select | No | Active, Inactive, Suspended |

**Buttons**: Reset, Save Merchant

### Edit Merchant Modal (`editModal`)
| Field | ID | Type |
|-------|-----|------|
| Merchant Name | `editMerchantName` | text |
| Assigned Agent | `editAssignedAgent` | select |
| Domain | `editDomain` | text |
| Collection % | `editCollectionPct` | number |
| Payout % | `editPayoutPct` | number |
| Commission | `editCommission` | number |
| Administrator | `editAdministrator` | text |
| Contact Information | `editContact` | text |
| Account Status | `editStatus` | select |

**Hidden**: `editMerchantId`
**Buttons**: Cancel, Save Changes

### Manual Balance Adjustment Modal (`adjustmentModal`)
| Field | ID | Type | Required | Notes |
|-------|-----|------|----------|-------|
| Merchant ID | `adjustMerchantIdDisplay` | text | No (readonly) | — |
| Current Balance | `adjustCurrentBalance` | text | No (readonly) | — |
| Amount | `adjustAmount` | number | Yes | step=0.01 |
| Adjustment Type | `adjustType` | select | Yes | Increase, Decrease |
| Remarks | `adjustRemarks` | select | Yes | Manual Adjustment, Correction Deduction, Order Compensation, Settlement, Freeze Account |
| Created By | `adjustCreatedBy` | text | No (readonly) | value="Admin" |
| Date | `adjustDate` | date | No | — |

**Hidden**: `adjustMerchantId`
**Buttons**: Reset, Save Adjustment

### View Merchant Modal (`viewModal`)
**Title**: "Merchant Details"
**Displayed Fields**: User ID, Merchant Name, Assigned Agent, Domain, Balance, Currency, Collection %, Payout %, Role, Commission, Administrator, Contact, Status, Created
**Button**: Close

## Tables

### Merchant List Table
| Column | Description |
|--------|-------------|
| Checkbox | Select all/individual |
| User ID | Unique identifier |
| Merchant Name | Business name |
| Assigned Agent | Agent managing this merchant |
| Domain | Website domain |
| Balance | Current balance |
| Currency | Account currency |
| Collection % | Collection fee percentage |
| Payout % | Payout fee percentage |
| Role | Merchant role type |
| Commission | Commission rate |
| Administrator | Admin name |
| Contact | Contact information |
| Status | Account status |
| Created | Registration date |
| Actions | Action buttons |

## Action Buttons

### Row Actions
| Button | Function | Icon |
|--------|----------|------|
| View | View merchant details | Eye |
| Edit | Edit merchant information | Pencil |
| Delete | Delete merchant account | Trash |
| Balance Adjustment | Open balance adjustment modal | Dollar |

## Workflow
1. Admin navigates to Merchant Management page
2. Views statistics cards showing merchant counts and balances
3. Uses search/filters to find specific merchants
4. Clicks "Create Merchant" to open creation modal
5. Fills in required fields (ID, name, agent, domain)
6. Configures commission rates and currency
7. Saves new merchant
8. Can edit existing merchants via row action
9. Can view detailed merchant information
10. Can perform manual balance adjustments
11. Can export merchant list to CSV
12. Can delete selected merchants (with confirmation)

## Translation Requirements
| Key | English | Description |
|-----|---------|-------------|
| `merchant_management` | Merchant Management | Page title |
| `create_edit_manage_merchants` | Create, edit, and manage all registered merchants | Subtitle |
| `create_merchant` | Create Merchant | Button text |
| `delete_merchant` | Delete Merchant | Button text |
| `export` | Export | Button text |
| `refresh` | Refresh | Button text |
| `clear_filters` | Clear Filters | Button text |
| `search_merchants` | Search merchants... | Placeholder |
| `total_merchants` | Total Merchants | Stat label |
| `active_merchants` | Active Merchants | Stat label |
| `inactive_merchants` | Inactive Merchants | Stat label |
| `total_merchant_balance` | Total Merchant Balance | Stat label |
| `todays_transactions` | Today's Transactions | Stat label |
| `pending_settlements` | Pending Settlements | Stat label |
| `user_id` | User ID | Column/filter |
| `merchant_name` | Merchant Name | Column/filter |
| `assigned_agent` | Assigned Agent | Column/filter |
| `domain` | Domain | Column |
| `balance` | Balance | Column |
| `currency` | Currency | Column/filter |
| `collection_pct` | Collection % | Column |
| `payout_pct` | Payout % | Column |
| `role` | Role | Column |
| `commission` | Commission | Column |
| `administrator` | Administrator | Column |
| `contact` | Contact | Column |
| `status` | Status | Column/filter |
| `created` | Created | Column |
| `actions` | Actions | Column |
| `active` | Active | Status |
| `inactive` | Inactive | Status |
| `suspended` | Suspended | Status |
| `view` | View | Action |
| `edit` | Edit | Action |
| `delete` | Delete | Action |
| `balance_adjustment` | Balance Adjustment | Action |
| `manual_balance_adjustment` | Manual Balance Adjustment | Modal title |
| `adjustment_type` | Adjustment Type | Label |
| `increase` | Increase | Option |
| `decrease` | Decrease | Option |
| `remarks` | Remarks | Label |
| `save` | Save | Button |
| `cancel` | Cancel | Button |
| `reset` | Reset | Button |

## Responsive Requirements

### Desktop (≥1024px)
- 6-column statistics grid
- Horizontal filter bar
- Full-width data table

### Tablet (768px–1023px)
- 3-column statistics grid
- Stacked filter fields
- Horizontally scrollable table

### Mobile (<768px)
- 2-column statistics grid
- Full-width stacked filters
- Horizontally scrollable table

## API Dependency
- **Merchants API**: GET `/api/merchants` — List all merchants
- **Create Merchant**: POST `/api/merchants` — Create new merchant
- **Update Merchant**: PUT `/api/merchants/:id` — Update merchant
- **Delete Merchant**: DELETE `/api/merchants/:id` — Delete merchant
- **Balance Adjustment**: POST `/api/merchants/:id/adjustment` — Manual balance adjustment
- **Merchant Stats**: GET `/api/merchants/stats` — Merchant statistics
- **Export Merchants**: GET `/api/merchants/export` — CSV export