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
Every method except country_format needs an API key, and that includes lookup_bic, which used to work without one. Without a key the API answers HTTP 401 and the client returns Error::Authentication. Request a free key at ibanchecker.cash/api-docs; it arrives by email in seconds. Paid plans with higher quotas are at ibanchecker.cash/pricing.
What a key can call follows its plan:
- A free key covers
validateonly, 100 requests a month. validate_bulkandlookup_bicneed the Basic plan or above (Basic, Starter, Growth, Enterprise).extractneeds the Growth plan or above (Growth, Enterprise).
A call outside the key's plan gets HTTP 403 with code PLAN_REQUIRED, which the client returns as Error::Api (see Error handling).
A key whose email address has a verified account at ibanchecker.cash/dashboard can try the methods its plan lacks: validate_bulk with up to 10 IBANs per call (100 on a plan that includes it), lookup_bic, and extract with up to 5,000 characters per call (50,000 on a plan that includes it). The trial applies to any plan that lacks the method, so a Basic key with a verified account can try extract. A trial call over the trial size gets HTTP 400 (Error::BadRequest) with code TOO_MANY_IBANS for validate_bulk or TEXT_TOO_LONG for extract.
country_format works without a key, limited to 100 requests an hour per IP; beyond that the API answers HTTP 429 with code RATE_LIMIT_EXCEEDED. This hourly keyless limit applies only to country formats.
let client = with_api_key;
let client = builder
.api_key
.timeout
.build?;
// Country formats only: no key needed.
let client = new;
The key is sent as Authorization: Bearer <key>.
How requests are counted
validate and lookup_bic count one request per call. validate_bulk counts one request per IBAN, and extract one per IBAN found, with at least one per call. A call that costs more than the requests left this month gets HTTP 429 with code QUOTA_EXCEEDED (Error::RateLimit), so a bulk call of 50 IBANs with 20 requests left gets 429.
Methods
| Method | API key | Description |
|---|---|---|
validate(iban) |
required, any plan | Validate a single IBAN. Returns a ValidationResult. |
validate_bulk(ibans) |
required, Basic or above | Validate up to 100 IBANs (10 on a trial). Returns a BatchResult. |
extract(text) |
required, Growth or above | Find and validate IBANs in free text (up to 50,000 chars; 5,000 on a trial). Returns a BatchResult. |
country_format(country) |
not needed | IBAN format spec for an ISO country code. Returns a FormatSpec. |
lookup_bic(bic) |
required, Basic or above | Resolve an 8 or 11 character BIC. Returns a BankRecord. |
A key whose plan lacks validate_bulk, extract or lookup_bic can still try it when the key's email address has a verified account; see Authentication.
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
// Needs a key on the Basic plan or above, or a verified account to try it.
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, plan, quota and server-side problems only.
use Error;
match client.lookup_bic.await
| Variant | Returned when |
|---|---|
Error::BadRequest |
HTTP 400, the request was malformed, or a trial call went over the trial size (TOO_MANY_IBANS, TEXT_TOO_LONG) |
Error::Authentication |
HTTP 401, the API key is missing, invalid or inactive; every method except country_format needs one |
Error::NotFound |
HTTP 404, no such country code or BIC |
Error::RateLimit |
HTTP 429: QUOTA_EXCEEDED when a call costs more than the key's requests left this month, RATE_LIMIT_EXCEEDED when keyless country_format calls pass 100 an hour per IP |
Error::Api |
HTTP 403 PLAN_REQUIRED when the key's plan does not include the method; 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().
The client has no variant of its own for HTTP 403: a PLAN_REQUIRED answer arrives as Error::Api with status 403 and code "PLAN_REQUIRED". Its body carries required_plan ("basic" or "growth") and upgrade_url:
if let Err = client.extract.await
A QUOTA_EXCEEDED body also carries retry_after, the seconds until the quota resets on the 1st of next month (UTC), and upgrade_url:
if let Err = client.validate.await
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