ifsc 0.1.1

A fast offline directory for Indian bank branches and IFSCs
Documentation

IFSC

A fast offline Rust directory for Indian bank branches and Indian Financial System Codes (IFSCs).

The crate bundles a versioned snapshot generated only from Razorpay's IFSC data. It does not perform network or filesystem I/O at runtime. Exact lookups and record access borrow from the bundled directory without decoding the complete snapshot.

let code = ifsc::parse("HDFC0000001")?;

if let Some(branch) = code.branch() {
    println!("{}", branch.name());
}
# Ok::<(), ifsc::Error>(())

Parsing and directory membership are separate. A parsed Ifsc matches the IFSC grammar. Ifsc::branch returning a branch means only that the code occurs in the bundled Razorpay snapshot. Neither result proves that a branch is open, an account exists, a beneficiary owns an account, or a payment can complete.

Operations

  • parse accepts one IFSC of at most 64 bytes, trims surrounding ASCII whitespace, and normalizes ASCII lowercase letters.
  • parse_strict accepts only the canonical 11-character uppercase form.
  • Ifsc owns a canonical code and exposes its routing code.
  • lookup and Ifsc::branch find exact branch metadata in the bundled snapshot.
  • lookup_str combines convenience parsing with exact directory lookup.
  • directory provides deterministic branch and bank iteration, exact reverse lookups, and paged searches.
  • Branch exposes Razorpay's branch name, reported bank name, address, location, contact, MICR, SWIFT, and reported payment-rail fields.
  • Bank and BankProfile expose Razorpay's bank-level metadata separately from branch-level metadata.
  • BranchQuery and BankQuery compose source-backed filters with bounded result pages.
  • dataset identifies the Razorpay release, source commit, and RBI update date.
  • Directory::statistics reports snapshot counts and field coverage.

Lookup

Use a parsed code when the caller already handles syntax errors:

let code = ifsc::parse("HDFC0000001")?;
match ifsc::lookup(code) {
    Some(branch) => println!("{}", branch.address()),
    None => println!("not present in the bundled snapshot"),
}
# Ok::<(), ifsc::Error>(())

Use lookup_str at a boundary that wants one convenience operation:

let branch = ifsc::lookup_str(" hdfc0000001 ")?;
assert_eq!(branch.map(|branch| branch.ifsc()), Some(ifsc::parse_strict("HDFC0000001")?));
# Ok::<(), ifsc::Error>(())

A well-formed code absent from the snapshot returns None. Absence is not a parse error.

Directory search

Searches return paged records in the requested deterministic order. Branches default to IFSC order, and banks default to bank-code order. A page limit cannot exceed 10,000 records.

use ifsc::{BranchQuery, LocationField, SearchOptions};

let matches = ifsc::directory().search_branches(
    &BranchQuery::new().with_location(LocationField::State, "KARNATAKA"),
    SearchOptions::default(),
)?;

for branch in matches {
    println!("{}", branch.ifsc());
}
# Ok::<(), ifsc::Error>(())

Branch searches can use the source-backed fields represented by BranchQuery, including routing code, sub-member bank, location, MICR, SWIFT, branch name, bank name, and reported payment rail. Bank searches use BankQuery and bank-level services. Exact reverse lookups retain all matches because values such as MICR and SWIFT are not assumed to be unique.

Search terms are matched as provided. Structured query fields do not trim whitespace. Location and MICR filters compare bytes exactly. SWIFT and IFSC prefix filters ignore ASCII letter case. Text queries select exact-byte or ASCII-insensitive matching explicitly.

Searches scan the bundled directory. IFSC- and bank-code-ordered searches allocate only the requested page. Other orders collect and sort all matches before applying the page. Page and text limits bound result size and input size, not total scan work. The library does not perform Unicode normalization, fuzzy correction, regular-expression matching, address correction, or geocoding. Consult the rustdoc for exact term and result limits.

Bank and payment semantics

The following concepts can differ and remain separate in the API:

  • The four-character routing code encoded in an IFSC.
  • The bank name reported on a branch record.
  • A bank profile from Razorpay's bank-level data.
  • A sub-member institution that uses another bank's routing prefix.

BranchRail describes a branch-level value such as NEFT, RTGS, IMPS, or UPI. BankService describes bank-level values supplied by Razorpay. A ReportedStatus is snapshot data, not a live availability result. The library does not combine branch rails with bank services or describe them as capabilities.

Missing values

Razorpay records contain missing and inconsistent metadata. Accessors return Option when a source value can be absent. Contact values, MICR codes, SWIFT codes, IINs, and similar identifiers remain strings. The crate preserves non-empty source text instead of inventing values or coercing it into numeric types.

Features

The complete offline directory and search API are available by default. The only optional feature is:

  • serde: serialize and strictly deserialize stable semantic identifiers.

Snapshot-relative handles such as Branch and Bank do not serialize. Their private row identifiers are meaningful only for one data version.

The crate requires std. Its API is synchronous, runtime-neutral, dependency-free by default, and implemented in safe Rust. No storage type or binary-layout detail appears in the public API. IFSC supports the workspace's minimum Rust version and is checked for wasm32-wasip1.

Data and updates

The bundled snapshot is Razorpay IFSC v2.0.61, which reports an RBI update date of 2026-06-30.

Normal builds use committed artifacts and never download data. The repository-only Rust generator downloads explicitly pinned Razorpay inputs, checks each SHA-256 digest, validates their schemas and limits, and emits one deterministic binary artifact. DATA_VERSION and dataset identify the snapshot. Updating the data can change lookup, metadata, and search results.

The crate uses only Razorpay data. It does not merge RBI, NPCI, bank websites, geocoders, or another directory. Razorpay's own transformations and source limitations therefore remain present, including reported service flags and incomplete sub-member coverage.

Non-goals

IFSC does not provide:

  • Account-number, account-holder, or beneficiary verification.
  • Proof that a branch is open or operational.
  • Live NEFT, RTGS, IMPS, UPI, ACH, APBS, or NACH availability.
  • Payment initiation, routing, fraud detection, or compliance decisions.
  • Branch history, merger history, geocoding, or address correction.
  • Runtime data downloads or automatic updates.

Applications making payments or consequential decisions must use an appropriate live, authoritative service in addition to this offline snapshot.

License

The IFSC implementation is licensed under MIT. The bundled snapshot is derived from Razorpay's public-domain IFSC dataset. See the third-party notice for source and license information. dataset identifies the bundled release.