KtoBLZCheck is a package providing up to date bankdata information in several formats and a library to access and check account numbers and bank codes of German and other banks.

Naming explanation: This library provides a check for "kto" (German abbreviation for account number) and "blz" (German abbreviation for bank identification code, A.B.A. code or similar).

Introduction

Both a library for other programs as well as a short command-line tool is available. It is possible to check pairs of account numbers and bank codes (BLZ) of German and other banks, and to map bank codes (BLZ) to the clear-text name and location of the bank. Python bindings are provided as well (requires the python module "ctypes").

Requirements

cmake
c++ compiler (gcc, clang, mingw or msvc)
python 2 interpreter and development package (e.g package python-base and python-devel on openSUSE)
alternativly python 3 interpreter and development package (e.g package python3-base and python3-devel on openSUSE)
internet access for downloading bankdata files (optional)

Compiling Ktoblzcheck

First you need to unpack the source either by fetching from git with

cd <some-root-dir>
git clone https://git.code.sf.net/p/ktoblzcheck/code ktoblzcheck

This will create a directory named ktoblzcheck, which you need to specify later as source directory.

or from a tarball located at https://sourceforge.net/projects/ktoblzcheck/files/

cd <some-root-dir>
tar -xzf <download-root>/ktoblzcheck-1.49.tar.gz

This will create a directory named ktoblzcheck-1.49, which you need to specify later as source directory.

There are different ways to compile ktoblzcheck depending on the platform and/or used compiler.

Unix like OS

For compiling ktoblzcheck on Unix like OS, after you got the sources as described above, you need to run:

mkdir ktoblzcheck-build
cd ktoblzcheck-build
cmake <ktoblzcheck-src-dir> [<additional-cmake-options>] [1]
make
make install

[1] for available cmake options see below

GCC/Windows (MinGW32)

You need to download a MingW compiler from http://sourceforge.net/projects/mingw-w64/. After unpacking and placing the bin dir into the PATH environment variables you need to run

mkdir ktoblzcheck-build
cd ktoblzcheck-build
cmake -G "MinGW Makefiles" <ktoblzcheck-src-dir> [<additional-cmake-options>] [1]
mingw32-make
mingw32-make install

MSVC/Windows

For compiling ktoblzcheck for MSVC you need to open a MSVC command shell

mkdir ktoblzcheck-build
cd ktoblzcheck-build
cmake -G "NMake Makefiles" <ktoblzcheck-src-dir> [<additional-cmake-options>] [1]
nmake
nmake install

Running

ktoblzcheck <your-bank-id> <your-account-id>

Some example BLZ;Account-ids are the following from Bundesbank: 64192220;12345008 20210200;0240334000 56061472;0000191919

The ktoblzcheck command has several optional arguments; use "--help" to see a summary. (The argument –outformat by default is "multiline". The other choice, "--outformat=oneline", gives you one line of result with the following tab-delimited fields: "bank name, bank city, result of check, BLZ, accountId, name of the checking algorithm". This format is more suitable if multiple account numbers are read from an input file using the option –infile.)

Running tests

ktoblzcheck contains several test applications to check the implementation and some parts of the build system.

These tests can be run after building with the following command:

cd ktoblzcheck-build
<used-make-tools> test

Additional CMake Options

The cmake build system provides some additional options, which could be specified on the cmake command line in the form -D<option-name>=

option name                    platform             value              default value
-------------------------------------------------------------------------------------
ENABLE_BANKDATA_DOWNLOAD         all               OFF/ON                  ON
Enable download of raw bank data file - if this option is set to OFF, cmake uses
already present bank data file

INSTALL_RAW_BANKDATA_FILE        all               OFF/ON                  OFF
Install raw bank data file - this option is useful for 3rdparty applications like kmymoney

INSTALL_SEPA_BANKDATA_FILE       all               OFF/ON                  OFF
Install sepa provider data file in csv format

ISCC_DIR                        Windows              path                 not set
Specify the installation directory of the inno setup compiler that is required
to create a setup installation program.

USE_WINE                        Windows              OFF/ON                OFF
Enable support to run cross compiled applications on Linux with wine.

Using ktoblzcheck

To use the library in your own application it is necessary to find an installed development package from ktoblzcheck. The necessary procedure depends on the build system used:

cmake

Add the following cmake fragment to the top level CMakeLists.txt file:

find_package(KtoBlzCheck)
...
if(KtoBlzCheck_FOUND)
    add_executable(myapp mysource.cpp)
    target_link_libraries(myapp ktoblzcheck)
endif()

Autotools

... to be finished

C++ Code

You can then use the following code fragment in your C++ code, for example:

#include <ktoblzcheck.h>
...
AccountNumberCheck var;
std::string bankId = "64192220";
std::string accountId = "12345008";
Result result = var.check(bankId, accountId);

For more information, see AccountNumberCheck.

#include <iban.h>
...
IbanCheck var;
std::string iabn = "DE07123412341234123412";
Result result = var.check(iban);

For more information, see IbanCheck.

Installer

On Windows you may install the "Inno Setup Compiler" from http://www.jrsoftware.org/isdl.php, run cmake with the install path added to the cmake command line e.g.

cmake <ktoblzcheck-src-dir> -DISCC_DIR=<inno-setup-install-dir>

and run

<used-make-tools> <used-make-tools> setup

so that a self-installing setup.exe file will be created.

Common CMake targets

The cmake build system provides several build targets, which could be displyed by running

<used-make-tool> help

in the build directory. Common targets are:

dist   - build source tarball
rpm    - build binary rpm
srpm   - build source rpm
test   - run test suit

Bank List Format

A file with all bank codes (BLZ Datei) can regularly be retrieved from the Deutsche Bundesbank at bundesbank.de, more specifically from

http://www.bundesbank.de/de/aufgaben/unbarer-zahlungsverkehr/serviceangebot/bankleitzahlen

Updating to the most recent bank data file is done automatically by the build system if cmake configure option -DENABLE_BANKDATA_DOWNLOAD=1 has been set (which is the default).

Since version 1.16, ktoblzcheck installs multiple bankdata files which are valid at different dates. Each of the bank code files from the Deutsche Bundesbank is valid for three (3) months. Ktoblzcheck ships with the bankdata file from several validity periods: One file is valid at the date of release; and the second file is valid in the three subsequent months (i.e. it is newer). If even the newest file is outdated at the day of when libktoblzcheck is used, a warning line will be printed to stderr and the newest file will be used anyway.

Note: The available files (marked by the first valid day as part of the filename) and their validity period are looked up by simply taking all files in the BANKDATA_PATH folder into consideration. Hence, you can install a new bank data file by copying the correct file format into that folder, which is done automatically by the cmake build system

Note 2nd: The bank data file "bankdata.txt" with no date in the file name is not used anymore. It used to be a one-to-one copy of the newest file, but with ktoblzcheck-1.35 this file is neither used nor shipped anymore.

Note 3rd: All of the above is ignored if a bankdata file is explicitly requested by the command line argument –file=... . In that case the specified file is used and no further date comparisons are made.

The bankdata.txt file used by ktoblzcheck contains less information than the file provided by the Bundesbank. Namely, it contains only four tab-delimited columns and only those lines that refer to the main institutes instead of all branches. The provided python script src/bankdata/bundesbank.py (provided by Ralf Habacker) will automatically convert the Bundesbank's ascii file into the required ktoblzcheck format.

If you got the Bundesbank BLZ file in excel format, the four columns for bankdata.txt are A, O, G, J, in that order, and it has only those lines which have a '1' in column B.

Authors

The original author was Fabian Kaiser fabia.nosp@m.n@op.nosp@m.enhbc.nosp@m.i.de. The current maintainer is Christian Stimming stimm.nosp@m.ing@.nosp@m.tuhh..nosp@m.de and Alexander Kurz sf2@b.nosp@m.lala.nosp@m..de.

For contacting the authors, please write to the mailing list < ktobl.nosp@m.zche.nosp@m.ck-cv.nosp@m.s@li.nosp@m.sts.s.nosp@m.ourc.nosp@m.eforg.nosp@m.e.ne.nosp@m.t >. This list is subscriber-only which means you need to subscribe if you want to post to the list. Subscription information can be found on https://sourceforge.net/projects/ktoblzcheck/lists/ktoblzcheck-cvs

Related projects

A ruby interface to ktoblzcheck: https://rubygems.org/gems/rbktoblzcheck/versions/0.1.2

A different implementation of this checking algorithms: http://kontocheck.sourceforge.net/