ibanchecker
Official Rust client for the ibanchecker.cash IBAN validation API.
Validate IBANs across 92 countries, validate up to 100 IBANs per request, extract IBANs from free text, look up country format specifications, and resolve SWIFT/BIC codes. No IBAN data is stored or logged; all validation runs in memory at the edge.
Install
Requires Rust 1.88 or newer. The client is async and built on reqwest with rustls, so it needs no system OpenSSL.
Quick start
use Client;
async
Authentication
An API key is optional. Without one, requests are limited to 100 per hour per IP. With a key, requests count against your plan quota. Get a free key at ibanchecker.cash/api-docs.
let client = with_api_key;
let client = builder
.api_key
.timeout
.build?;
Methods
| Method | Description |
|---|---|
validate(iban) |
Validate a single IBAN. Returns a ValidationResult. |
validate_bulk(ibans) |
Validate up to 100 IBANs. Returns a BatchResult. |
extract(text) |
Find and validate IBANs in free text (up to 50,000 chars). Returns a BatchResult. |
country_format(country) |
IBAN format spec for an ISO country code. Returns a FormatSpec. |
lookup_bic(bic) |
Resolve an 8 or 11 character BIC. Returns a BankRecord. |
Bulk validation
let batch = client
.validate_bulk
.await?;
println!;
for result in &batch.results
Extract from text
let batch = client
.extract
.await?;
for result in &batch.results
Country format and BIC lookup
let spec = client.country_format.await?;
println!; // 22 DE89370400440532013000
for field in &spec.bban_fields
let bank = client.lookup_bic.await?;
println!; // Deutsche Bank AG Frankfurt FRANKFURT AM MAIN
Tri-state fields are Option<bool>
national_check_valid, sepa and swift are Option<bool>. The API distinguishes false from absent, so None means "not known for this IBAN" rather than "no".
let result = client.validate.await?;
if result.valid && result.national_check_valid == Some
national_check_valid reports a domestic account check digit run on top of the ISO 13616 checksum, such as Germany's per-bank Prüfziffer or the UK sort-code and account modulus check. It is advisory: an IBAN with valid true is a valid IBAN whatever this says.
Error handling
A malformed IBAN is not an error: validate returns a ValidationResult with valid false. Error is returned for transport, authentication, quota and server-side problems only.
use Error;
match client.lookup_bic.await
| Variant | Returned when |
|---|---|
Error::BadRequest |
HTTP 400, the request was malformed |
Error::Authentication |
HTTP 401, the API key is missing, invalid or inactive |
Error::NotFound |
HTTP 404, no such country code or BIC |
Error::RateLimit |
HTTP 429, hourly limit or monthly quota exceeded |
Error::Api |
any other error status, or a body that could not be read |
Error::Transport |
the request never reached the API: DNS, TLS, connection, timeout |
Every variant except Transport carries an ApiError with the status, the machine-readable code and the decoded body, reachable through Error::api(), Error::status() and Error::code().
Your own HTTP client
let client = builder
.http_client
.build?;
That replaces the timeout and the redirect policy below, so set both on the client you pass in.
Redirects are refused, not followed
The default client stops at a redirect and returns an error naming the target. That is deliberate, for two reasons. reqwest turns a POST into a GET on a 301, as the RFC asks, so an http:// base URL would reach the https endpoint as a GET and come back 405 Method Not Allowed with nothing to explain it. And a redirect to another host is how an API key travels somewhere it was never meant to go.
Use an https base URL and the situation does not arise.
Raw responses
Every model keeps the untouched response body in raw, so a field added to the API later is reachable without waiting for a client release.
let result = client.validate.await?;
println!; // "SEPA+SWIFT"
Tests
The suite runs against wiremock, so it needs no network.
Links
- Website: https://ibanchecker.cash
- API documentation: https://ibanchecker.cash/api-docs
- OpenAPI spec: https://ibanchecker.cash/openapi.json
- Free online tools: https://ibanchecker.cash/tools
Clients for other languages: Python, PHP, JavaScript, Ruby, Go, and an MCP server.
License
MIT