IBAN Library
A small, dependency-free TypeScript library for validating, formatting, parsing and generating IBAN numbers.
- Validates country, length, format and the ISO 7064 mod-97 checksum
- Formats IBANs for screen (
GB82 WEST 1234 5698 7654 32) or machines (GB82WEST12345698765432) - Extracts the BBAN and fields such as bank code, branch code and account number
- Generates random, valid IBANs for testing
- Supports 111 countries: every country in the SWIFT IBAN Registry (ISO 13616), plus countries that use IBAN outside the registry
Installation
npm install @dellacagna/iban
Requires Node.js 18 or later. The package ships both ES modules and CommonJS, with TypeScript types for each.
Upgrading from 1.x? See Migrating to 2.0.
Usage
import { IBAN } from '@dellacagna/iban';
const iban = new IBAN('GB82 WEST 1234 5698 7654 32');
if (iban.isValid()) {
console.log(iban.toPrintFormat()); // GB82 WEST 1234 5698 7654 32
} else {
console.log(iban.getError()); // e.g. CHECKSUM_FAILED
}
CommonJS works too:
const { IBAN } = require('@dellacagna/iban');
API
new IBAN(iban: string)
Creates an IBAN object. Input is case-insensitive, and spaces and hyphens are ignored.
isValid(): boolean
Returns true for a valid IBAN or false if invalid.
const iban = new IBAN('GB82 WEST 1234 5698 7654 32');
iban.isValid(); // true
getError(): errorCodes | undefined
Returns why the IBAN is invalid, or undefined if it is valid. The possible values are exported as the errorCodes enum:
errorCodes |
Value | Meaning |
|---|---|---|
invalidCountry |
INVALID_COUNTRY |
The country code is not supported |
invalidLength |
INVALID_LENGTH |
Wrong length for the country |
invalidFormat |
INVALID_FORMAT |
Characters don't match the country's BBAN format |
checksumFailed |
CHECKSUM_FAILED |
The check digits are wrong (e.g. a typo in the number) |
import { IBAN, errorCodes } from '@dellacagna/iban';
const iban = new IBAN('GB82 WEST 1234');
iban.getError(); // 'INVALID_LENGTH'
if (iban.getError() === errorCodes.invalidLength) {
// ...
}
getOriginal(): string
Returns the original input, unchanged.
new IBAN('GB82 weST 123456987654 32').getOriginal(); // 'GB82 weST 123456987654 32'
toElectronicFormat(): string
Returns the IBAN in upper case with all spaces and hyphens removed.
new IBAN('GB82 weST 123456987654 32').toElectronicFormat(); // 'GB82WEST12345698765432'
toPrintFormat(): string
Returns the IBAN in upper case, in groups of four characters.
new IBAN('GB82 weST 123456987654 32').toPrintFormat(); // 'GB82 WEST 1234 5698 7654 32'
getBBAN(): string
Returns the BBAN (Basic Bank Account Number): the IBAN without the country code and check digits.
new IBAN('GB82 WeST 1234 5698 7654 32').getBBAN(); // 'WEST12345698765432'
getFields(): Fields | undefined
Returns the fields contained in the IBAN. Fields that don't apply to the country are left out. Returns undefined for unsupported countries and for countries with no published field layout.
interface Fields {
countryCode: string;
country: string;
checkDigits: string;
accountNumber?: string;
currencyCode?: string;
ownerAccountNumber?: string;
accountNumberPrefix?: string;
bankCode?: string;
bicBankCode?: string;
branchCode?: string;
accountType?: string;
nationalCheckDigit?: string;
}
new IBAN('BA39 1290 0794 0102 8494').getFields();
// {
// countryCode: 'BA',
// country: 'Bosnia and Herzegovina',
// checkDigits: '39',
// accountNumber: '94010284',
// bankCode: '129',
// branchCode: '007',
// nationalCheckDigit: '94',
// }
getFields() does not check that the IBAN is valid; call isValid() first.
IBAN.random(countryCode?: string): string
Generates a random IBAN with valid check digits, in print format. Pass a country code (case-insensitive) to choose the country; otherwise one is picked at random. The result is structurally valid but almost certainly not a real account, so it is only meant for tests and fake data.
IBAN.random(); // e.g. 'GB82 WEST 1234 5698 7654 32'
IBAN.random('IT'); // e.g. 'IT60 X054 2811 1010 0000 0123 456'
IBAN.random('US'); // throws RangeError: Unsupported IBAN country code: US
Throws a RangeError if the country is not supported.
IBAN.supportedCountries(): string[]
Returns the country codes of all supported countries, sorted alphabetically.
IBAN.supportedCountries(); // ['AD', 'AE', 'AL', ...]
IBAN.isSupportedCountry(countryCode: string): boolean
Returns true if the country (case-insensitive) is supported.
IBAN.isSupportedCountry('gb'); // true
IBAN.isSupportedCountry('US'); // false
Static helpers
The formatting methods are also available without creating an object:
IBAN.electronicFormat('gb82 west 1234 5698 7654 32'); // 'GB82WEST12345698765432'
IBAN.printFormat('GB82WEST12345698765432'); // 'GB82 WEST 1234 5698 7654 32'
IBAN.bban('GB82 WEST 1234 5698 7654 32'); // 'WEST12345698765432'
IBAN.extractFields('BA39 1290 0794 0102 8494'); // same as getFields()
Supported countries
The library covers every country in the SWIFT IBAN Registry, including recent additions such as the Falkland Islands, Mongolia, Oman, Somalia and Yemen.
It also supports 23 countries that use IBAN but are not in the official registry. Their formats come from national banks and are not guaranteed by SWIFT, and getFields() returns undefined for them:
Algeria (DZ), Angola (AO), Benin (BJ), Burkina Faso (BF), Cabo Verde (CV), Cameroon (CM), Central African Republic (CF), Chad (TD), Comoros (KM), Congo (CG), Côte d'Ivoire (CI), Equatorial Guinea (GQ), Gabon (GA), Guinea-Bissau (GW), Honduras (HN), Iran (IR), Madagascar (MG), Mali (ML), Morocco (MA), Mozambique (MZ), Niger (NE), Senegal (SN), Togo (TG).
Migrating to 2.0
- Node.js 18+ is required, and the build targets ES2018 instead of ES5. If you need to support very old browsers, transpile the package in your bundler.
IBAN.random('XX')throws aRangeErrorfor unsupported countries instead of quietly returning an IBAN for a random country. UseIBAN.isSupportedCountry()to check first.getError()returns theerrorCodesenum instead ofstring. The runtime values are unchanged ('INVALID_LENGTH'etc.), but TypeScript may now flag comparisons with plain strings. Compare witherrorCodes.invalidLengthinstead.- The package has an
exportsmap. Only the package root (@dellacagna/iban) can be imported; deep imports such as@dellacagna/iban/dist/lib/constantsno longer work. Everything you need is exported from the root.
Development
npm install
npm test # Jest
npm run lint # ESLint
npm run typecheck # tsc --noEmit
npm run build # ESM + CommonJS + types in dist/ (tsup)
npm run check:exports # verify the package resolves for ESM, CommonJS and TypeScript