FinTS German Bank Institute Database

Common errors

• Error: Cannot find module 'fints-institute-db'

  cause The package has not been installed or is not correctly resolved in the module path.
  fix Run `npm install fints-institute-db` in your project directory. Ensure your module bundler or Node.js environment is configured to find `node_modules`.

• TypeError: banks.filter is not a function

  cause The imported `banks` variable is not an array as expected. This could happen if the package's export structure changed or if the import statement is incorrect (e.g., trying to destructure a default export).
  fix Ensure you are using the correct import statement for the default export: `import banks from 'fints-institute-db';` (ESM) or `const banks = require('fints-institute-db');` (CommonJS).

• Property 'blz' does not exist on type 'BankInstitute'.

  cause When using TypeScript, the type definitions might be outdated, incorrect, or missing for the 'blz' field (or any other field you are trying to access).
  fix Check for `@types/fints-institute-db` or ensure the package's built-in types (if any) are correctly referenced. If the types are genuinely missing or incorrect for a specific field, consider using type assertions (`(bank as any).blz`) or extending the type definitions in your project.

Warnings

• breaking Major version updates (e.g., v0.x.x to v1.x.x) may introduce changes to the data schema (e.g., renaming fields like `blz`, `bic`, `pinTanURL`, or adding/removing flags like `rdh7`). This could break applications relying on specific field names or data types.
  Fix: Always review the release notes for new versions for schema changes. Consider adding runtime data validation or using TypeScript with up-to-date type definitions if available.
• gotcha The `pinTanURL` and `hbciDomain` fields, which are critical for FinTS connections, can change without immediate package updates. Relying solely on this static database for real-time endpoint validity in production environments might lead to connection failures.
  Fix: For mission-critical applications, consider implementing a fallback mechanism, an external endpoint validation service, or a configuration overlay to override potentially outdated URLs.
• gotcha The `updated` field for individual bank entries is often `null` in the provided data format. This makes it difficult to ascertain the freshness of specific bank data points directly from the entry itself.
  Fix: Assume the overall package version reflects the data freshness. Monitor the package's release frequency and changelog on npm or GitHub for updates to the underlying data.
• gotcha While the package aims for comprehensive coverage, it might not always include every niche banking institute or reflect the very latest changes from all German financial institutions immediately. Data is community-driven and updated periodically.
  Fix: If a specific bank is missing or has incorrect data, verify against official bank sources or contribute to the project to improve data accuracy.

Install

• npm install fints-institute-db npm
• yarn add fints-institute-db yarn
• pnpm add fints-institute-db pnpm

Imports

• banks
  wrong:

  import { banks } from 'fints-institute-db';

  correct:

  import banks from 'fints-institute-db';

  The package exports the entire bank list as its default export, which is an array. There are no named exports.
• banks

  const banks = require('fints-institute-db');

  CommonJS default import for Node.js environments. The exported value is an array.
• BankInstitute
  wrong:

  import { BankInstitute } from 'fints-institute-db';

  correct:

  import type { BankInstitute } from 'fints-institute-db/types';

  If using TypeScript, explicit type imports for the structure of a single bank entry are available from a subpath. The package might not always ship with comprehensive type definitions, so community-provided types (`@types/fints-institute-db`) might be needed for older versions or more specific fields.

Quickstart

Demonstrates how to import the bank database, find a specific bank by BLZ, filter banks by organization, and access their properties.

import banks from 'fints-institute-db';

// Find a bank by its Bankleitzahl (BLZ)
const blzToFind = '10030600'; // Example BLZ for 'Bankhaus Kruber'
const bankByBlz = banks.find(bank => bank.blz === blzToFind);

if (bankByBlz) {
  console.log(`Found bank '${bankByBlz.name}' in '${bankByBlz.location}' with HBCI URL: ${bankByBlz.pinTanURL}`);
} else {
  console.log(`Bank with BLZ ${blzToFind} not found.`);
}

// Filter banks by organization (e.g., 'DSGV' for Sparkassen)
const dsgvBanks = banks.filter(bank => bank.organisation === 'DSGV');
console.log(`
Found ${dsgvBanks.length} banks belonging to DSGV (Sparkassen-Finanzgruppe). Example:`);
if (dsgvBanks.length > 0) {
  console.log(`  - ${dsgvBanks[0].name}, BIC: ${dsgvBanks[0].bic}`);
}

// Get a count of all registered banks
console.log(`\nTotal number of banks in the database: ${banks.length}`);