IBAN Validation in Node.js — mod-97 Algorithm Explained

1. What is an IBAN?

An IBAN (International Bank Account Number) is a standardised way to identify a bank account internationally, defined by ISO 13616. Introduced in 1997 to streamline cross-border payments in Europe, IBANs are now used in over 80 countries — and are mandatory for SEPA credit transfers and direct debits in the Eurozone.

Despite the name, IBANs are not just European. Countries like Brazil, Saudi Arabia, Israel, and Pakistan have adopted the standard. When your payment form accepts IBANs from international users, you need a validator that knows the rules for every country.

2. IBAN anatomy — country code, check digits, BBAN

Every IBAN has the same four-component structure:

3. The mod97 checksum (modulus 97, ISO 13616) — step by step

The check digits are validated by rearranging the IBAN and computing the remainder when divided by 97. A valid IBAN always gives a remainder of 1. Let's walk through it with GB82 WEST 1234 5698 7654 32:

// mod97.js — implements the ISO 13616 IBAN checksum
function mod97(iban) {
  // Step 1: move first 4 chars to the end
  const rearranged = iban.slice(4) + iban.slice(0, 4);

  // Step 2: replace each letter with its numeric value
  const numeric = rearranged.replace(/[A-Z]/g, ch =>
    String(ch.charCodeAt(0) - 55)  // A=10, B=11, ..., Z=35
  );

  // Step 3: mod 97 in chunks (JavaScript can't handle the full integer)
  let remainder = 0;
  for (let i = 0; i < numeric.length; i += 9) {
    const chunk = String(remainder) + numeric.slice(i, i + 9);
    remainder = parseInt(chunk, 10) % 97;
  }

  return remainder; // must be 1 for a valid IBAN
}

const iban = 'GB82WEST12345698765432'; // no spaces
console.log(mod97(iban)); // → 1 ✓

4. Why IBAN validation is harder than it looks

// All of these represent the same IBAN — normalise first
'GB82 WEST 1234 5698 7654 32'  // paper/display format
'GB82-WEST-1234-5698-7654-32'  // dashes
'GB82WEST12345698765432'        // no separators (canonical)

5. The production-ready solution

The IsValid IBAN API handles format normalisation, country-length validation, and the mod-97 checksum in a single GET request — for 76 countries. The response also includes the parsed BBAN and an isEU flag for SEPA routing logic.

Get your free API key at isvalid.dev. The free tier includes 100 calls per day — enough for most development and low-volume production use.

Full parameter reference and response schema: IBAN Validation API docs →

6. Node.js code example

Using the IsValid SDK or the native fetch API.

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Example usage ────────────────────────────────────────────────────────────

const result = await iv.iban('GB82 WEST 1234 5698 7654 32');

if (!result.valid) {
  console.log('Invalid IBAN');
} else {
  console.log(`Valid IBAN — ${result.countryName} (${result.isEU ? 'SEPA' : 'non-SEPA'})`);
  console.log('BBAN:', result.bban);
  console.log('Formatted:', result.formatted);
  if (result.bankName) console.log('Bank:', result.bankName);
  if (result.bankBic) console.log('BIC:', result.bankBic);
}

// routes/payment.js (Express)
app.post('/payment', async (req, res) => {
  const { iban, amount, ...rest } = req.body;

  let ibanCheck;
  try {
    ibanCheck = await validateIban(iban);
  } catch {
    return res.status(502).json({ error: 'IBAN validation service unavailable' });
  }

  if (!ibanCheck.valid) {
    return res.status(400).json({ error: 'Invalid IBAN' });
  }

  // Use isEU to route SEPA vs international wire
  const transferType = ibanCheck.isEU ? 'sepa' : 'international';
  await initiateTransfer({ iban, transferType, amount, ...rest });

  res.json({ success: true, transferType });
});

7. cURL example

Validate a German IBAN:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iban?value=DE89370400440532013000"

Spaces are handled automatically:

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "value=GB82 WEST 1234 5698 7654 32" \
  "https://api.isvalid.dev/v0/iban"

With explicit country code (when the IBAN has no prefix):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/iban?value=370400440532013000&countryCode=DE"

8. Understanding the response

Valid German IBAN:

{
  "valid": true,
  "countryCode": "DE",
  "countryName": "Germany",
  "bban": "370400440532013000",
  "isEU": true,
  "formatted": "DE89 3704 0044 0532 0130 00",
  "bankCode": "37040044",
  "bankName": "Commerzbank",
  "bankBic": "COBADEFFXXX"
}

Invalid IBAN (bad checksum):

{
  "valid": false
}

9. Edge cases to handle

function showCorrectAccountForm(country) {
  if (ibanCountries.has(country)) {
    showIbanInput();
  } else {
    showRoutingAndAccountInput(country); // ABA, sort code, BSB, etc.
  }
}

Node.js integration notes

When handling IBAN in a TypeScript codebase, define a branded type to prevent accidental mixing of financial identifier strings at compile time:type Iban = string & { readonly __brand: 'Iban' }. The IsValid SDK ships with full TypeScript definitions covering all response fields, including country-specific and instrument-specific data, so your editor provides autocomplete on the parsed result without manual type declarations.

In financial data pipelines — payment processors, reconciliation engines, or KYC workflows — IBAN validation sits at the ingestion boundary. Pair the IsValid SDK with decimal.js orbig.js for any monetary amounts tied to the identifier, and usepino for structured logging that attaches the validation result to the transaction reference in every log line, making audit trails straightforward.

Error handling should distinguish between a 422 response from IsValid (the IBAN is structurally invalid — return this to the caller immediately) and 5xx or network errors (transient failures — retry once after a short delay before surfacing a service-unavailable error). Never swallow validation failures silently; they indicate bad data that could propagate into financial records downstream.

• Assert process.env.ISVALID_API_KEY is present at server startup, not lazily at first request
• Use Promise.allSettled() for batch validation — it collects all results without aborting on the first failure
• Mock the IsValid client with jest.mock() in unit tests; keep CI pipelines free of real API calls
• Store the full parsed API response alongside the raw IBAN in your database — country code, institution data, and check-digit status are useful for downstream logic

When making HTTP calls to the IsValid API directly (without the SDK), the choice between fetch and axios is largely a matter of preference. The native fetch API is available in Node.js 18+ without any additional dependency and is sufficient for simple request/response flows. axios adds automatic JSON parsing, request/response interceptors, and a cleaner timeout API (axios.create({ timeout: 5000 })), which makes it easier to centralise the Authorization header and retry logic in one place. For high-throughput services that make many concurrent API calls, consider undici — the HTTP client underlying Node.js fetch — used directly for its connection pooling and lower overhead.