Skip to main content

Crate ifsc

Crate ifsc 

Source
Expand description

§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());
}

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"),
}

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")?));

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

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());
}

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.

Structs§

Bank
A bank-name entry in the bundled Razorpay snapshot.
BankCode
A four-character code used by Razorpay’s bank and sub-member records.
BankMatches
An exact-size iterator over one page of bank matches.
BankNameQuery
A configurable text condition for bank-name search.
BankProfile
Bank-level metadata reported by Razorpay.
BankProfiles
An exact-size iterator over bank metadata profiles.
BankQuery
Composable filters and ordering for bank search.
Banks
An iterator over banks, optionally constrained by a directory filter.
Branch
An immutable branch record in the bundled snapshot.
BranchMatches
An exact-size iterator over one page of branch matches.
BranchQuery
Composable filters and ordering for branch search.
BranchRails
The set of payment rails reported for a branch.
BranchTextQuery
A configurable text condition for branch search.
Branches
An iterator over branches, optionally constrained by a directory filter.
Coverage
Coverage of one field in the bundled branch directory.
CustomSubletMatches
Matches custom Razorpay sub-member prefixes for one IFSC.
Dataset
Identifies the immutable Razorpay snapshot bundled with this crate.
Directory
A zero-sized handle to the embedded Razorpay IFSC directory.
Error
A redacted IFSC parsing or query error.
Ifsc
A canonical 11-character Indian Financial System Code.
IsoSubdivision
A canonical ISO 3166-2 subdivision code for India.
Page
Zero-based offset and maximum result count for one search page.
RoutingCode
The four-character routing prefix encoded in an IFSC.
SearchOptions
Resource limits and paging controls for a search.
Statistics
Aggregate facts derived from the bundled Razorpay snapshot.
SubletMatch
One exact or prefix sub-member match.

Enums§

BankKind
A bank classification reported by Razorpay.
BankOrder
Sort order for bank search results.
BankService
A bank-level service represented in Razorpay metadata.
BranchOrder
Sort order for branch search results.
BranchRail
A branch-level payment rail reported by Razorpay.
BranchTextField
A branch field available to text matching.
ErrorKind
A stable category for an IFSC operation failure.
LocationField
A source location field available to branch filters.
ReportedStatus
Razorpay’s reported state for a bank-level service.
SearchCase
Case handling for text comparisons.
SubletSource
The Razorpay mapping that produced a sub-member match.
SubletTarget
The institution reported for a sub-member mapping.
TextMatch
How a text query matches a field value.

Constants§

DATA_VERSION
Stable version label for the bundled Razorpay IFSC data.

Functions§

dataset
Returns information about the bundled dataset.
directory
Returns a handle to the embedded directory.
lookup
Looks up a parsed IFSC code in the embedded directory.
lookup_str
Parses input, then looks it up in the embedded directory.
parse
Parses an IFSC after enforcing a 64-byte input bound.
parse_strict
Parses an IFSC that is already in canonical uppercase form.

Type Aliases§

Result
An IFSC parsing or directory-query result.