# @dellacagna/iban

> Validate, format and generate IBAN numbers

Latest version **2.0.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @dellacagna/iban
pnpm add @dellacagna/iban
yarn add @dellacagna/iban
bun add @dellacagna/iban
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-11-19 |
| First published | 2023-01-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 73 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Giovanni Della Cagna |
| Maintainers | giovannidc |
| Keywords | IBAN, BBAN, Validator, Formatter, Fake, Generator, Generate, ISO 13616, SEPA, validation |

## Links

- npm: https://www.npmjs.com/package/@dellacagna/iban
- Repository: https://github.com/dellacagna/iban
- Homepage: https://github.com/dellacagna/iban#readme
- Issues: https://github.com/dellacagna/iban/issues
- npm.io page: https://npm.io/package/@dellacagna/iban

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-11-19
- 1.2.0 — 2026-11-19
- 1.1.1 — 2023-01-24
- 1.0.0 — 2023-01-23
- 0.0.1 — 2023-01-16

## README

[![npm version](https://badge.fury.io/js/@dellacagna%2Fiban.svg)](https://badge.fury.io/js/@dellacagna%2Fiban)
[![CI](https://github.com/dellacagna/iban/actions/workflows/ci.yml/badge.svg)](https://github.com/dellacagna/iban/actions/workflows/ci.yml)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dellacagna/iban/master/LICENSE)

# 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)](https://www.swift.com/standards/data-standards/iban-international-bank-account-number), plus [countries that use IBAN outside the registry](#supported-countries)

## Installation

```sh
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](#migrating-to-20).

## Usage

```ts
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:

```js
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.

```ts
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) |

```ts
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.

```ts
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.

```ts
new IBAN('GB82 weST 123456987654   32').toElectronicFormat(); // 'GB82WEST12345698765432'
```

### `toPrintFormat(): string`

Returns the IBAN in upper case, in groups of four characters.

```ts
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.

```ts
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.

```ts
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;
}
```

```ts
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.

```ts
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.

```ts
IBAN.supportedCountries(); // ['AD', 'AE', 'AL', ...]
```

### `IBAN.isSupportedCountry(countryCode: string): boolean`

Returns `true` if the country (case-insensitive) is supported.

```ts
IBAN.isSupportedCountry('gb'); // true
IBAN.isSupportedCountry('US'); // false
```

### Static helpers

The formatting methods are also available without creating an object:

```ts
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 a `RangeError`** for unsupported countries instead of quietly returning an IBAN for a random country. Use `IBAN.isSupportedCountry()` to check first.
- **`getError()` returns the `errorCodes` enum** instead of `string`. The runtime values are unchanged (`'INVALID_LENGTH'` etc.), but TypeScript may now flag comparisons with plain strings. Compare with `errorCodes.invalidLength` instead.
- **The package has an `exports` map.** Only the package root (`@dellacagna/iban`) can be imported; deep imports such as `@dellacagna/iban/dist/lib/constants` no longer work. Everything you need is exported from the root.

## Development

```sh
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
```

## Resources

- [Changelog](https://github.com/dellacagna/iban/blob/master/CHANGELOG.md)
- [License](https://raw.githubusercontent.com/dellacagna/iban/master/LICENSE)

---
_Source: https://npm.io/package/@dellacagna/iban · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
