trid-iban

Lightweight Turkish IBAN validation library with MOD-97 checksum verification and bank identification.

Installation

npm install trid-iban

Usage

import { validateIBAN } from 'trid-iban';

validateIBAN('TR330006100519786457841326');          // true
validateIBAN('TR33 0006 1005 1978 6457 8413 26');   // true (spaces OK)
validateIBAN('TR000006100519786457841326');          // false

Detailed Validation

import { validateIBANDetailed } from 'trid-iban';

const result = validateIBANDetailed('TR330006100519786457841326');
// {
//   isValid: true,
//   errors: [],
//   bankCode: '00061',
//   bankName: undefined,       // undefined if bank code not in registry
//   formatted: 'TR33 0006 1005 1978 6457 8413 26'
// }

Formatting & Utilities

import { formatIBAN, cleanIBAN, extractBankCode, lookupBankName } from 'trid-iban';

formatIBAN('TR330006100519786457841326');
// 'TR33 0006 1005 1978 6457 8413 26'

cleanIBAN('TR33 0006 1005 1978 6457 8413 26');
// 'TR330006100519786457841326'

extractBankCode('TR330006100519786457841326');
// '00061'

lookupBankName('00046');
// 'Akbank'

API

validateIBAN(iban: string): boolean

Returns true if the given Turkish IBAN is valid. Accepts spaces, dashes, and dots (stripped automatically).

validateIBANDetailed(iban: string): IBANValidationResult

Returns detailed validation result with error information, bank identification, and formatted output.

interface IBANValidationResult {
  isValid: boolean;
  errors: IBANValidationError[];
  bankName?: string;    // Bank name (if known)
  bankCode?: string;    // 5-digit bank code
  formatted?: string;   // Formatted IBAN with spaces
}

formatIBAN(iban: string): string

Formats an IBAN into groups of 4 characters for readability.

cleanIBAN(iban: string): string

Removes spaces, dashes, and dots. Converts to uppercase.

extractBankCode(iban: string): string | undefined

Extracts the 5-digit bank code from positions 5-9.

lookupBankName(bankCode: string): string | undefined

Returns the bank name for a given 5-digit code, or undefined if not in the registry.

Error Codes

| Code | Description | |------|-------------| | EMPTY_INPUT | Input is empty or undefined | | INVALID_LENGTH | Input is not 26 characters | | INVALID_COUNTRY_CODE | Input does not start with "TR" | | INVALID_CHARACTER | Input contains non-digit characters after country code | | INVALID_CHECKSUM | MOD-97 checksum verification failed |

Algorithm

Turkish IBAN validation follows the ISO 13616 standard:

1. Must be exactly 26 characters
2. Must start with "TR"
3. Characters 3–26 must all be digits
4. MOD-97 check: Move first 4 characters to end → convert letters to numbers (A=10...Z=35) → result MOD 97 must equal 1

License

MIT