BIC / SWIFT Validation in Node.js

1. What is a BIC / SWIFT code?

A BIC (Bank Identifier Code), also called a SWIFT code, is a unique identifier for financial institutions used in international wire transfers. It is defined by ISO 9362 and maintained by SWIFT (Society for Worldwide Interbank Financial Telecommunication).

BICs appear in SEPA transfers, IBAN structures, correspondent banking, and payment system integrations. When a user enters a BIC in your app — whether during onboarding, a transfer form, or KYC — you need to verify it's a real, correctly formatted code before passing it downstream.

2. BIC structure decoded

A BIC is either 8 characters (without branch) or 11 characters (with branch). Let's decode a real example:

DEUTDEDB (8 chars) and DEUTDEDBXXX (11 chars with XXX) both refer to the same primary office of Deutsche Bank in Germany. Both are equally valid.

3. The naive approach: regex (and what it misses)

The first impulse is to write a regex against the ISO 9362 format definition:

// bicValidator.js — regex-only approach
// Structurally correct — but misses real-world edge cases

const BIC_REGEX = /^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$/;

function validateBicNaive(bic) {
  return BIC_REGEX.test(bic.toUpperCase().trim());
}

console.log(validateBicNaive('DEUTDEDB'));      // true  — correct
console.log(validateBicNaive('DEUTDEDBXXX'));   // true  — correct
console.log(validateBicNaive('DEUTDEDBBER'));   // true  — correct
console.log(validateBicNaive('AAAABB11'));      // true  — structurally valid but not a real institution
console.log(validateBicNaive('DEUTDEDE'));      // true  — technically valid format, may not exist
console.log(validateBicNaive('DEUTDE'));        // false — too short

4. Why BIC validation is more than format

5. The right solution: one API call

The IsValid BIC API validates format, resolves the institution name, city, and branch, and returns the full country name — all from a single GET request.

Get your free API key at isvalid.dev — 100 calls per day, no credit card required.

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

6. Node.js example with native fetch

Using the @isvalid-dev/sdk package or the native fetch API (Node 18+).

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

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

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

const result = await iv.bic('DEUTDEDBBER');

if (!result.valid) {
  console.log('Invalid BIC');
} else {
  const bank = result.bankName ?? result.bankCode;
  const country = result.countryName ?? result.countryCode;
  const city = result.city ?? '—';
  const branch = result.branch ?? 'primary office';
  console.log(`${bank} · ${country} · ${city} · ${branch}`);
  // → Deutsche Bank · Germany · Berlin · Berlin
}

// bicBatch.js — validate multiple BICs sequentially
async function validateBics(bicList) {
  const results = [];

  for (const bic of bicList) {
    try {
      const data = await validateBic(bic);
      results.push({ bic, ...data });
    } catch (err) {
      results.push({ bic, valid: false, error: err.message });
    }
  }

  return results;
}

// ── Example ──────────────────────────────────────────────────────────────────

const codes = ['DEUTDEDBBER', 'BNPAFRPPXXX', 'CHASUS33', 'INVALID123'];
const results = await validateBics(codes);

for (const r of results) {
  const status = r.valid ? '✓' : '✗';
  const name = r.bankName ?? 'unknown';
  console.log(`  ${status}  ${r.bic.padEnd(15)}  ${name}`);
}

7. Express.js integration

In a payment form or onboarding flow, wrap the API call in an Express route handler with proper error handling:

// routes/bic.js (Express)
app.get('/api/validate-bic', async (req, res) => {
  const bic = (req.query.bic ?? '').trim();

  if (!bic) {
    return res.status(400).json({ error: 'bic parameter required' });
  }

  let result;
  try {
    result = await validateBic(bic);
  } catch {
    return res.status(502).json({ error: 'BIC validation service unavailable' });
  }

  if (!result.valid) {
    return res.status(422).json({ error: 'Invalid BIC code' });
  }

  res.json({
    bic: bic.toUpperCase(),
    institution: result.bankName,
    country: result.countryName,
    city: result.city,
  });
});

// middleware/validateBicParam.js
async function validateBicParam(req, res, next) {
  const bic = req.body.bic ?? req.query.bic;

  if (!bic) {
    return res.status(400).json({ error: 'bic is required' });
  }

  try {
    const result = await validateBic(bic);
    if (!result.valid) {
      return res.status(422).json({ error: 'Invalid BIC code' });
    }
    // Attach enriched data for downstream handlers
    req.bicData = result;
    next();
  } catch {
    return res.status(502).json({ error: 'Validation service error' });
  }
}

// Usage: app.post('/transfer', validateBicParam, transferHandler);

8. cURL example

Deutsche Bank, Berlin branch (11-char BIC):

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

Same institution, primary office shorthand (8-char BIC):

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

Invalid BIC (wrong format):

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

9. Understanding the response

Response for XASXAU2SRTG (ASX Operations, Sydney):

{
  "valid": true,
  "bankCode": "XASX",
  "countryCode": "AU",
  "countryName": "Australia",
  "locationCode": "2S",
  "branchCode": "RTG",
  "bankName": "ASX Operations Pty Limited",
  "city": "Sydney",
  "branch": "RTGS Settlement"
}

Response for an 8-char BIC with no branch code:

{
  "valid": true,
  "bankCode": "BNPA",
  "countryCode": "FR",
  "countryName": "France",
  "locationCode": "PP",
  "branchCode": null,
  "bankName": "BNP Paribas",
  "city": "Paris",
  "branch": null
}

Response for an invalid code:

{
  "valid": false,
  "bankCode": "TOOS",
  "countryCode": "HO",
  "countryName": null,
  "locationCode": "RT",
  "branchCode": null,
  "bankName": null,
  "city": null,
  "branch": null
}

10. Edge cases to handle

/**
 * Normalise a BIC after successful validation.
 * @param {string} bic - Validated BIC code
 * @param {{ to11?: boolean }} options
 */
function normaliseBic(bic, { to11 = false } = {}) {
  bic = bic.toUpperCase().trim();
  if (to11 && bic.length === 8) {
    return bic + 'XXX';
  }
  if (!to11 && bic.endsWith('XXX')) {
    return bic.slice(0, -3);
  }
  return bic;
}

/**
 * Passive SWIFT participants have '1' as the second char of locationCode.
 */
function isPassiveParticipant(result) {
  const location = result.locationCode ?? '';
  return location.length === 2 && location[1] === '1';
}

const result = await validateBic('DEUTDEDB');
if (isPassiveParticipant(result)) {
  throw new Error('Cannot send outbound transfer to a passive SWIFT participant');
}

// Simple in-process TTL cache (use Redis for multi-process deployments)
const cache = new Map();
const TTL = 24 * 60 * 60 * 1000; // 24 hours in ms

async function validateBicCached(bic) {
  const key = bic.toUpperCase().trim();
  const cached = cache.get(key);

  if (cached && Date.now() - cached.ts < TTL) {
    return cached.data;
  }

  const data = await validateBic(key);
  cache.set(key, { data, ts: Date.now() });
  return data;
}

Node.js integration notes

When handling BIC/SWIFT Code in a TypeScript codebase, define a branded type to prevent accidental mixing of financial identifier strings at compile time:type BicCode = string & { readonly __brand: 'BicCode' }. 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 — BIC/SWIFT Code 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 BIC/SWIFT Code 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 BIC/SWIFT Code 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.