Docs / Identifier checks / Validate an IBAN

Validate an IBAN

Check that an IBAN has the right length for its country and correct mod-97 check digits, and get it back normalised and grouped for printing.

curl "https://agent-helper.org/check/iban/DE89370400440532013000"
valid
# type: computed
# checked: IBAN: country length (SWIFT IBAN registry) and ISO 7064 mod 97-10 check digits
# normalized: DE89370400440532013000
# country: DE (Germany)
# formatted: DE89 3704 0044 0532 0130 00
# bban: 370400440532013000
# note: format and check digits only; this does not show that the account exists or is in use

The trap

An IBAN validator answers a question about a string of characters, not about a bank account. The two digits after the country code are computed with ISO 7064 mod 97-10 over the rest of the IBAN, and they catch almost every typing mistake: a wrong character, or two neighbouring characters swapped. That is what they were designed for, stopping a slip of the finger before a payment leaves. They say nothing about whether the bank or the account exists.

Producing an IBAN that passes is easy. Take a country code and an account part of the right length, put 00 where the check digits go, compute the remainder, and write its complement in their place. Test data generators do exactly this, which is why a column of valid IBANs in a customer table proves nothing about the customers.

The checksum also knows nothing of national rules. Many domestic account numbers carry check digits of their own inside the IBAN, computed with methods that vary by country and in Germany by bank, and a generic validator does not run them. An IBAN can pass mod 97 while its account number fails its bank's check.

The input is the other source of false answers. IBANs are copied from invoices, PDFs and emails, and they arrive with a space after every fourth character, in lowercase, with non-breaking spaces, or with zero-width characters that no one can see. A strict validator rejects a correct IBAN because of a space. A careless one removes the spaces it knows about and passes an invisible character through to the payment file, where it breaks something later.

Whether an account exists can only be learned from the banking system itself: an account verification service, or a payment that either arrives or comes back.

What this endpoint does

The value is normalised first: spaces of any kind, hyphens and invisible characters such as zero-width spaces are removed, letters are upper-cased, and the answer shows the result, so it is clear what was checked. Any other character is refused rather than dropped: a Cyrillic letter that looks Latin gets a 400 naming the character and its position.

Then two things are examined: that the country is in the SWIFT IBAN registry with the length it requires, and that the mod 97-10 check digits match. An invalid IBAN comes with the first reason found; a valid one with its country, account part and grouped form. Every answer states that only format and check digits were examined. Check digits inside national account numbers are not verified, and nothing is looked up.

Parameters

NameRequiredMeaning and valuesDefaultLimit
valueyesthe IBAN to check; spaces, hyphens and invisible characters are ignored—200 characters

The whole path and query together are capped at 2048 bytes. Every parameter has the same meaning under /v1/check/iban/{value}.

Examples

One mistyped digit

curl "https://agent-helper.org/check/iban/DE89370400440532013001"
invalid
# type: computed
# checked: IBAN: country length (SWIFT IBAN registry) and ISO 7064 mod 97-10 check digits
# normalized: DE89370400440532013001
# reason: check digits do not match (mod 97 = 28, must be 1)
# country: DE (Germany)
# note: format and check digits only; this does not show that the account exists or is in use

One digit missing

curl "https://agent-helper.org/check/iban/DE8937040044053201300"
invalid
# type: computed
# checked: IBAN: country length (SWIFT IBAN registry) and ISO 7064 mod 97-10 check digits
# normalized: DE8937040044053201300
# reason: length 21, but DE IBANs have 22 characters
# country: DE (Germany)
# note: format and check digits only; this does not show that the account exists or is in use

Copied with spaces and a zero-width space

curl "https://agent-helper.org/check/iban/DE89%203704%200044%200532%200130%2000%E2%80%8B"
valid
# type: computed
# checked: IBAN: country length (SWIFT IBAN registry) and ISO 7064 mod 97-10 check digits
# normalized: DE89370400440532013000
# country: DE (Germany)
# formatted: DE89 3704 0044 0532 0130 00
# bban: 370400440532013000
# note: format and check digits only; this does not show that the account exists or is in use

A country code outside the IBAN registry

curl "https://agent-helper.org/check/iban/XX89370400440532013000"
invalid
# type: computed
# checked: IBAN: country length (SWIFT IBAN registry) and ISO 7064 mod 97-10 check digits
# normalized: XX89370400440532013000
# reason: XX is not a country in the IBAN registry
# note: format and check digits only; this does not show that the account exists or is in use

A Cyrillic letter that looks Latin (error)

curl "https://agent-helper.org/check/iban/GB82W%D0%95ST12345698765432"
error: 400 bad parameter 'value'
parameter: value
problem: contains 'Е' (U+0415 CYRILLIC CAPITAL LETTER IE) at position 6, which cannot be part of an IBAN
hint: spaces, hyphens and invisible characters are ignored; any other character is refused instead of being dropped, because it usually means a typo or a look-alike letter
example: /check/iban/DE89370400440532013000
[the rest of this error repeats the parameter list above]

Limits and provenance

Rate class light (light computations: conversion, validation, dates, encodings, text, networks, geometry): 120 requests a minute per address, bursts of 30; wider limits apply per network and per autonomous system. Current values: /limits.

Answers are marked # type: computed; successful ones are served with Cache-Control: public, max-age=31536000, immutable.

Computed locally; no external data source is involved.

Related