# UPI PSP Next Phase Implementation Plan

## Current State Assessment ✅

### Completed Components
- ✅ Database schema with hash-chained events
- ✅ Transaction state machine (initiated → success/failure/deemed)
- ✅ Timeout escalation (ChkTxn → Reversal → Deemed)
- ✅ REST API endpoints with JSON responses
- ✅ Sandbox partner adapter
- ✅ Watchdog process for timeout handling
- ✅ Basic XML parser scaffold
- ✅ SaaS Kit integration layer

### Current Limitations
- ❌ XML parser only handles basic fields (missing 80% of UPI spec)
- ❌ Sandbox partner (no real international partner integration)
- ❌ No authentication/authorization
- ❌ No webhook endpoints for partner callbacks
- ❌ Limited error code taxonomy (only 4 codes)
- ❌ No comprehensive test suite
- ❌ No rate limiting or security measures

## Phase 5 Priority Plan 🎯

### **Phase 5A: Complete XML Parser (High Priority)**
**Goal**: Full UPI specification compliance for XML parsing

**Implementation Order**:
1. **ReqValQr Extended Parser** - Add all missing fields per UPI spec
2. **RespValQr Parser** - Handle validation responses  
3. **ReqPay Parser** - Payment request parsing
4. **RespPay Parser** - Payment response parsing
5. **ReqChkTxn/RespChkTxn** - Transaction status check
6. **ReqReversal/RespReversal** - Reversal request/response

**Technical Details**:
- Extend `ValQrParser` with complete field mapping
- Add validation for mandatory vs optional fields
- Handle multiple FX quotes and complex nested structures
- Add comprehensive error handling for malformed XML

### **Phase 5B: Real Partner Integration (High Priority)**
**Goal**: Replace sandbox with actual international partner APIs

**Implementation Steps**:
1. **Partner Configuration System** - Environment-based partner selection
2. **HTTP Client Wrapper** - Robust HTTP handling with retries
3. **Real Partner Adapter** - Implement actual partner API calls
4. **Response Code Expansion** - Complete UPI response code taxonomy
5. **Error Classification** - Map partner errors to UPI standard codes
6. **Timeout Handling** - Real-world timeout scenarios

### **Phase 5C: Webhook Infrastructure (Medium Priority)**
**Goal**: Handle asynchronous partner callbacks

**Components**:
1. **Webhook Endpoints** - Secure callback receivers
2. **Signature Verification** - Partner authentication
3. **Idempotency Handling** - Prevent duplicate processing
4. **Event Correlation** - Match callbacks to transactions

### **Phase 5D: Security & Production Readiness (Medium Priority)**
**Goal**: Production-grade security and reliability

**Features**:
1. **API Authentication** - JWT/API key based auth
2. **Rate Limiting** - Per-client request limits
3. **Input Validation** - Comprehensive request validation
4. **Audit Logging** - Enhanced security logging
5. **Health Checks** - System monitoring endpoints

## Recommended Implementation Order

### **Week 1-2: Phase 5A - XML Parser Completion**
- Start with ReqValQr extended parsing
- Add comprehensive field validation
- Extend to other UPI message types
- **Deliverable**: Full UPI XML spec compliance

### **Week 3-4: Phase 5B - Partner Integration** 
- Design real partner adapter interface
- Implement HTTP client with error handling
- Add complete response code taxonomy
- **Deliverable**: Production partner integration

### **Week 5: Phase 5C - Webhook Infrastructure**
- Build webhook receivers
- Add signature verification
- Implement idempotency
- **Deliverable**: Async callback handling

### **Week 6: Phase 5D - Security & Testing**
- Add authentication layer
- Implement rate limiting
- Build comprehensive test suite
- **Deliverable**: Production-ready system

## Technical Specifications

### XML Parser Enhancement
```elixir
# Extended field mapping for ReqValQr
defmodule UpiXmlParser do
  @reqvalqr_fields %{
    # Header fields
    "msgId" => :msg_id,
    "ts" => :timestamp,
    "orgId" => :org_id,
    "channelId" => :channel_id,
    
    # QR fields  
    "addr" => :payee_addr,
    "mid" => :payee_mid,
    "tid" => :terminal_id,
    "mc" => :merchant_code,
    "purpose" => :purpose_code,
    "am" => :amount,
    "cu" => :currency,
    "tn" => :transaction_note,
    
    # Additional fields per UPI spec...
  }
end
```

### Partner Configuration
```elixir
config :da_product_app, :partners,
  primary: %{
    module: RealPartnerAdapter,
    base_url: "https://partner-api.com",
    api_key: {:system, "PARTNER_API_KEY"},
    timeout: 30_000,
    retries: 3
  },
  fallback: %{
    module: SandboxPartner,
    enabled: true
  }
```

### Authentication Strategy
```elixir
# JWT-based API authentication
defmodule ApiAuthPlug do
  def init(opts), do: opts
  
  def call(conn, _opts) do
    case get_req_header(conn, "authorization") do
      ["Bearer " <> token] -> verify_jwt(conn, token)
      _ -> unauthorized(conn)
    end
  end
end
```

## Success Metrics

### Phase 5A Success Criteria
- [ ] Parse all UPI message types (ReqValQr, RespValQr, ReqPay, etc.)
- [ ] Handle all mandatory and optional fields per UPI spec
- [ ] 100% XML validation compliance
- [ ] Comprehensive error messages for malformed XML

### Phase 5B Success Criteria  
- [ ] Replace sandbox with real partner integration
- [ ] Handle all UPI response codes (200+ codes)
- [ ] Implement proper retry logic with exponential backoff
- [ ] Error recovery and fallback mechanisms

### Phase 5C Success Criteria
- [ ] Secure webhook endpoints with signature verification
- [ ] Idempotent callback processing
- [ ] Event correlation and state updates
- [ ] Webhook retry mechanism for failed deliveries

### Phase 5D Success Criteria
- [ ] API authentication and authorization
- [ ] Rate limiting (1000 req/min per client)
- [ ] Comprehensive test coverage (>90%)
- [ ] Production monitoring and alerting

## Risk Assessment

### **High Risk Items**
1. **Partner API Changes** - External dependency on partner APIs
2. **UPI Spec Compliance** - Complex XML validation requirements
3. **Security Vulnerabilities** - Payment system security critical

### **Medium Risk Items** 
1. **Performance Under Load** - Need load testing
2. **Database Migration** - Schema changes for new fields
3. **Webhook Reliability** - Network failure scenarios

### **Mitigation Strategies**
- Comprehensive testing at each phase
- Feature flags for gradual rollout
- Monitoring and alerting at every level
- Documentation and runbooks

## Implementation Decision

**Recommendation**: Start with **Phase 5A (XML Parser)** as it's the foundation for everything else.

Would you like me to begin implementing the complete XML parser for ReqValQr, or would you prefer to start with a different phase?