IFSC Verification & Banking Intelligence API

Enterprise-grade IFSC verification, bank lookup, MICR search, SWIFT finder, and bulk verification API built for the Apify platform. Cross-verified from RBI, NPCI, Razorpay, and multiple banking sources.

Features

Core Features

• IFSC Validation - Validate IFSC code format and bank code existence
• IFSC Lookup - Get complete branch details by IFSC code
• MICR Lookup - Search branches by MICR code
• SWIFT Finder - Find branches by SWIFT/BIC code
• Bank Search - Search by bank name or bank code
• Branch Search - Search by branch name with fuzzy matching
• Location Search - Find branches by state, district, city, or pincode
• Bulk Verification - Verify thousands of IFSC codes (CSV, Excel, JSON, Text)
• Verification Report - Cross-source verification with confidence scoring
• Auto-complete - Suggestions for partial inputs
• Duplicate Detection - Find duplicate branches within a bank

Payment Capabilities

• UPI (Unified Payments Interface)
• NEFT (National Electronic Funds Transfer)
• RTGS (Real Time Gross Settlement)
• IMPS (Immediate Payment Service)
• ECS (Electronic Clearing Service)
• ACH Credit/Debit
• NACH Debit
• BBPS (Bharat Bill Payment System)
• AEPS (Aadhaar Enabled Payment System)

Data Sources

• RBI - Reserve Bank of India official data
• NPCI - National Payments Corporation of India
• Razorpay IFSC - Comprehensive IFSC database
• Bank Websites - Official bank branch pages
• Open Government Datasets - Public banking data

Tech Stack

• Runtime: Node.js 22+
• Language: TypeScript 5.7+
• Framework: Apify SDK 3.x, Crawlee 3.x
• API: Express.js 4.x
• Validation: Zod, Joi
• HTTP Client: Axios
• HTML Parsing: Cheerio
• Caching: node-cache
• CSV/Excel: PapaParse, xlsx
• Fuzzy Search: Fuse.js
• Logging: Pino
• Testing: Jest, Supertest
• Linting: ESLint, Prettier

Quick Start

Prerequisites

• Node.js 22+ and npm
• Apify CLI (optional, for deployment)

Installation

# Clone the repository
git clone https://github.com/your-org/ifsc-verification-actor.git
cd ifsc-verification-actor

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

Environment Variables

# Required
APIFY_LOG_LEVEL=INFO

# Optional
CACHE_TTL_SECONDS=3600
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000
MAX_CONCURRENT_REQUESTS=10
RETRY_ATTEMPTS=3
RETRY_DELAY_MS=1000
ENABLE_SCRAPING=true
ENABLE_CACHE=true
API_KEY=your-secret-api-key
RAZORPAY_IFSC_API_URL=https://ifsc.razorpay.com

API Endpoints

Validation

POST /api/v1/validate
Content-Type: application/json

{
  "ifsc": "KKBK0000261",
  "micr": "110485003",
  "bankCode": "KKBK",
  "pincode": "122001"
}

Lookup

POST /api/v1/lookup
Content-Type: application/json

{
  "ifsc": "KKBK0000261"
}

Response:

{
  "success": true,
  "data": {
    "ifsc": "KKBK0000261",
    "bank": "Kotak Mahindra Bank",
    "bankCode": "KKBK",
    "branch": "Gurgaon",
    "address": "SCO 16-17, HUDA Market, Sector 14, Gurgaon",
    "contact": "0124-4334000",
    "city": "Gurgaon",
    "district": "Gurgaon",
    "state": "Haryana",
    "centre": "Gurgaon",
    "micr": "110485003",
    "swift": "",
    "upi": true,
    "neft": true,
    "rtgs": true,
    "imps": true,
    "ecs": true,
    "achCredit": true,
    "achDebit": true,
    "nachDebit": true,
    "bbps": true,
    "aeps": false,
    "bankType": "Private",
    "iin": "",
    "bankCodeNumber": "",
    "verified": true,
    "confidence": 99.7,
    "sources": ["Razorpay", "NPCI"],
    "lastUpdated": "2026-07-23T12:00:00.000Z",
    "isActive": true,
    "isMerged": false,
    "isClosed": false
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2026-07-23T12:00:00.000Z",
    "durationMs": 150,
    "apiVersion": "1.0.0",
    "cacheHit": false
  }
}

Search

POST /api/v1/search
Content-Type: application/json

{
  "bankName": "Kotak Mahindra",
  "searchMode": "contains"
}

Bulk Verification

POST /api/v1/bulk
Content-Type: application/json

{
  "items": ["KKBK0000261", "SBIN0005943", "HDFC0001234"],
  "format": "json"
}

Verification Report

POST /api/v1/verify
Content-Type: application/json

{
  "ifsc": "KKBK0000261"
}

Auto-complete Suggestions

$GET /api/v1/suggest?q=Kot&field=bank&limit=10

Suggest Correct IFSC

$GET /api/v1/suggest-ifsc?q=KKBK000026

Duplicate Detection

$GET /api/v1/duplicates/KKBK

Search Modes

Mode	Description
exact	Exact match
contains	Partial match (substring)
startsWith	Prefix match
endsWith	Suffix match
fuzzy	Fuzzy matching with confidence score
regex	Regular expression matching

Output Formats

Format	Content-Type	Description
json	application/json	Default JSON response
csv	text/csv	CSV download
excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Excel download
dataset	-	Apify Dataset output

Deployment

Apify Platform

# Install Apify CLI
npm install -g apify-cli

# Login
apify login

# Push to Apify
npm run apify:push

# Run on Apify
npm run apify:run

Docker

# Build image
docker build -t ifsc-verification-api .

# Run container
docker run -p 3000:3000 --env-file .env ifsc-verification-api

Local Server

# Development
npm run dev

# Production
npm run build
npm run start:prod

Project Structure

src/
  main.ts              # Entry point (Apify Actor + Express server)
  routes/
    api.routes.ts      # API route definitions
  services/
    ifsc.service.ts    # Core business logic
    export.service.ts  # CSV/Excel export utilities
  validators/
    ifsc.validator.ts  # Input validation
  clients/
    razorpay.client.ts # Razorpay IFSC API client
    rbi.client.ts      # RBI data client
    npci.client.ts     # NPCI data client
  models/
    branch.model.ts    # Branch data model
    bank.model.ts      # Bank data model
  types/
    index.ts           # TypeScript type definitions
  utils/
    logger.ts          # Pino logger configuration
    errors.ts          # Custom error classes
    helpers.ts         # Utility functions
  cache/
    index.ts           # In-memory caching service
  middleware/
    auth.middleware.ts         # API key authentication
    rate-limit.middleware.ts   # Rate limiting
    error.middleware.ts        # Error handling
    logging.middleware.ts      # Request logging
  config/
    index.ts           # Application configuration

tests/
  unit/                # Unit tests
  integration/         # Integration tests
  setup.ts             # Test setup

docs/
  openapi.yaml         # OpenAPI/Swagger documentation

.github/workflows/
  ci.yml               # CI/CD pipeline

Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid input parameters
NOT_FOUND	404	Resource not found
RATE_LIMIT_EXCEEDED	429	Too many requests
EXTERNAL_SERVICE_ERROR	502	Third-party service failure
AUTHENTICATION_ERROR	401	Invalid or missing API key
AUTHORIZATION_ERROR	403	Insufficient permissions
INTERNAL_ERROR	500	Unexpected server error

Caching Strategy

• In-Memory Cache: node-cache with TTL (default 1 hour)
• Cache Keys: lookup:ifsc:{code}, search:{field}:{mode}:{query}, bank:code:{code}
• Cache Invalidation: Automatic TTL expiration, manual flush via /cache/stats
• Hit Rate Tracking: Real-time cache statistics in health endpoint

Rate Limiting

• Default: 100 requests per minute per IP
• Bulk Endpoint: 20 requests per 5 minutes per IP
• Health Check: Exempt from rate limiting
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Retry Logic

• Max Attempts: 3 (configurable)
• Backoff: Exponential with jitter (1s, 2s, 4s max 10s)
• Retryable Errors: 5xx server errors, network timeouts
• Non-Retryable: 4xx client errors, 404 not found

Security

• Helmet.js for security headers
• CORS configuration
• API key authentication (optional)
• Input sanitization
• Rate limiting per IP
• Request logging with redacted sensitive fields

Monitoring

• Structured JSON logging with Pino
• Request/response timing
• Cache hit/miss statistics
• External API call metrics
• Error tracking with stack traces

Performance Optimization

• In-memory caching for frequently accessed data
• Chunked processing for bulk operations
• Connection pooling for HTTP clients
• Compression middleware
• Lazy loading of Fuse.js index

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• Documentation: docs/openapi.yaml
• Issues: GitHub Issues
• Email: support@ifsc-verification.io

---

Built with care for the Indian banking ecosystem.