koblas / ibankit-js

Validation, field extraction and creation of IBAN, BBAN, BIC numbers

ibankit

A library for generation and validation of International Bank Account Numbers (IBAN, ISO 13616) and Business Identifier Codes (BIC, ISO_9362).

Key Features

• Drop-in replaceable with iban-js
• Currently conformant with Version 95 (July 2023) of the IBAN registry
• Decodes bank, branch and account numbers from IBAN
• Supports random BBAN / IBAN generation for testing
• Has BIC validation as a bonus
• Supports validation of National Check Digits if part of BBAN format
• Full TypesScript support
• No external dependencies

SWIFT IBAN Registry

This release should be compatible with the SWIFT IBAN Registry Version 95. There may be a limited number of value differences, some countries in the Registry doesn't describe bank/branch information but may expose it as 3!n4!n but leave the branch description as a blank.

IBAN quick examples

// How to generate IBAN
const ibanStr = new IBANBuilder()
  .countryCode(CountryCode.AT)
  .bankCode("19043")
  .accountNumber("00234573201")
  .build()
  .toString();

// How to create IBAN object from String
const iban = new IBAN("DE89370400440532013000");

// The library ignores spaces in IBANs, this is valid
const iban = new IBAN("DE89 3704 0044 0532 0130 00");

// For testing, the library will also generate random IBANs
const iban = IBAN.random(CountryCode.AT);
const iban = IBAN.random();
const iban = new IBANBuilder().countryCode(CountryCode.AT).bankCode("19043").build();

// For simplicity in porting from iban-js applications
// you can quickly check validity
IBAN.isValid("AT611904300234573201"); // ===  true
IBAN.isValid("DE89 3704 0044 0532 0130 00"); // == true
IBAN.isValid("hello world"); // == false

BIC quick examples

// How to create BIC object from String
const bic = BIC("DEUTDEFF");

// Check to see is BIC code is valid
BIC.isValid("DEUTDEFF500"); // === true

TODO

• Finish writing all national check digit generators (see Oracle spec)
• For random IBANs the National Check digits is random, rather than "valid"

References

• http://en.wikipedia.org/wiki/ISO_13616
• http://en.wikipedia.org/wiki/ISO_9362
• https://www.swift.com/resource/iban-registry-pdf
• https://docs.oracle.com/cd/E18727_01/doc.121/e13483/T359831T498954.htm
• https://en.bitcoinwiki.org/wiki/International_Bank_Account_Number
• globalcitizen/php-iban#39

Credits

• iban-js by ARHS Group
• iban4j by Artur Mkrtchyan

License

Copyright 2018-2023 David Koblas

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

ibankit-js's Issues

Error messages using `Object.entries` and `Object.values`

I have very little experience with TypeScript, so this may be a false alarm, but after I imported ibankit into my project, VSCode is showing me two warnings:

Property 'entries' does not exist on type 'ObjectConstructor'.

in

ibankit-js/src/bbanStructure.ts

Line 60 in 3ba59db

Object.entries(replaceChars).map(

and

ibankit-js/src/country.ts

Lines 513 to 521 in 3ba59db

	const by2code = Object.entries(countryData).reduce((acc, [k, v]) => {
	acc[k] = [k, v];
	return acc;
	}, {});
	const by3code = Object.entries(countryData).reduce((acc, [k, v]) => {
	acc[v[1]] = [k, v];
	return acc;
	}, {});

as well as

Property 'values' does not exist on type 'ObjectConstructor'.

in

ibankit-js/src/bbanStructure.ts

Line 876 in 3ba59db

return Object.values(this.structures) as BbanStructure[];

Is this something misconfigured on my end, or is it a legitimate issue?

Clarification of compatibility with iban-js

The README claims that ibankit is "Drop-in replaceable with iban-js", but it's unclear what that means. Would a project using ibankit be able to swap to iban-js and continue working, or is it the opposite? The latter seems more likely (and fits better with what the README mentions further down about "porting from iban-js applications", but the language suggests the contrary.

Perhaps "Drop-in replacement for iban-js" would better match the intention?

dist / webbrowser script

I would like to use this in a webbrowser project that doesn't support modules (import/require) yet.

If a drop-in for https://www.npmjs.com/package/iban#in-the-browser could be distributed in this package, I would be very grateful!

Missing `tslib` dependency

Description

After trying to release a project using your lib, I encountered the following error:

Error: Cannot find module 'tslib'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:636:15)
    at Function.Module._load (internal/modules/cjs/loader.js:562:25)
    at Module.require (internal/modules/cjs/loader.js:690:17)
    at require (internal/modules/cjs/helpers.js:25:18)
    at Object.<anonymous> (/space/www/my-project/data/releases/20200430123219/node_modules/ibankit/lib/exceptions.js:3:15)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Module.require (internal/modules/cjs/loader.js:690:17)
    at require (internal/modules/cjs/helpers.js:25:18)
    at Object.<anonymous> (/space/www/my-project/data/releases/20200430123219/node_modules/ibankit/lib/bbanStructure.js:6:20)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Module.require (internal/modules/cjs/loader.js:690:17)
    at require (internal/modules/cjs/helpers.js:25:18)
    at Object.<anonymous> (/space/www/my-project/data/releases/20200430123219/node_modules/ibankit/lib/index.js:5:23)

The important line from above is the following one where tslib is required:

at Object.<anonymous> (/space/www/my-project/data/releases/20200430123219/node_modules/ibankit/lib/exceptions.js:3:15)

The error comes from the fact that the library is working fine when there is dev dependencies (containing tslib) but not on an environment where tslib is not in the dependencies.

How to fix

Add tslib in the dependency.

Support IBAN Registry version 92

Noted changes from document (https://www.swift.com/swift-resource/9606/download)

• SD updated and BI added

-- Specific formats:

SD update (need to check)

SD2!n2!n12!n

BI added

BI2!n5!n5!n11!n2!n

Update check digits based on wikipedia

https://en.wikipedia.org/wiki/International_Bank_Account_Number

The page now lists additional check digit validation and should be reviewed.

Updates and detailed/modified validation

Current version of the IBAN registry appears to be Version 88. Will the library be updated?

Could the detailed validation parts of ibanUtils be made part of the external API? I'd like to basically repeat the steps in validate() but tweak them to skip country validation so XX and newly added countries don't have validation errors.

Getting bank name and BIC from IBAN

Can we somehow get the Bank name and BIC from IBAN?

IBANBuilder failure

The random iban generator sometimes generates an invalid iban and throws an exception. Here is a failing code snippet:

import {IBANBuilder} from 'ibankit';

for (let i = 0 ; i < 100; ++i) {
  console.log(new IBANBuilder().build())
}

Exception:

C:\Users\lagri\clones\temp\node_modules\ibankit\src\exceptions.ts:46
    super(msg);
    ^
FormatException [Error]: [88JFGW92NHDQJQZY88H5482] length is 23, expected BBAN length is: 26
    at new FormatException (C:\Users\lagri\clones\temp\node_modules\ibankit\src\exceptions.ts:46:5)
    at BbanStructure.validateBbanLength (C:\Users\lagri\clones\temp\node_modules\ibankit\src\bbanStructure.ts:954:13)
    at BbanStructure.validate (C:\Users\lagri\clones\temp\node_modules\ibankit\src\bbanStructure.ts:880:10)
    at validateBban (C:\Users\lagri\clones\temp\node_modules\ibankit\src\ibanUtil.ts:92:13)
    at Object.validate (C:\Users\lagri\clones\temp\node_modules\ibankit\src\ibanUtil.ts:56:3)
    at IBANBuilder.build (C:\Users\lagri\clones\temp\node_modules\ibankit\src\ibanBuilder.ts:164:16)
    at Object.<anonymous> (C:\Users\lagri\clones\temp\index.ts:4:33)
    at Module._compile (internal/modules/cjs/loader.js:999:30)
    at Module.m._compile (C:\Users\lagri\clones\temp\node_modules\ts-node\src\index.ts:1310:23)
    at Module._extensions..js (internal/modules/cjs/loader.js:1027:10) {
  formatViolation: 14,
  expected: '23',
  actual: '26'
}