# PRD: Da Product App (Core Application)

**Version**: 1.0  
**Date**: 2026-06-12  
**Status**: Active  

---

## 1. Executive Summary

**Da Product App** is the primary umbrella application containing core business logic, security infrastructure, audit trails, and shared services for the Mercury UPI PSP Platform. It serves as the backbone for all UPI payment processing operations, international payment corridors, merchant management, and financial settlements.

**Primary Stakeholders**: Financial Operations, Engineering, Security, Compliance

---

## 2. Product Overview

### 2.1 Purpose
- **Core Business Logic**: Transaction processing, QR validation, payment flows
- **Security Infrastructure**: Encryption, signature verification, API key management
- **Audit & Compliance**: Immutable transaction event chains, regulatory logging
- **International Payments**: Multi-currency support, FX rate management, corridor handling
- **Merchant Management**: Merchant profiles, invoice generation, KYC tracking
- **Partner Integration**: Partner API keys, webhook management, external system integration
- **Feature Control**: Feature flags for gradual rollout and A/B testing
- **Financial Reporting**: Monitoring, analytics, and business intelligence

### 2.2 Key Users
- **Merchants**: Receive payments via UPI/QR codes
- **Acquirers**: Process payment transactions
- **Partners**: Integrate with UPI platform APIs
- **Admin Users**: Manage system configuration and monitoring
- **Compliance Officers**: Audit trail review and regulatory compliance

---

## 3. Core Features

### 3.1 Transaction Processing
- **ReqValQr Processing**: QR validation with verification tokens
- **ReqPay Processing**: Payment request handling with status tracking
- **ReqChkTxn Processing**: Transaction status check queries
- **Async Processing**: Non-blocking two-phase response (ACK + processing)
- **Idempotency**: Prevention of duplicate transactions via unique tokens/msg_ids
- **Error Handling**: 20+ standardized NPCI error codes (X7, YH, PE, ZE, ZD, ZF, etc.)

### 3.2 QR Code Management
- **Dynamic QR**: Real-time QR generation (initiation_mode=16)
- **Static QR**: Pre-stored QR codes (initiation_mode=02/15)
- **QR Validation**: XML parsing, payload verification, expiry checks
- **QR Parser**: Support for UPI, Bharat QR, and custom formats

### 3.3 International Payments
- **Multi-Corridor Support**: Singapore, UAE, USA, and extensible corridors
- **FX Rate Management**: Real-time currency conversion with markup
- **Validation Types**: DOMESTIC vs INTERNATIONAL routing
- **Base Currency Handling**: Convert foreign currency to INR with NPCI compliance

### 3.4 Merchant Operations
- **Merchant Profiles**: VPA, category, invoice management
- **Organization Hierarchy**: Multiple merchants per organization
- **Timeout Simulation**: Special VPA handlers (gourmet@mercury, gourmet@merstatic)
- **Merchant Invoicing**: Generate and track payment invoices

### 3.5 Audit & Compliance
- **Event Chain**: Hash-linked immutable transaction events with SHA256
- **API Request Logging**: All external API calls logged with request/response
- **Transaction Events**: Timestamped state changes with previous hash verification
- **Regulatory Reporting**: Settlement reconciliation and dispute tracking

### 3.6 Security
- **Signature Verification**: Merchant signature validation using RSA/ECDSA
- **Encryption**: Payment data encryption at rest and in transit
- **API Keys**: Secure API key generation, rotation, and revocation
- **Session Management**: JWT tokens with expiry and refresh mechanisms
- **Data Masking**: PII masking in logs (payment details, credentials)

### 3.7 Partner Integration
- **API Key Operations**: Create, list, revoke, rotate operations
- **Email Service**: Send API key notifications and alerts
- **Partner Management**: Track partner organizations and credentials
- **Webhook Management**: Configure and manage partner webhooks

### 3.8 Financial Management
- **Fee Calculation**: NPCI NTSL formula (interchange, switching, PSP, GST)
- **Settlement Batching**: Daily settlement batch generation
- **Dispute Handling**: Chargeback and representment workflows
- **Reconciliation**: UTXN matching and settlement validation

### 3.9 Feature Flags
- **Gradual Rollout**: Enable features progressively
- **A/B Testing**: Run experiments with user segments
- **Emergency Kill Switch**: Disable problematic features instantly
- **Configuration**: Per-organization flag management

### 3.10 Monitoring & Analytics
- **System Health**: Memory, CPU, database connection monitoring
- **KPI Tracking**: Transaction volume, success rates, error rates
- **Performance Metrics**: Response times, throughput, latency
- **Alert System**: Automatic alerts for anomalies

---

## 4. Database Schema Overview

### 4.1 Core Entities
| Entity | Purpose | Key Fields |
|--------|---------|-----------|
| qr_validations | QR validation records | msg_id, txn_id, ver_token, qr_payload, org_id, validation_type |
| req_pays | Payment requests | msg_id, txn_id, payer_addr, payee_addr, amount, status |
| transactions | Payment transactions | txn_id, status, settlement_amount, fee_calc |
| merchants | Merchant profiles | vpa, category, org_id, invoice_id |
| partners | Partner organizations | org_id, net_inst_id, api_keys |
| static_qrs | Pre-stored QR records | tr, tn, org_id, expires_at |
| settlements | Settlement batches | batch_id, window, total_amount, status |
| disputes | Chargeback records | dispute_id, txn_id, status, representment_filed_at |
| api_keys | Partner API credentials | key_hash, partner_id, status, rotated_at |
| qr_validation_events | Event chain | seq, event_type, payload, prev_hash, hash |
| transaction_events | Event chain | seq, event_type, payload, prev_hash, hash |
| fx_quotes | FX rate records | currency_pair, rate, timestamp |
| fx_rates | FX rate master | currency, rate, effective_date |
| feature_flags | Feature toggles | flag_name, enabled, organizations |

### 4.2 Constraints & Indexes
- **Unique**: msg_id (idempotency), ver_token (QR validation)
- **Foreign Keys**: txn_id → transactions, org_id → partners, merchant_id → merchants
- **Indexes**: org_id, txn_id, timestamp columns for fast queries
- **Partitioning**: Consider date-based partitioning for events table

---

## 5. API Architecture

### 5.1 Key Modules
- **Accounts**: User and organization management
- **QRValidation**: ReqValQr processing and token generation
- **Transactions**: Core transaction lifecycle
- **ReqPay**: Payment request normalization
- **International**: Multi-currency and corridor handling
- **Merchants**: Merchant profile management
- **Partners**: Partner integration and API keys
- **Adapters**: External service integrations (NPCI, partners)
- **Crypto**: Signature and encryption operations
- **Audit**: Event logging and immutable trails
- **ForeignExchange**: FX rate management
- **Monitoring**: System health and metrics
- **FeatureFlags**: Toggle management

### 5.2 Error Handling
| Error Code | Meaning | Response Status |
|-----------|---------|-----------------|
| 00 | Success | 200 OK |
| PE | Payment Expired | 400 Bad Request |
| X7 | Amount Exceeds Limit | 400 Bad Request |
| YH | Merchant Error | 403 Forbidden |
| ZE | Invalid Token | 400 Bad Request |
| ZD | Duplicate Request | 400 Bad Request |
| ZF | Verification Failed | 403 Forbidden |
| ZQ | QR Not Found | 404 Not Found |
| ZR | Merchant Not Found | 404 Not Found |
| ZH | Invalid XML | 400 Bad Request |
| 05 | Invalid Payload | 400 Bad Request |
| 96 | System Error | 500 Internal Server Error |
| IP05/08/10 | Acquirer Errors | 400/500 depending on scenario |

---

## 6. Configuration Requirements

### 6.1 Environment Variables
```elixir
# Database
DATABASE_URL=ecto://user:pass@localhost/da_product_app

# Security
SECRET_KEY_BASE=<generated-random-key>
ENCRYPTION_KEY=<aes-256-key>

# NPCI Integration
NPCI_API_URL=https://npci.sandbox.com/api
NPCI_AUTH_TOKEN=<token>

# FX Rates
FX_SERVICE_URL=https://fxrates.example.com/api
FX_API_KEY=<key>

# Email Service
SMTP_HOST=smtp.sendgrid.net
SENDGRID_API_KEY=<key>

# Monitoring
SENTRY_DSN=<sentry-url>
DATADOG_API_KEY=<key>

# Feature Flags
FEATURE_FLAG_SERVICE_URL=https://flags.example.com

# Settlement
SETTLEMENT_WINDOW_HOURS=24
SETTLEMENT_DAILY_TRIGGER=17:30
INGEST_DAILY_TRIGGER=20:35
```

### 6.2 Configuration Settings
- **Amount Limits**: Dynamic QR 8000 INR, Static QR 200 INR
- **Expiry Windows**: Dynamic 30 minutes, Static 365 days
- **Fee Rates**: Interchange 0.15%, Switching ₹0.25/txn, PSP 0.50%, GST 18%
- **Timeout VPAs**: gourmet@mercury (dynamic), gourmet@merstatic (static)
- **Settlement Windows**: T-1 17:30 UTC to T 17:29:59 UTC
- **Dispute Workflow**: 9-state lifecycle with deadline checks

---

## 7. Dependencies

### 7.1 External Services
- **NPCI Platform**: Payment network integration
- **Bank Partners**: Acquiring and settlement
- **FX Rate Service**: Currency conversion rates
- **Email Service**: SendGrid/SMTP for notifications
- **Monitoring**: Sentry/Datadog for APM

### 7.2 Elixir Libraries
- **phoenix**: Web framework
- **ecto_sql**: ORM with MySQL adapter
- **myxql**: MySQL driver
- **req**: HTTP client
- **sweet_xml**: XML parsing
- **bcrypt_elixir**: Password hashing
- **joken**: JWT token handling
- **timex**: Date/time utilities

---

## 8. Security & Compliance

### 8.1 Security Measures
✅ **Encryption**: AES-256 at rest, TLS 1.2+ in transit  
✅ **Signature Verification**: RSA/ECDSA for merchant transactions  
✅ **API Key Rotation**: Automatic rotation with grace period  
✅ **Rate Limiting**: Prevent brute force and DDoS  
✅ **Input Validation**: Strict payload validation  
✅ **SQL Injection Prevention**: Parameterized queries via Ecto  
✅ **CSRF Protection**: Token-based verification  
✅ **Audit Trails**: Immutable event chains for all transactions  

### 8.2 Compliance
✅ **NPCI Compliance**: Follow UPI/BHIM specifications  
✅ **PCI DSS**: Payment card data security standards  
✅ **KYC**: Know Your Customer requirements  
✅ **AML**: Anti-money laundering checks  
✅ **Data Retention**: Compliance with RBI guidelines  
✅ **Regulatory Reporting**: Settlement and dispute reconciliation  

---

## 9. Functional Requirements

### 9.1 Transaction Flow
1. **Receive ReqValQr** → Parse XML → Generate verification token
2. **Validate QR** → Check merchant → Verify expiry → Create record
3. **Return RespValQr** → Send ACK with token
4. **Async Processing** → Task spawned for additional validation
5. **Receive ReqPay** → Validate token → Process payment
6. **Update Status** → Success/Error/Reversal
7. **Generate Settlement** → Calculate fees → Create batch
8. **Reconcile** → Match UTXN → Update dispute status

### 9.2 Merchant Operations
1. **Merchant Onboarding** → KYC verification → Profile creation
2. **QR Generation** → Create QR code → Store in system
3. **Timeout Handling** → Special VPAs trigger timeout scenarios
4. **Invoice Management** → Track payment invoices
5. **Settlement Reporting** → View settlement details

### 9.3 Admin Operations
1. **View Dashboard** → KPIs, metrics, recent transactions
2. **Manage Users** → Create, edit, delete users
3. **Manage Merchants** → Onboard, update, deactivate
4. **Configure Settings** → Fees, limits, timeouts
5. **View Audit Logs** → Transaction event chains
6. **Monitor Health** → System performance and alerts

---

## 10. Non-Functional Requirements

### 10.1 Performance
- **Transaction Latency**: < 100ms for sync operations
- **Throughput**: 10,000+ TPS (transactions per second)
- **Settlement Batch**: Complete within 30 minutes
- **API Response Time**: < 500ms for most endpoints

### 10.2 Scalability
- **Horizontal Scaling**: Support load balancing
- **Database Pooling**: Connection pooling for high concurrency
- **Caching**: Redis for frequently accessed data
- **Async Processing**: Task-based background jobs

### 10.3 Availability
- **Uptime SLA**: 99.95% availability
- **Recovery**: < 5 minute recovery from failure
- **Backup**: Daily database backups + WAL replication
- **Monitoring**: 24/7 system monitoring with alerts

### 10.4 Reliability
- **Error Rate**: < 0.1% transaction failure rate
- **Idempotency**: Duplicate requests handled gracefully
- **Retry Logic**: Exponential backoff for failed requests
- **Data Consistency**: ACID compliance for critical operations

---

## 11. Success Metrics

| Metric | Target | Status |
|--------|--------|--------|
| Transaction Success Rate | 99.5% | ✅ |
| Average Response Time | < 100ms | ✅ |
| System Uptime | 99.95% | ✅ |
| Merchant Onboarding | < 2 hours | ✅ |
| Settlement Accuracy | 100% | ✅ |
| Audit Trail Completeness | 100% | ✅ |
| API Availability | 99.99% | ✅ |

---

## 12. Risks & Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| Duplicate transaction processing | Medium | High | Unique token + DB constraint |
| FX rate fluctuation | Medium | Medium | Rate locking + hedging |
| Settlement batch failure | Low | High | Retry logic + manual reconciliation |
| Merchant timeout abuse | Low | Medium | Rate limiting + monitoring |
| Security breach | Low | Critical | Encryption + audit trails |

---

## 13. Release Notes

**v1.0 - Current Release**
- ✅ Core transaction processing
- ✅ QR validation (dynamic & static)
- ✅ International payment corridors
- ✅ Settlement batch generation
- ✅ Dispute handling
- ✅ Audit trail implementation
- ✅ API key management
- ✅ Feature flags

---

## 14. Next Steps

1. **Phase 2**: Enhanced analytics and reporting
2. **Phase 3**: Mobile app integration
3. **Phase 4**: Additional international corridors
4. **Phase 5**: Machine learning fraud detection
5. **Phase 6**: Customer portal for merchants