# IFSC Verification & Banking Intelligence API (`cplegend_robo/ifsc-verification-banking-intelligence`) Actor

Verify IFSC codes, lookup bank branches, check MICR/SWIFT. Cross-verified from RBI, NPCI & Razorpay.

- **URL**: https://apify.com/cplegend\_robo/ifsc-verification-banking-intelligence.md
- **Developed by:** [Chandan Kumar Mishra](https://apify.com/cplegend_robo) (community)
- **Categories:** Developer tools, E-commerce, Open source
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.005 / ifsc verification

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## IFSC Verification & Banking Intelligence API

[![CI/CD](https://github.com/your-org/ifsc-verification-actor/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/ifsc-verification-actor/actions)
[![codecov](https://codecov.io/gh/your-org/ifsc-verification-actor/branch/main/graph/badge.svg)](https://codecov.io/gh/your-org/ifsc-verification-actor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Enterprise-grade IFSC verification, bank lookup, MICR search, SWIFT finder, and bulk verification API built for the [Apify](https://apify.com) 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

```bash
## 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

```env
## 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

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

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

#### Lookup

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

{
  "ifsc": "KKBK0000261"
}
```

**Response:**

```json
{
  "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

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

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

#### Bulk Verification

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

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

#### Verification Report

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

{
  "ifsc": "KKBK0000261"
}
```

#### Auto-complete Suggestions

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

#### Suggest Correct IFSC

```bash
GET /api/v1/suggest-ifsc?q=KKBK000026
```

#### Duplicate Detection

```bash
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

```bash
## 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

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

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

#### Local Server

```bash
## 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](LICENSE) file for details.

### Support

- Documentation: [docs/openapi.yaml](docs/openapi.yaml)
- Issues: [GitHub Issues](https://github.com/your-org/ifsc-verification-actor/issues)
- Email: support@ifsc-verification.io

***

Built with care for the Indian banking ecosystem.

# Actor input Schema

## `action` (type: `string`):

The operation to perform

## `ifsc` (type: `string`):

Indian Financial System Code (e.g., KKBK0000261)

## `bankCode` (type: `string`):

4-character bank code (e.g., KKBK)

## `bankName` (type: `string`):

Full or partial bank name (e.g., Kotak Mahindra)

## `branch` (type: `string`):

Branch name or partial match

## `city` (type: `string`):

City name

## `district` (type: `string`):

District name

## `state` (type: `string`):

State name

## `micr` (type: `string`):

9-digit MICR code (e.g., 110485003)

## `swift` (type: `string`):

SWIFT/BIC code

## `pincode` (type: `string`):

6-digit Indian PIN code

## `bulk` (type: `array`):

Array of IFSC codes for bulk verification

## `searchMode` (type: `string`):

Search matching strategy

## `outputFormat` (type: `string`):

Format for results

## `includeMetadata` (type: `boolean`):

Include additional metadata like geo coordinates, holidays, etc.

## `confidenceThreshold` (type: `integer`):

Minimum confidence score (0-100) for fuzzy matches

## Actor input object example

```json
{
  "action": "validate",
  "searchMode": "exact",
  "outputFormat": "json",
  "includeMetadata": false,
  "confidenceThreshold": 80
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("cplegend_robo/ifsc-verification-banking-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("cplegend_robo/ifsc-verification-banking-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call cplegend_robo/ifsc-verification-banking-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=cplegend_robo/ifsc-verification-banking-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/QAraxJ3jbjreXkkUc/builds/mo2q5jzVZhtbFPvHZ/openapi.json