@nivalis/iban

A modern, lightweight TypeScript library for validating, formatting, and converting International Bank Account Numbers (IBANs) and Basic Bank Account Numbers (BBANs).

Features

• ✅ Comprehensive IBAN validation - Validates IBANs according to ISO 13616 standard
• 🌍 Wide country support - Supports 70+ countries and territories
• 🔄 IBAN ↔ BBAN conversion - Convert between IBAN and country-specific BBAN formats
• 📝 Flexible formatting - Format IBANs for display or electronic processing
• 🎯 TypeScript native - Built with TypeScript for excellent type safety
• 📦 Zero dependencies - Lightweight with no external dependencies
• 🚀 Modern ESM/CJS - Supports both ES modules and CommonJS
• ✨ Tree-shakable - Import only what you need

Installation

# npm
npm install @nivalis/iban

# pnpm
pnpm add @nivalis/iban

# yarn
yarn add @nivalis/iban

# bun
bun add @nivalis/iban

Quick Start

import { isValid, printFormat, toBBAN } from '@nivalis/iban';

// Validate an IBAN
isValid('GB29NWBK60161331926819'); // true
isValid('GB29NWBK60161331926820'); // false (wrong check digit)

// Format for display
printFormat('GB29NWBK60161331926819'); // 'GB29 NWBK 6016 1331 9268 19'

// Convert to BBAN
toBBAN('GB29NWBK60161331926819'); // 'NWBK 60161331926819'

API Reference

isValid(iban: string): boolean

Validates an IBAN according to the ISO 13616 standard.

import { isValid } from '@nivalis/iban';

isValid('BE68539007547034'); // true
isValid('BE68539007547035'); // false
isValid('invalid'); // false

validate(iban: string): ValidationResult

Runs the same validation as isValid but returns structured error information instead of throwing exceptions.

import { validate } from '@nivalis/iban';

const result = validate('GB29NWBK60161331926819');
// { ok: true }

const failed = validate('ZZ68539007547034');
// { ok: false, error: 'unknown_country' }

Possible error codes are:

• unknown_country – the IBAN prefix is not part of the ISO registry supported by the library
• bad_length – the IBAN is too short/long or has an invalid BBAN structure for its country
• mod97_failure – the checksum (ISO 7064 Mod 97-10) does not evaluate to 1

describe(iban: string): DescribeResult

Exposes the parsed BBAN blocks for a given IBAN so you can display the bank/branch/account slices without reimplementing the ISO structure tables.

The returned object contains:

• country – ISO country code detected from the IBAN
• iban / bban – sanitized electronic representations
• groups – raw regex capture groups, matching the BBAN blocks in order
• blocks – metadata for each BBAN block including pattern, length, offset, index, and the extracted value

import { describe } from '@nivalis/iban';

const { country, blocks } = describe('BE68 5390 0754 7034');
// country === 'BE'
// blocks === [
//   { pattern: 'F', length: 3, offset: 0, index: 0, value: '539' },
//   { pattern: 'F', length: 7, offset: 3, index: 1, value: '0075470' },
//   { pattern: 'F', length: 2, offset: 10, index: 2, value: '34' },
// ];

electronicFormat(iban: string): string

Converts an IBAN to electronic format (removes spaces and converts to uppercase).

import { electronicFormat } from '@nivalis/iban';

electronicFormat('be68 5390 0754 7034'); // 'BE68539007547034'
electronicFormat('BE68539007547034'); // 'BE68539007547034'

printFormat(iban: string, separator?: string): string

Formats an IBAN for display with optional custom separator (defaults to space).

import { printFormat } from '@nivalis/iban';

printFormat('BE68539007547034'); // 'BE68 5390 0754 7034'
printFormat('BE68539007547034', '-'); // 'BE68-5390-0754-7034'

toBBAN(iban: string, separator?: string): string

Converts an IBAN to its corresponding BBAN (Basic Bank Account Number).

import { toBBAN } from '@nivalis/iban';

toBBAN('BE68539007547034'); // '539 0075470 34'
toBBAN('BE68539007547034', '-'); // '539-0075470-34'

fromBBAN(countryCode: string, bban: string): string

Generates an IBAN from a country code and BBAN.

import { fromBBAN } from '@nivalis/iban';

fromBBAN('BE', '539007547034'); // 'BE68539007547034'
fromBBAN('BE', '539-0075470-34'); // 'BE68539007547034' (ignores formatting)

isValidBBAN(countryCode: string, bban: string): boolean

Validates a BBAN for a specific country.

import { isValidBBAN } from '@nivalis/iban';

isValidBBAN('BE', '539007547034'); // true
isValidBBAN('BE', '539-0075470-34'); // true (ignores formatting)
isValidBBAN('BE', '1539007547034'); // false (invalid length)

availableCountries(): { [key: string]: Specification }

Returns all supported country specifications.

import { availableCountries } from '@nivalis/iban';

const countries = availableCountries();
console.log(Object.keys(countries)); // ['AD', 'AE', 'AL', 'AT', ...]
console.log(countries['BE'].example); // 'BE68539007547034'

Supported Countries

The library supports IBAN validation for 70+ countries and territories:

| Country | Code | Example IBAN | |---------|------|--------------| | Belgium | BE | BE68539007547034 | | Germany | DE | DE89370400440532013000 | | France | FR | FR1420041010050500013M02606 | | United Kingdom | GB | GB29NWBK60161331926819 | | Netherlands | NL | NL91ABNA0417164300 | | Spain | ES | ES9121000418450200051332 | | Italy | IT | IT60X0542811101000000123456 |

Andorra (AD), United Arab Emirates (AE), Albania (AL), Austria (AT), Azerbaijan (AZ), Bosnia and Herzegovina (BA), Belgium (BE), Bulgaria (BG), Bahrain (BH), Brazil (BR), Belarus (BY), Switzerland (CH), Costa Rica (CR), Cyprus (CY), Czech Republic (CZ), Germany (DE), Denmark (DK), Dominican Republic (DO), Estonia (EE), Egypt (EG), Spain (ES), Finland (FI), Faroe Islands (FO), France (FR), United Kingdom (GB), Georgia (GE), Gibraltar (GI), Greenland (GL), Greece (GR), Guatemala (GT), Croatia (HR), Hungary (HU), Ireland (IE), Israel (IL), Iceland (IS), Italy (IT), Iraq (IQ), Jordan (JO), Kuwait (KW), Kazakhstan (KZ), Lebanon (LB), Saint Lucia (LC), Liechtenstein (LI), Lithuania (LT), Luxembourg (LU), Monaco (MC), Moldova (MD), Montenegro (ME), North Macedonia (MK), Mauritania (MR), Malta (MT), Mauritius (MU), Netherlands (NL), Norway (NO), Pakistan (PK), Poland (PL), Palestine (PS), Portugal (PT), Qatar (QA), Romania (RO), Serbia (RS), Saudi Arabia (SA), Seychelles (SC), Sweden (SE), Slovenia (SI), Slovakia (SK), San Marino (SM), São Tomé and Príncipe (ST), El Salvador (SV), Timor-Leste (TL), Tunisia (TN), Turkey (TR), Ukraine (UA), Vatican City (VA).

Examples

Basic Validation

import { isValid } from '@nivalis/iban';

// Valid IBANs
console.log(isValid('DE89370400440532013000')); // true
console.log(isValid('FR1420041010050500013M02606')); // true
console.log(isValid('IT60X0542811101000000123456')); // true

// Invalid IBANs
console.log(isValid('DE89370400440532013001')); // false (wrong check digit)
console.log(isValid('ZZ68539007547034')); // false (unknown country)
console.log(isValid('invalid')); // false (invalid format)

Formatting and Display

import { printFormat, electronicFormat } from '@nivalis/iban';

const iban = 'de89 3704 0044 0532 0130 00';

// Clean and format
const electronic = electronicFormat(iban); // 'DE89370400440532013000'
const display = printFormat(electronic); // 'DE89 3704 0044 0532 0130 00'

// Custom separator
const customFormat = printFormat(electronic, '-'); // 'DE89-3704-0044-0532-0130-00'

IBAN/BBAN Conversion

import { toBBAN, fromBBAN, isValidBBAN } from '@nivalis/iban';

const iban = 'BE68539007547034';

// Convert to BBAN
const bban = toBBAN(iban); // '539 0075470 34'
console.log(isValidBBAN('BE', bban)); // true

// Convert back to IBAN
const regeneratedIban = fromBBAN('BE', bban); // 'BE68539007547034'
console.log(iban === regeneratedIban); // true

Working with Different Countries

import { isValid, toBBAN, fromBBAN } from '@nivalis/iban';

// Dutch IBAN
const dutchIban = 'NL91ABNA0417164300';
console.log(isValid(dutchIban)); // true
console.log(toBBAN(dutchIban)); // 'ABNA 0417164300'

// French IBAN
const frenchIban = 'FR1420041010050500013M02606';
console.log(isValid(frenchIban)); // true
console.log(toBBAN(frenchIban)); // '20041 01005 0500013M026 06'

// Generate German IBAN from BBAN
const germanBban = '370400440532013000';
const germanIban = fromBBAN('DE', germanBban); // 'DE89370400440532013000'

Error Handling

import { fromBBAN, toBBAN } from '@nivalis/iban';

try {
  // This will throw an error for invalid BBAN
  fromBBAN('BE', 'invalid-bban');
} catch (error) {
  console.log(error.message); // "Invalid BBAN"
}

try {
  // This will throw an error for unknown country
  toBBAN('ZZ68539007547034');
} catch (error) {
  console.log(error.message); // "No country with code ZZ"
}

TypeScript Support

This library is written in TypeScript and provides full type definitions:

import type { Specification } from '@nivalis/iban';
import { availableCountries, isValid } from '@nivalis/iban';

// Get type-safe country specifications
const countries: { [key: string]: Specification } = availableCountries();

// Type-safe validation
const isValidIban: boolean = isValid('BE68539007547034');

Development

Prerequisites

• Bun >= 1.2.17
• TypeScript >= 5.0

Setup

# Clone the repository
git clone https://github.com/nivalis-studio/iban.git
cd iban

# Install dependencies
bun install

# Run tests
bun test

# Build the package
bun run build

# Lint code
bun run lint

Testing

The library includes comprehensive tests covering:

• IBAN validation for all supported countries
• BBAN validation and conversion
• Formatting functions
• Error handling
• Edge cases

# Run all tests
bun test

# Run tests with coverage
bun test --coverage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines

1. Ensure tests pass: bun test
2. Follow the existing code style: bun run lint
3. Add tests for new features
4. Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related

• IBAN Registry - Official IBAN country specifications
• ISO 13616 - International standard for IBAN
• ISO 7064 - Check digit algorithms

Made with ❤️ by Nivalis Studio