Skip to main content

TSD - Bank Verification

Document Control​

VersionDateAuthorDescription
1.02025-09-22BA TeamInitial Version

Table of Contents​

  1. Overview
  2. Technology Stack
  3. System Architecture Overview
  4. Functional Overview
  5. User Interface
  6. Technical Specification
  7. Integration Requirements
  8. Authentication
  9. Security Considerations
  10. Error Handling
  11. Performance Considerations
  12. Testing Strategy
  1. Monitoring and Analytics
  1. Deployment Considerations
  1. Future Enhancements

1. Overview​

1.1 Purpose​

The Bank Verification feature in the OX Agry application enables users to securely link their bank accounts to facilitate seamless transactions, wallet operations, and payments across agricultural services such as equipment booking, trade, and financial aggregations. This feature ensures that bank details are verified through secure APIs, promoting trust and compliance with financial regulations in India.

1.2 Scope​

The specification covers:

  • Bank account registration and verification process
  • Multi-account management capabilities
  • Primary account designation system
  • Secure banking API integration
  • User interface components and flows
  • Backend architecture and data models
  • Security and compliance requirements

2. Technology Stack​

2.1 Frontend Technologies​

  • Framework: Tanstack with TypeScript
  • Routing: Tanstack Router for navigation management
  • Forms: Tanstack Form for form state management
  • Data Fetching: Apollo Client for GraphQL operations
  • State Management: React Context API with hooks
  • UI Components: Custom component library with status-aware components

2.2 Backend Technologies​

  • Framework: NestJS with TypeScript
  • API Layer: GraphQL with Apollo Server
  • Database ORM: Prisma ORM
  • Authentication: JWT tokens with refresh mechanism
  • File Storage: Cloud storage integration
  • Validation: Class-validator and class-transformer

2.3 Banking Integration​

  • Open Banking APIs
  • Bank-specific API integrations
  • Encryption libraries (AES-256, RSA)
  • SSL/TLS for secure communication

3. System Architecture Overview​

3.1 Component Interaction Flow​

Mobile App → API Gateway → Bank Service → Banking APIs
     ↓           ↓              ↓
User State → Cache Layer → Database

3.2 High-Level Process Flow​

  1. User initiates bank account addition
  2. System validates account information format
  3. Secure API call to banking service for verification
  4. Bank details retrieved and encrypted storage
  5. Account confirmation and primary designation
  6. Integration with wallet operations

4. Functional Overview​

4.1 Bank Account Registration Flow​

4.1.1 Initial Account Setup​

  • Display informational screen explaining bank connection benefits
  • Present security assurance messaging
  • Guide user through required information collection
  • Initiate secure connection establishment

4.1.2 Account Information Input​

  • Account Number Input:

    • 10-16 digit validation
    • Real-time format checking
    • Masked display for security
    • Copy-paste functionality with validation

  • IFSC Code Input:

    • 11-character alphanumeric validation
    • Auto-completion from bank database
    • Format verification (4 letters + 7 characters)
    • Bank name auto-population

4.1.3 Bank API Verification​

  • Secure API call to banking service
  • Account existence validation
  • Account holder name verification
  • Branch information retrieval
  • Account status checking

4.1.4 Account Confirmation​

  • Display retrieved account details
  • Show bank name, branch, and account holder information
  • Allow user to confirm or cancel
  • Generate verification timestamp

4.1.5 Multi-Account Management​

  • Support for multiple bank account connections
  • Primary account designation system
  • Account status tracking (active/inactive)
  • Historical verification tracking

4.2 Account Management Operations​

4.2.1 Setting Primary Account​

  • Single primary account enforcement
  • Automatic wallet integration updates
  • Transaction routing configuration
  • User confirmation requirements

4.2.2 Account Removal​

  • Secure account disconnection process
  • Primary account reassignment logic
  • Transaction history preservation
  • User confirmation with warning messages

4.2.3 Account Status Management​

  • Active/inactive status tracking
  • Automatic status updates from banking APIs
  • Error state handling
  • Re-verification workflows

5. User Interface​

5.1 Bank Account Setup Screens​

5.1.1 Initial Setup Screen​

  • Header: "Bank Accounts" with close/back navigation
  • Information Panel: Informational box explaining connection benefits
  • Requirements List: Account number and IFSC code requirements
  • Primary CTA: "Add Bank Account" button

5.1.2 Account Information Entry Modal​

  • Modal Header: "Bank Account" with close button
  • Form Fields:
    • Account Number: Numeric input with placeholder "1234567890"
    • IFSC Code: Alphanumeric input with placeholder "HDFC0004842"
  • Security Notice: Warning box with encryption and verification messaging
  • Action Buttons: "Cancel" (secondary) and "Verify" (primary)
  • Validation: Real-time field validation with error states

5.1.3 Verification Confirmation Modal​

  • Account Details Display:
    • Account Number (read-only)
    • IFSC Code (read-only)
    • Bank Name (auto-populated)
    • Branch Name (auto-populated)
  • Action Buttons: "Cancel" and "Confirm"
  • Loading States: Progress indicators during verification

5.2 Account Management Dashboard​

5.2.1 Multiple Account Display​

  • Card-based Layout: Individual cards for each connected account
  • Account Information Display:
    • Bank name with verified checkmark
    • Account number (partially masked)
    • IFSC code
    • Branch name
    • Verification date

5.2.2 Primary Account Indication​

  • Visual Indicator: "Primary" badge
  • Distinction: Clear visual differentiation from secondary accounts
  • Easy Identification: Prominent placement and styling

5.2.3 Account Action Controls​

  • Primary Account Actions:
    • "Remove primary" button
    • "Remove account" button
  • Secondary Account Actions:
    • "Set As primary" button
    • "Remove account" button
  • Add Bank Account: Floating action button or header button

6. Technical Specification​

6.1 Frontend Implementation​

6.1.1 Account Setup Component​

  • Component Structure: Modal-based setup flow with form validation
  • State Management: Handle form data, verification status, and loading states
  • Validation Logic:
    • Account number: 10-16 digit numeric validation
    • IFSC code: 11-character alphanumeric format validation (4 letters + 7 characters)
  • User Experience: Real-time validation feedback and error handling
  • API Integration: Asynchronous verification with loading indicators

6.1.2 Account Information Modal​

  • Modal Design: Semi-transparent overlay with centered content container
  • Form Elements:
    • Account number input with numeric keyboard and 16-character limit
    • IFSC code input with auto-capitalization and 11-character limit
  • Security Notice: Yellow-background warning box with shield icon
  • Action Buttons: Cancel (secondary) and Verify (primary) with loading states
  • Accessibility: Proper labeling and screen reader support

6.1.3 Account Management Dashboard​

  • Layout Structure: Header with title and add button, scrollable account list
  • Account Cards: Individual cards displaying bank information with action buttons
  • State Management: Handle account list, loading states, and user interactions
  • Primary Account Logic: Ensure only one account can be marked as primary
  • Interactive Elements: Set primary and remove account functionality with confirmation dialogs

6.2 Backend Implementation​

6.2.1 Database Schema​

-- Bank Accounts Table
CREATE TABLE bank_accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    account_number_encrypted TEXT NOT NULL,
    account_number_hash TEXT NOT NULL,
    ifsc_code VARCHAR(11) NOT NULL,
    bank_name VARCHAR(100) NOT NULL,
    branch_name VARCHAR(200) NOT NULL,
    account_holder_name_encrypted TEXT,
    is_primary BOOLEAN DEFAULT FALSE,
    is_verified BOOLEAN DEFAULT FALSE,
    verification_date TIMESTAMP WITH TIME ZONE,
    status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'error')),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(user_id, account_number_hash),
    UNIQUE(user_id, is_primary) WHERE is_primary = TRUE
);

6.2.2 GraphQL Schema​

type BankAccount {
  id: ID!
  accountNumber: String! # Masked for security
  ifscCode: String!
  bankName: String!
  branchName: String!
  accountHolderName: String
  isPrimary: Boolean!
  isVerified: Boolean!
  verificationDate: DateTime
  status: BankAccountStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum BankAccountStatus {
  ACTIVE
  INACTIVE
  ERROR
}

input AddBankAccountInput {
  accountNumber: String!
  ifscCode: String!
}

input UpdateBankAccountInput {
  id: ID!
  isPrimary: Boolean
  status: BankAccountStatus
}

type BankVerificationResult {
  isValid: Boolean!
  bankName: String
  branchName: String
  accountHolderName: String
  errorMessage: String
}

type Query {
  getBankAccounts: [BankAccount!]!
  getPrimaryBankAccount: BankAccount
  verifyBankAccount(input: AddBankAccountInput!): BankVerificationResult!
}

type Mutation {
  addBankAccount(input: AddBankAccountInput!): BankAccount!
  updateBankAccount(input: UpdateBankAccountInput!): BankAccount!
  deleteBankAccount(id: ID!): Boolean!
  setPrimaryBankAccount(id: ID!): BankAccount!
}

type Subscription {
  bankAccountStatusUpdated(userId: ID!): BankAccount!
}

7. Integration Requirements​

Banking APIs:

  • Integration with major Indian banks (HDFC, SBI, ICICI, Axis, etc.)
  • Open Banking API compliance
  • Real-time account verification
  • Account balance inquiry (if required)
  • Transaction history access (future enhancement)

Internal Systems:

  • User authentication service integration
  • Wallet service integration for payment routing
  • Notification service for status updates
  • Audit logging service for compliance
  • Analytics service for user behavior tracking

Third-party Services:

  • SMS/Email notification providers
  • Encryption key management services
  • Monitoring and alerting platforms
  • Compliance and regulatory reporting tools

8. Authentication​

User Authentication:

  • JWT-based authentication required for all bank-related operations
  • Multi-factor authentication for sensitive operations
  • Session management with automatic timeout

API Authentication:

  • API key management and rotation
  • Rate limiting per authenticated user

Authorization Levels:

  • User-level: Basic account operations
  • Admin-level: Account management and monitoring
  • System-level: Automated verification processes
  • Audit-level: Read-only access for compliance

9. Security Considerations​

Data Encryption:

  • AES-256 encryption for account numbers at rest
  • RSA encryption for API communications
  • End-to-end encryption for sensitive data transmission
  • Regular key rotation and management

PCI DSS Compliance:

  • Secure storage of financial data
  • Regular security audits and assessments
  • Secure development lifecycle practices
  • Employee access controls and monitoring

Banking Regulations:

  • RBI compliance for financial data handling
  • GDPR compliance for user data protection
  • Regular penetration testing and vulnerability assessments

Security Measures:

  • Input validation and sanitization
  • SQL injection prevention
  • Cross-site scripting (XSS) protection
  • Rate limiting and DDoS protection
  • Secure session management
  • Regular security patch updates

10. Error Handling​

User-Friendly Error Messages:

  • Clear, actionable error messages
  • Multilingual support
  • Progressive error disclosure
  • Recovery suggestions and help links
  • Contact support options for unresolved issues

Error Recovery Strategies:

  • Automatic retry mechanisms with exponential backoff
  • Fallback to alternative API providers
  • Graceful degradation of features
  • Offline capability with sync when online
  • User notification of temporary service issues

11. Performance Considerations​

Response Time Targets:

  • Account verification: < 3 seconds
  • Account listing: < 500ms
  • Account updates: < 1 second
  • Primary account switching: < 800ms

Optimization Strategies:

  • Redis caching for frequently accessed bank data
  • Connection pooling for database operations
  • Asynchronous processing for non-critical operations
  • CDN integration for static assets
  • Database query optimization with proper indexing

Scalability Requirements:

  • Support for 100,000+ concurrent users
  • Horizontal scaling capability
  • Load balancing across multiple instances
  • Database sharding strategies
  • Microservices architecture for independent scaling

12. Testing Strategy​

12.1 Unit Testing​

  • Test individual components: IFSC validator, GraphQL resolvers using Jest.

12.2 Integration Testing​

  • End-to-end API testing with real banking APIs in sandbox mode
  • Database integration testing with test data
  • Authentication and authorization flow testing
  • Error handling and recovery testing
  • Performance testing under various load conditions

12.3 User Acceptance Testing​

  • Usability testing with real users
  • Accessibility testing for compliance
  • Cross-platform testing (iOS, Android)
  • Security penetration testing
  • Compliance validation testing

13. Monitoring and Analytics​

13.1 Key Metrics​

  • Verification Success Rate: Target >95%
  • API Response Time: Target <3 seconds
  • Error Rate: Target <2%
  • User Completion Rate: Target >90%
  • Primary Account Setup Rate: Target >80%

13.2 Alerting​

  • API failure rate exceeding threshold
  • Verification success rate dropping below 90%
  • Unusual error patterns or spikes
  • Security-related events and anomalies
  • Performance degradation alerts

13.3 Logging​

  • Log all API calls with anonymized data using ELK stack.

14. Deployment Considerations​

14.1 Environment Variables​

  • API keys for banking integrations stored in .env (e.g., RAZORPAY_KEY).

14.2 Feature Flags​

  • bank_verification_enabled: Master toggle for bank verification feature
  • multiple_accounts_enabled: Enable multiple bank account support
  • primary_account_switching: Enable primary account switching
  • advanced_verification: Enable enhanced verification methods
  • bank_api_fallback: Enable API provider fallback mechanism

14.3 Rollback Strategy​

  • Blue-green deployment for zero-downtime updates
  • Database migration rollback scripts
  • Feature flag-based rollback capability
  • API versioning for backward compatibility
  • Monitoring-driven automatic rollback triggers

15. Future Enhancements​

Phase 2 Features:

  • Account balance inquiry integration
  • Transaction history viewing
  • Automated bank statement parsing
  • UPI ID integration and management
  • Multi-currency account support

Phase 3 Features:

  • AI-powered fraud detection
  • Predictive account verification
  • Advanced analytics and insights
  • Open banking marketplace integration
  • Cryptocurrency wallet integration

Long-term Vision:

  • Complete financial ecosystem integration
  • Personal finance management tools
  • Investment portfolio integration
  • Credit scoring and lending features
  • International banking support