A B2B checkout or supplier onboarding form usually collects two identifiers that are easy to mistype and costly to get wrong: a bank account number in IBAN form and a VAT number. This tutorial shows how to validate both in code, and where the limits of each check lie.
The IBAN can be checked offline with a short function. A VAT number needs a live lookup against the European Commission's VIES service, which brings availability and legal questions with it. The last section shows the same checks through APIStack's API.
How an IBAN is built
The IBAN format is defined by ISO 13616, and SWIFT, as registration authority, publishes the IBAN registry with each country's length and layout (Wikipedia summarises the structure and the per-country formats). An IBAN has up to 34 characters in three parts:
- a two-letter country code, such as
DEorGB - two check digits
- the Basic Bank Account Number (BBAN), whose length and structure each country sets
In DE89 3704 0044 0532 0130 00 the country is Germany, the check digits are 89, and the BBAN is an eight-digit bank code followed by a ten-digit account number. A German IBAN is always 22 characters; other countries use other fixed lengths. The spaces are for people and are not part of the value.
The mod-97 check
The check digits make the whole IBAN satisfy one arithmetic rule. To test it:
- Remove spaces and convert to upper case.
- Move the first four characters to the end.
- Replace each letter with two digits:
Abecomes 10,Bbecomes 11, up toZas 35. - Read the result as one integer. The IBAN passes if that integer leaves a remainder of 1 when divided by 97.
The integer can run to more than 60 digits, far beyond what a JavaScript number can hold exactly. The usual solution is to compute the remainder as you go, one character at a time, so the running value stays below ten thousand. This function does that, and also checks the overall shape and the length for a few countries:
const IBAN_LENGTHS = { BE: 16, DE: 22, ES: 24, FR: 27, GB: 22, IE: 22, IT: 27, NL: 18 }
function validateIban(input) {
const iban = String(input).replace(/[\s-]/g, '').toUpperCase()
if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban)) return { valid: false, reason: 'format' }
const expected = IBAN_LENGTHS[iban.slice(0, 2)]
if (expected && iban.length !== expected) return { valid: false, reason: 'length' }
const rearranged = iban.slice(4) + iban.slice(0, 4)
let remainder = 0
for (const ch of rearranged) {
const value = ch >= 'A' ? ch.charCodeAt(0) - 55 : Number(ch)
remainder = (remainder * (value > 9 ? 100 : 10) + value) % 97
}
return remainder === 1 ? { valid: true, iban } : { valid: false, reason: 'checksum' }
}
validateIban('GB82 WEST 1234 5698 7654 32') // { valid: true, iban: 'GB82WEST12345698765432' }
validateIban('DE89 3704 0044 0532 0130 00') // { valid: true, iban: 'DE89370400440532013000' }
validateIban('GB82 WEST 1234 5698 7654 23') // { valid: false, reason: 'checksum' }A letter contributes two digits, so the running remainder is multiplied by 100 for a letter and by 10 for a digit before the value is added. The third call shows the point of the scheme: swapping the last two digits of a valid IBAN is caught.
Python integers have no size limit, so the same check is shorter there. int(ch, 36) maps 0-9 and A-Z to 0-35 in one step.
import re
def validate_iban(value: str) -> bool:
iban = re.sub(r"[\s-]", "", value).upper()
if not re.fullmatch(r"[A-Z]{2}\d{2}[A-Z0-9]{11,30}", iban):
return False
rearranged = iban[4:] + iban[:4]
digits = "".join(str(int(ch, 36)) for ch in rearranged)
return int(digits) % 97 == 1What the checksum proves
The check is designed to catch typing mistakes: a wrong character or two characters swapped. It is cheap enough to run on every keystroke in a form.
It does not prove that the account exists, that it is open, or that it belongs to the person who typed it. A passing IBAN is well-formed and nothing more. Two further offline checks tighten it: the country's exact length and BBAN layout from the registry, and, for some countries, national check digits inside the BBAN. Libraries such as ibantools carry those tables so you do not have to maintain them. Confirming the account holder is a job for your bank or payment provider.
EU VAT number formats
An EU VAT identification number is a two-letter prefix followed by up to 12 characters in a layout each member state defines. Germany uses nine digits (DE123456789), the Netherlands nine digits, the letter B and two more digits, and Ireland a mix of digits and letters such as IE6388047V. Two prefixes differ from the ISO country code: Greece uses EL, not GR, and Northern Ireland uses XI.
A regular expression per country catches malformed input before you spend a network call on it. It cannot tell you whether the number has been issued. Unlike the IBAN, there is no single checksum across countries, and a number that fits the pattern may never have been assigned or may have been cancelled last month.
Checking registration with VIES
The European Commission runs the VAT Information Exchange System for this. The Commission's own description is that VIES is a search engine, not a database: each query is forwarded to the national VAT database of the member state that issued the number. That design explains most of its behaviour.
VIES has a REST interface, described in the Commission's OpenAPI file. A check is a POST with the prefix and the rest of the number sent separately:
curl -X POST "https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number" \
-H "Content-Type: application/json" \
-d '{"countryCode": "IE", "vatNumber": "6388047V"}'The response has a boolean valid, a requestDate, and name and address fields. If you also send your own VAT number as requesterMemberStateCode and requesterNumber, the response includes a requestIdentifier, a consultation reference you can keep as evidence of the check.
What valid means
A valid result means the number was registered for intra-EU transactions in the national database at the moment you asked. The Commission's page lists what an invalid result can mean: the number does not exist, it has not been activated for intra-EU transactions, or the registration is not yet finalised. Some member states require a separate registration for cross-border trade, so a business can have a working domestic VAT number that VIES reports as invalid.
The legal weight is real. Since the 2020 "quick fixes" in Council Directive (EU) 2018/1910, the customer's VAT identification number is a condition for exempting an intra-EU supply of goods from VAT. The Commission accepts no responsibility for the accuracy of the national data and recommends keeping a record of each validation in case of a tax audit. Store the number, the result, the timestamp and the request identifier with the invoice.
Name and address are not always returned. Some member states withhold them for data protection reasons, and Germany is one that returns no name through VIES.
Availability
Because every query depends on a national system, VIES is only as available as the member state you are asking. National databases go offline for maintenance and backups, and the service limits concurrent requests. The check-status endpoint reports each member state as Available or Unavailable, and a failed check returns an error code such as MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, SERVICE_UNAVAILABLE or TIMEOUT. These codes are listed in the VIES service definition.
UK and Northern Ireland numbers
Since the end of the Brexit transition period on 1 January 2021, GB numbers are not in VIES; a lookup for one returns an input error. Check them with HMRC instead, through the Check a UK VAT number service or HMRC's API, which requires registering an application.
Northern Ireland is the exception. Businesses there that trade goods with the EU use a VAT number with the XI prefix in place of GB, and VIES accepts XI as a country code. The prefix applies to goods, not services.
Caching and fallback
A workable strategy has four parts.
Validate the format locally first and reject malformed input without calling VIES.
Model three outcomes, not two: valid, invalid and unavailable. On unavailable, retry once after a short delay, since concurrency errors often clear quickly. If it still fails, let the customer continue, mark the number as unverified, and queue a recheck. Decide in advance whether an unverified order is invoiced with VAT until the check succeeds.
Cache valid results for a period your tax adviser is comfortable with, such as a day, to avoid repeating lookups during one checkout session. Do not cache unavailable results, and re-validate at the point of invoicing, because registrations are cancelled.
Keep the evidence. A stored timestamp and identifier are what you show an auditor.
The same checks through one API
APIStack's VAT and IBAN Validation API wraps both checks. The IBAN endpoint takes an iban parameter, with spaces allowed, and applies the checksum plus each country's length and layout rules without a network call:
curl "https://apistack.online/api/utilities/vat-iban-validation/v1/iban?iban=GB82%20WEST%201234%205698%207654%2032" \
-H "x-api-key: YOUR_API_KEY"The result is in the data field of the response:
{
"input": "GB82 WEST 1234 5698 7654 32",
"iban": "GB82WEST12345698765432",
"valid": true,
"formatted": "GB82 WEST 1234 5698 7654 32",
"countryCode": "GB",
"countryName": "United Kingdom",
"expectedLength": 22,
"sepa": true,
"errors": [],
"checkDigits": "82",
"bban": "WEST12345698765432",
"bankCode": "WEST",
"branchCode": "123456"
}For an invalid IBAN, valid is false and errors holds objects with a code and a message, for example WrongIBANChecksum when the check digits do not match.
The VAT endpoint takes vat, and an optional country if the number has no prefix. Spaces, dots and dashes are ignored, and GR is accepted for Greece.
curl "https://apistack.online/api/utilities/vat-iban-validation/v1/vat?vat=IE6388047V" \
-H "x-api-key: YOUR_API_KEY"The response always includes countryCode, vatNumber, formatValid, status and registered. The status field carries the three-way outcome described above, plus one more:
status | registered | Meaning |
|---|---|---|
valid | true | VIES confirmed the number; name and address are included where the country publishes them, with checkedAt |
invalid | false | The format is wrong (see errors) or VIES does not know the number |
unavailable | null | VIES or the national service could not answer; reason says why, so retry later |
format_only | null | A GB number: the format was checked, registration was not |
XI numbers go through VIES like any EU number. To check several identifiers from one form submission, the base endpoint /api/utilities/vat-iban-validation/v1 accepts iban, bic and vat together and returns one result per identifier. The same checks are available to AI agents as the validate_iban and validate_vat_number tools on the MCP server.
Summary
- An IBAN is a country code, two check digits and a national account number. The mod-97 check catches typing errors offline but says nothing about whether the account exists.
- VAT number formats vary by country and have no common checksum, so format checks only filter out malformed input.
- VIES forwards each query to a national database. Valid means registered for intra-EU trade at that moment; keep the timestamp and request identifier as evidence.
- Treat unavailable as a third outcome: retry, let the customer continue as unverified, and recheck later.
GBnumbers are not in VIES and are checked with HMRC; Northern Ireland'sXInumbers are in VIES.