IBANTools

You can install IBANTools using npm for Node.js environments or Bower for AMD ES5 environments. Note that Bower packages are no longer being generated after the TypeScript 7 release.

$ npm install ibantools

For browser environments using RequireJS, load the ibantools module via the require function.

require(["ibantools"], function(ibantools) {
  console.log(ibantools.isValidIBAN('NL91 ABNA 0417 1643 00'));
  console.log(ibantools.isValidBIC('ABNANL2A'));
});

In a Node.js environment using CommonJS, require the ibantools module. You can use functions like isValidIBAN for boolean checks, validateIBAN to get detailed error codes, and isValidBIC for BIC/SWIFT validation. The library also provides electronicFormatIBAN to normalize IBAN strings.

const ibantools = require('ibantools');
const iban = electronicFormatIBAN('NL91 ABNA 0417 1643 00'); // 'NL91ABNA0517164300'
ibantools.isValidIBAN(iban);

// If you want to know reason why IBAN is invalid
ibantools.validateIBAN('NL91ABNA0517164300');
// Returns { valid: false, errorCodes: [iban.ValidationErrorsIBAN.WrongIBANChecksum] }

// Validate BIC
ibantools.isValidBIC('ABNANL2A');

You can extend the library's country specifications by providing national BBAN (Basic Bank Account Number) validation logic using setCountryBBANValidation. This allows for deeper syntactic checks for specific countries.

const ibantools = require('ibantools');
const ibantoolsGermany = require("ibantools-germany");

// Register a custom BBAN validator for Germany (DE)
ibantools.setCountryBBANValidation("DE", ibantoolsGermany.isValidBBAN);

If you need to implement custom validation logic for a specific country's BBAN, use setCountryBBANValidation(country, func). This will overwrite any existing validation function for that country.

Parameters:

• country: The 2-letter country code.
• func: A function (bban: string) => boolean that performs the validation.

Returns: true if the country exists and the function was set, false otherwise.

Example:

// Custom validation for a hypothetical country 'XX'
ibantools.setCountryBBANValidation('XX', (bban) => bban.length === 10);

IBANTools provides utilities to change the visual representation of an IBAN without performing validation.

Electronic Format

electronicFormatIBAN(iban) removes all spaces and hyphens and converts the string to uppercase. Returns null if the input is not a string.

// returns "NL91ABNA0417164300"
ibantools.electronicFormatIBAN("NL91 ABNA 0417 1643 00");

Friendly Format

friendlyFormatIBAN(iban, separator) returns the IBAN with a separator inserted every 4 characters. The separator defaults to a space if not provided.

// returns "NL91 ABNA 0417 1643 00"
ibantools.friendlyFormatIBAN("NL91ABNA0417164300");

// returns "NL91-ABNA-0417-1643-00"
ibantools.friendlyFormatIBAN("NL91ABNA0417164300", "-");

IBANTools includes support for validating Business Identifier Codes (BIC/SWIFT).

Simple Validation

isValidBIC(bic) returns true if the BIC is valid according to format and country registry.

// returns true
ibantools.isValidBIC("ABNANL2A");

// returns false
ibantools.isValidBIC("ABN4NL2A");

Detailed Validation

validateBIC(bic) returns a ValidateBICResult object containing errorCodes (from ValidationErrorsBIC) and a valid flag.

Errors handled:

• NoBICProvided
• NoBICCountry
• WrongBICFormat

Example:

// returns {errorCodes: [], valid: true}
ibantools.validateBIC("NEDSZAJJXXX");

Use composeIBAN() to generate a valid IBAN from a country code and a BBAN. The function automatically calculates the correct checksum.

Parameters:

• params: An object containing:
  • countryCode (string): The 2-letter country code.
  • bban (string): The Basic Bank Account Number.

Returns: A valid IBAN string or null if the combination is invalid or the country code is missing.

Example:

// returns NL91ABNA0417164300
ibantools.composeIBAN({ countryCode: "NL", bban: "ABNA0417164300" });

Use isValidIBAN() to check if a string is a valid IBAN. By default, it allows QRIBANs (used in Switzerland and Liechtenstein). You can disable this via the validationOptions object.

Options:

• allowQRIBAN (boolean): Whether to allow QRIBANs. Defaults to true.

Examples:

// returns true
ibantools.isValidIBAN("NL91ABNA0417164300");

// returns false
ibantools.isValidIBAN("NL92ABNA0517164300");

// returns false (disabling QRIBAN)
ibantools.isValidIBAN('CH4431999123000889012', { allowQRIBAN: false });

Use extractBIC(inputBic) to parse a BIC string into its constituent parts.

Returns ExtractBICResult:

• bankCode: The first 4 characters.
• countryCode: The 2-character country code (chars 5-6).
• locationCode: The 2-character location code (chars 7-8).
• branchCode: The remaining characters (if any), or null.
• testBIC: Boolean indicating if it's a test BIC (if locationCode[1] is '0').
• valid: Boolean indicating if the BIC is valid.

Example:

// returns {bankCode: "ABNA", countryCode: "NL", locationCode: "2A", branchCode: null, testBIC: false, valid: true}
ibantools.extractBIC("ABNANL2A");

Use extractIBAN() to parse an IBAN string and retrieve its constituent parts like the country code, BBAN, and specific identifiers (bank, branch, or account numbers) if the country specification supports it.

Returns ExtractIBANResult:

• iban: The IBAN in electronic format (no spaces).
• bban: The Basic Bank Account Number.
• countryCode: The 2-letter country code.
• accountNumber: Extracted account number (if available in spec).
• branchIdentifier: Extracted branch identifier (if available in spec).
• bankIdentifier: Extracted bank identifier (if available in spec).
• valid: Boolean indicating if the IBAN is valid.

Example:

// returns {iban: "NL91ABNA0417164300", bban: "ABNA0417164300", countryCode: "NL", valid: true, accountNumber: '0417164300', bankIdentifier: 'ABNA'}
ibantools.extractIBAN("NL91 ABNA 0417 1643 00");