# Mercury UPI PSP Platform - Product Requirements Documents (PRD) Index

**Last Updated**: 2026-06-12  
**Total Documentation**: 2,299 lines across 6 PRD files  
**Status**: Complete & Ready for Stakeholder Review  

---

## 📋 PRD Suite Overview

This comprehensive PRD suite documents all components of the Mercury UPI PSP (Payment Service Provider) Platform, providing detailed requirements, architecture, features, and implementation guidelines for development teams, stakeholders, and compliance officers.

---

## 📁 PRD Files

### 1. **PRD_DA_PRODUCT_APP.md** (362 lines)
**Core Application - Business Logic & Infrastructure**

**Primary Focus**: Central business logic, security, audit trails, and shared services

**Key Sections**:
- Executive Summary & Product Overview
- 10 Core Features (Transaction Processing, QR Management, International Payments, etc.)
- Database Schema (14 core entities)
- API Architecture & Error Handling (20+ error codes)
- Configuration Requirements & Dependencies
- Security & Compliance Requirements
- Functional & Non-Functional Requirements
- Success Metrics & Risk Mitigation

**Target Users**: Engineering leads, architects, security team

**Download**: [PRD_DA_PRODUCT_APP.md](PRD_DA_PRODUCT_APP.md)

---

### 2. **PRD_UPI_CORE.md** (397 lines)
**Business Logic Layer - Request Normalization & Validation**

**Primary Focus**: Normalization, validation, and processing for ReqValQr/ReqPay/ReqChkTxn

**Key Sections**:
- ReqValQr Processing (QR validation, 20-step flow)
- ReqPay Processing (Payment requests, 19-step flow)
- ReqChkTxn Processing (Status queries)
- Domestic vs International Payment Flows
- FX Rate Management & Conversion
- Audit & Event Chain (Immutable hash-linked trails)
- Verification Token Management
- Database Schema with complete field definitions
- Error Detection & Classification
- API Contracts (XML input/output)

**Key Algorithms**:
- FX Conversion: `inr_amount = base_amount × fx_rate × (1 + markup_pct)`
- Event Chain: SHA256(prev_hash + current_event) for integrity

**Target Users**: Core backend engineers, QA testers

**Download**: [PRD_UPI_CORE.md](PRD_UPI_CORE.md)

---

### 3. **PRD_UPI_DYNAMIC.md** (355 lines)
**Dynamic QR Processing Module**

**Primary Focus**: Real-time QR generation, 30-minute validity, 8000 INR limit

**Key Specifications**:
- **Organization**: MER101 (org_id), MER1010001 (net_inst_id)
- **Initiation Mode**: 16
- **QR Validity**: 30 minutes
- **Amount Limit**: 8000 INR per transaction
- **Timeout VPA**: gourmet@mercury (30-second timeout simulation)

**Key Sections**:
- Dynamic QR Generation (unique per transaction)
- ReqValQr Processing (22-step flow with PE expiry check)
- ReqPay Processing (19-step flow with timeout handling)
- Timeout Scenarios & Error Handling
- 10 Error Scenarios with detailed flows
- HTTP API Endpoints (5 endpoints)
- Configuration & Feature Flags
- Performance Requirements (10,000 TPS target)
- Monitoring & Alerts

**Error Codes**: X7 (8000 INR limit), YH (merchant), PE (expired), ZE (token), ZD (duplicate), ZF (verification), IP05/08/10 (acquirer)

**Target Users**: Dynamic QR specialists, transaction processors

**Download**: [PRD_UPI_DYNAMIC.md](PRD_UPI_DYNAMIC.md)

---

### 4. **PRD_UPI_STATIC.md** (362 lines)
**Static QR Processing Module**

**Primary Focus**: Pre-printed QRs, 365-day validity, 200 INR limit

**Key Specifications**:
- **Organization**: MER102 (org_id), MER1020002 (net_inst_id)
- **Initiation Mode**: 02, 15
- **QR Validity**: 365 days (1 year)
- **Amount Limit**: 200 INR per transaction
- **Timeout VPA**: gourmet@merstatic
- **Terminal IDs**: tr (terminal) + tn (network) identifiers

**Key Sections**:
- Static QR Storage & Lifecycle Management
- ReqValQr Processing (19-step flow with tr/tn lookup)
- ReqPay Processing (19-step with static QR reuse)
- tr/tn Identifier Management
- Static QR Generation Flow (batch operations)
- 10 Error Scenarios (includes ZQ for tr/tn not found)
- Static vs Dynamic Comparison Table
- Inventory Management
- Database Schema (7 tables)

**Key Difference from Dynamic**: X7 limit is 200 INR (not 8000), 1-year validity (not 30 min), pre-generated, reusable, terminal-based

**Target Users**: Legacy QR specialists, merchant networks

**Download**: [PRD_UPI_STATIC.md](PRD_UPI_STATIC.md)

---

### 5. **PRD_UPI_SETTLEMENT.md** (369 lines)
**Financial Settlement & Reconciliation Module**

**Primary Focus**: Daily settlement batching, fee calculation, dispute management

**Key Features**:
- **Settlement Triggers**: 
  - 17:30 UTC: Main settlement generation
  - 20:35 UTC: NPCI settlement file ingestion
- **Fee Formula** (NPCI NTSL):
  - Interchange: 0.15% of gross
  - Switching: ₹0.25 per transaction
  - PSP: 0.50% of gross
  - GST: 18% on all fees
- **Settlement Window**: T-1 17:30 UTC to T 17:29:59 UTC
- **Dispute Lifecycle**: 9-state workflow (open → confirmed → representment_filed → won/lost → RRC → closed → archived)

**Key Sections**:
- Settlement Batch Generation (18 steps with idempotency)
- NPCI File Ingestion (11 steps)
- Dispute Management (9-state lifecycle with deadlines)
- UTXN Reconciliation (matching via partner_txn_id)
- Complete Fee Calculation Examples
- Dispute Deadline Tracking & Escalation Rules
- Settlement Scenarios (success, with disputes)
- Configuration & Error Handling
- Reporting & Monitoring
- Performance Requirements (batch < 5 min, reconciliation < 30 min)

**Database Schema**: 5 core tables (settlements, disputes, fees, reconciliation)

**Target Users**: Finance team, compliance officers, settlement specialists

**Download**: [PRD_UPI_SETTLEMENT.md](PRD_UPI_SETTLEMENT.md)

---

### 6. **PRD_UPI_WEB.md** (454 lines)
**User Interface & Admin Dashboard**

**Primary Focus**: Real-time dashboard, merchant management, transaction monitoring

**Key Features**:
- **24 User-Facing Flows** (login, dashboard, CRUD operations)
- **14 LiveView Components** (real-time interactive pages)
- **25 API Routes** organized by category
- **Real-time Updates** via WebSocket & PubSub

**Key Sections**:
- Admin Dashboard (KPIs, charts, alerts)
- Transaction Management (search, filter, detail)
- QR Validation Tracking
- Payment Requests (ReqPay)
- Merchant Management (CRUD)
- User & Organization Management
- Settlement Tracking
- Dispute Management
- Analytics & Reporting
- API Documentation (interactive)
- Technical Architecture & LiveView Lifecycle
- Features by User Role (Admin, Finance, Support, Merchant)
- Styling & Design (TailwindCSS)
- Real-time Features (WebSocket, PubSub, auto-refresh)
- Security (Auth, CSRF, PII masking)
- Performance Optimization
- Testing Strategy

**Pages/Routes**:
- `/dashboard` - Admin KPIs
- `/transactions` - Transaction list/detail
- `/qr-validations` - QR tracking
- `/req-pay` - Payment requests
- `/settlements` - Settlement batches
- `/disputes` - Chargeback management
- `/users`, `/organizations` - User/Org management
- `/analytics` - Reports
- `/api-docs` - API reference

**Performance Targets**:
- Dashboard: 500ms load, 1s interactive
- Transaction List: 800ms load, 1.2s interactive
- Settlement: 400ms load, 800ms interactive
- Analytics: 1500ms load, 2.5s interactive

**Target Users**: Admins, finance teams, merchants, developers

**Download**: [PRD_UPI_WEB.md](PRD_UPI_WEB.md)

---

## 🏗️ Architecture Overview

```
┌─────────────────────────────────────────────────┐
│                   UPI WEB (UI)                  │ PRD_UPI_WEB.md
│  Dashboard • Transactions • Settlements • Admin │
└────────────────┬────────────────────────────────┘
                 │ HTTP/WebSocket
┌────────────────┴────────────────────────────────┐
│              PHOENIX ROUTER                     │
├─────────────────────────────────────────────────┤
│  /api/v1/dynamic-qr/* → UPI Dynamic Handlers   │ PRD_UPI_DYNAMIC.md
│  /api/v1/static-qr/*  → UPI Static Handlers    │ PRD_UPI_STATIC.md
│  /api/v1/transactions → UPI Core Context       │ PRD_UPI_CORE.md
│  /api/v1/settlements  → UPI Settlement Module  │ PRD_UPI_SETTLEMENT.md
└────────────────┬────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────┐
│   DA_PRODUCT_APP (Core Business Logic)          │ PRD_DA_PRODUCT_APP.md
├─────────────────────────────────────────────────┤
│ • Transaction Processing    • Merchant Mgmt     │
│ • QR Validation             • Partner Integration│
│ • International Payments    • API Key Management│
│ • Audit Trails              • Feature Flags     │
│ • Monitoring & Analytics    • Security          │
└────────────────┬────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
    ┌───▼────┐        ┌───▼────┐
    │  MySQL │        │ NPCI   │
    │Database│        │APIs    │
    └────────┘        └────────┘
```

---

## 🔄 Data Flow

### ReqValQr → ReqPay → Settlement Flow

```
1. Merchant generates QR
   ↓
2. UPI_DYNAMIC or UPI_STATIC processes ReqValQr
   ├─ Parse XML
   ├─ Generate verification token
   ├─ Return RespValQr with token
   └─ (UPI_CORE handles normalization)
   ↓
3. Customer scans QR & initiates payment
   ↓
4. UPI_DYNAMIC or UPI_STATIC processes ReqPay
   ├─ Validate token
   ├─ Check amount & merchant
   ├─ Create transaction
   ├─ Return RespPay with status
   └─ (UPI_CORE creates immutable event chain)
   ↓
5. Settlement Window (Daily @ 17:30 UTC)
   ├─ UPI_SETTLEMENT aggregates transactions
   ├─ Calculate fees (interchange, switching, PSP, GST)
   ├─ Account for chargebacks & representments
   ├─ Generate settlement batch
   └─ Send to merchant
   ↓
6. NPCI Ingest (Daily @ 20:35 UTC)
   ├─ Receive NPCI settlement file (UTXN records)
   ├─ Match UTXN to transactions
   ├─ Reconcile amounts
   └─ Update dispute status
   ↓
7. UPI_WEB displays all data
   ├─ Real-time transaction updates
   ├─ Settlement tracking
   ├─ Dispute management
   └─ Analytics & reporting
```

---

## 📊 Key Statistics by App

| App | Lines | Tables | Endpoints | Key Metrics |
|-----|-------|--------|-----------|-------------|
| DA_PRODUCT_APP | 362 | 14 | N/A | 20+ error codes, 13 modules |
| UPI_CORE | 397 | 7 | N/A | 20-step validation, FX conversion |
| UPI_DYNAMIC | 355 | 6 | 5 | 8000 INR limit, 30 min validity |
| UPI_STATIC | 362 | 7 | 6 | 200 INR limit, 365 day validity |
| UPI_SETTLEMENT | 369 | 5 | 7 | 2 daily triggers, 9-state disputes |
| UPI_WEB | 454 | N/A | 25 | 24 flows, 14 components, 99.95% uptime |
| **TOTAL** | **2,299** | **39** | **43** | Comprehensive UPI Platform |

---

## 🎯 Use Cases by Audience

### 👨‍💼 Product Managers
- Start with: PRD_UPI_DYNAMIC.md, PRD_UPI_SETTLEMENT.md
- Focus on: Features, success metrics, user flows
- Check: Section 3 (Core Features) in each PRD

### 👨‍💻 Backend Engineers
- Start with: PRD_DA_PRODUCT_APP.md, PRD_UPI_CORE.md
- Focus on: Database schema, processing flows, API contracts
- Check: Database Schema & Processing Flow sections

### 👨‍🎨 Frontend Engineers
- Start with: PRD_UPI_WEB.md
- Focus on: Pages, components, styling, real-time features
- Check: Pages, Components, Styling & Design sections

### 🔒 Security/Compliance
- Start with: PRD_DA_PRODUCT_APP.md (Security & Compliance section)
- Focus on: Encryption, audit trails, data protection
- Check: Section 8 in each PRD

### 📊 Finance/Operations
- Start with: PRD_UPI_SETTLEMENT.md
- Focus on: Fee calculations, settlement, disputes
- Check: Fee Calculation formula, Scenarios, Reporting

### 🧪 QA/Testing
- Start with: All PRDs
- Focus on: Error scenarios, test cases, performance metrics
- Check: Error Handling sections & Scenarios

---

## 🔗 Cross-References

### Error Code Coverage
- **All Error Codes Defined**: Section 8 of DA_PRODUCT_APP, UPI_DYNAMIC, UPI_STATIC
- **Example Scenarios**: Section 6 of UPI_DYNAMIC, UPI_STATIC, UPI_SETTLEMENT

### Configuration Settings
- **Central Config**: PRD_DA_PRODUCT_APP.md Section 6
- **Dynamic-Specific**: PRD_UPI_DYNAMIC.md Section 7
- **Static-Specific**: PRD_UPI_STATIC.md Section 7
- **Settlement Config**: PRD_UPI_SETTLEMENT.md Section 6
- **Web Config**: PRD_UPI_WEB.md Deployment section

### Database Schema
- **Core Entities**: PRD_DA_PRODUCT_APP.md Section 4
- **QR Validation**: PRD_UPI_CORE.md Section 4
- **Dynamic-Specific**: PRD_UPI_DYNAMIC.md Section 4
- **Static-Specific**: PRD_UPI_STATIC.md Section 4
- **Settlement Tables**: PRD_UPI_SETTLEMENT.md Section 4

### Performance Targets
- **All Targets**: Each PRD Section 10 (Performance/Requirements)
- **API Latency**: < 100ms for sync, < 150ms for validation
- **Settlement**: < 5 minutes batch generation, < 30 min reconciliation
- **Web**: < 2s page load time

---

## 📝 Document Conventions

### Formatting
- **bold**: Emphasis, key terms
- `code`: File names, variable names, configuration keys
- **Tables**: Structured data, scenarios, error codes
- **Code blocks**: Examples, configuration, formulas
- **Lists**: Requirements, features, steps

### Sections in Each PRD
1. Executive Summary
2. Product Overview (Purpose, Key Users)
3. Core Features (8-12 features)
4. Database Schema
5. Processing Flow (with step-by-step breakdowns)
6. Configuration
7. Error Handling
8. API/Implementation Examples
9. Dependencies
10. Performance/Success Metrics
11. Additional (Testing, Deployment, Future)

### Scenario Notation
- **S1, S2, ..., S10**: Test scenarios
- **Error Code**: NPCI standard error code
- **Status**: HTTP or business status
- **Expected Output**: Result or error response

---

## 🚀 Quick Start by Role

### Getting Started (5-minute read)
- **All**: PRD_INDEX.md (this file) - Architecture Overview
- **Managers**: PRD_UPI_WEB.md Section 3 (Features by user role)
- **Engineers**: PRD_UPI_CORE.md Section 1-2 (Executive Summary)
- **Finance**: PRD_UPI_SETTLEMENT.md Section 3 (Fee Formula)

### Deep Dive (30-minute read)
- **Managers**: Full section 3 of main PRD for your area
- **Engineers**: Sections 4-5 (Schema & Processing flow)
- **Compliance**: Section 8 of PRD_DA_PRODUCT_APP.md
- **Finance**: Section 5 (Settlement Flow) & Section 7 (Scenarios)

### Implementation (2+ hour read)
- **All**: Sections 4-8 of your module PRD
- **Integration**: Cross-reference related module sections
- **Testing**: Section 9 (Error Handling) + Scenarios
- **Performance**: Section 10 (Performance Requirements)

---

## ✅ Quality Checklist

- ✅ All 6 PRDs completed (2,299 lines total)
- ✅ Consistent structure across all documents
- ✅ 20+ error codes documented
- ✅ 39+ database tables defined
- ✅ 43+ API endpoints described
- ✅ Processing flows with step-by-step breakdowns
- ✅ Configuration parameters documented
- ✅ Success metrics defined
- ✅ Error scenarios with examples
- ✅ Performance targets specified
- ✅ Security requirements outlined
- ✅ Role-based access defined
- ✅ Cross-references between modules
- ✅ Ready for stakeholder review

---

## 📞 Support & Questions

For questions about specific PRDs:
1. **General Architecture**: See PRD_INDEX.md (this file)
2. **Core Business Logic**: Consult PRD_DA_PRODUCT_APP.md
3. **Technical Implementation**: Reference PRD_UPI_CORE.md
4. **Dynamic QR**: Check PRD_UPI_DYNAMIC.md
5. **Static QR**: Check PRD_UPI_STATIC.md
6. **Financial Operations**: See PRD_UPI_SETTLEMENT.md
7. **User Interface**: Reference PRD_UPI_WEB.md

---

## 📅 Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-06-12 | Initial complete PRD suite for all 6 apps |

---

**Status**: ✅ **COMPLETE & READY FOR REVIEW**

All PRD documents are comprehensive, cross-referenced, and ready for stakeholder review, development planning, and implementation guidance.