English Abstract about KONTOPRUEF-OFFLINE

Contents of this page:

• Benefit of Bank Account Verifying
• How does it work?
• When and why use the offline version?
• How the offline version works
• Updates
• Technical Information
  • Offline Version
    • Windows
      • COM Server
      • Dynamic Link Library
    • Linux
• Testing and Demos

Benefit of Bank Account Verifying

KONTOPRUEF is a system for verifying bank account numbers (and addresses). The benefit of verifying bank account numbers is to avoid typos and/or real errors when customers enter their checking account number for example into a web form in order to let the merchant charge their checking account for some purchase.

Frequent errors include, for example, 7601085 as bank routing code instead of 76010085, or 731495 instead of 734195 as account number, or 100003791 instead of 1000003791, and so on. Because the merchant does not know the correct account data of the customer, he must believe in the correctness of the data.

Some days after charging the customer's account, the merchant receives a chargeback from the customer's bank, along with chargeback fees. If the merchant had verified the account data before charging the customer's account, the chargeback (and paying the fees) would have never happened!

How does it work?

Of course, the KONTOPRUEF system does not know all bank account numbers of all German customers. However, this is not necessary. German bank accounts consist of two parts: the Bankleitzahl (abbr. Blz, the bank routing code) and the Kontonummer (abbr. Kto, the account number). With this information, bank data can be verified as follows:

• First, the existence of the bank routing code can be verified, just by a lookup in a table (there are about 4,000 bank routing codes).
• The records in this table indicate the specific account number verifying procedure (there are about 120 different procedures).
• Using the appropriate procedure, the check digit in the account number is calculated. Comparing the calculated check digit with the data given by the customer, the account number can be classified as "good" (this means, possible at the given bank) or "bad" (this means, impossible at the given bank).

As you can see, KONTOPRUEF only verifies that a given bank account is just possible. But it has turned out that this is good enough to reduce chargebacks, caused be erroneous customer inputs, by 90%!

KONTOPRUEF especially helps when used "early" in order processing. If you have a webshop, don't let your customer click on the "Submit Order" button as long as his bank data is wrong. Or, if you have a call center, install KONTOPRUEF directly into the agent's order software.

When and why use the offline version?

First of all: If you don't know why, then don't use the offline version! The "normal" way to use KONTOPRUEF is the ONLINE or the INHOUSE version (have a look a the version comparison table).

However, if you are absolutely sure that you need the OFFLINE version, you'll find a lot of technical information in the following paragraphs.

How the offline version works

Withe the offline version, the complete KONTOPRUEF software is installed on your computer – with Windows or Linux. An Internet connection is not generally needed (but helps when downloading software updates). You have to care for regular updates: download, unpack and activate new data files.

Updates

Since the Blz table and the account verifying procedures change from time to time (at least four times a year: at the beginning of March, June, September and December), you have to care for updates of the "data file" of KONTOPRUEF if you are using the offline version.

When an update is available, the registered users are notified by e-mail. The new data file must be downloaded, unpacked and activated. You can do this manually from a web page, or you use the built-in functions in the KONTOPRUEF software (if the computer with KONTOPRUEF has an Internet connection, of course).

If you download the new data file manually, it comes as a compressed and electronically signed wbp ("Windows Bank Packet") or lbp ("Linux Bank Packet") file and must be decompressed before using. KONTOPRUEF has built-in functions to decompress the file to a wbd ("Windows Bank Data") or lbd ("Linux Bank Data") file. If you want to decompress the file manually, you can use the user interface of Bank.exe (Windows) or the freely downloadable KtoTool software (Linux).

Technical Information

In this chapter, you get some information about how to implement KONTOPRUEF into your own software. Most of the links lead to German web pages (sorry for that), but since most procedure, variable, and parameter names in the software are English anyway, you should not get too much comprehension problems. If you have any questions, just send an e-mail to support@kontopruef.de.

Offline Version Technics

Using the offline version, you have to install some piece of software on your computer, which is a bit different between Windows and Linux.

Windows

With Windows, you have two choices: using the COM server of KONTOPRUEF (according to Microsoft's "Component Object Model", the preferred method) or a DLL (Dynamic Link Library; has some disadvantages, but may be helpful under certain circumstances).

COM Server

Installing the COM server manually is pretty simple:

1. Download the ZIP file KtoPruef.zip.
2. UnZIP the file (with Window's "Compressed Folder" from XP on, or with WinZip).
3. Make sure that the Windows account you are using has administration rights. (This is inevitable because registering a COM server is a system-wide operation and is stored in the HKEY_CLASSES_ROOT tree of the Windows registry.)
4. Start the program Bank.exe, either without any parameters (then you get some user interface where you can try out KONTOPRUEF's functions manually), or with the parameter /regserver – this is a "quiet" registration without any visual display.

That's it! If you want to remove KONTOPRUEF from your system, only two steps are required (of course, you'll need administration rights again):

1. Start the program Bank.exe with the parameter /unregserver. This removes the COM server registration from the Windows registry.
2. Delete the directory where the KONTOPRUEF files reside.

Alternatively, you can download KONTOPRUEF's setup.exe and install it just like any other installation software.

For just using KONTOPRUEF's functions via COM, no administration rights are required, of course. How COM functions can be used depends on your application development system. Normally, it looks similarly like this:

Dim KtoPruef As New Bank.KtoPruef
Dim Result as Integer
Result = KtoPruef.TestBlzKto(Blz, Kto)

If you are using Visual Basic or VBscript in MS-Office, you have to install the KONTOPRUEF references within the VB editor in order to use the Bank.KtoPruef object as in the above example. Look for a menu item like Extras - References and put a check mark at Hanft Bank-Bibliothek.

You'll find examples for ASP, MS-Office/VBScript, Delphi, and Java on the tech page. A complete list of procedures, functions, parameters, and results is included in the func page.

Dynamic Link Library

As you have seen in the COM server section, the installation of KONTOPRUEF is required on every single computer which uses KONTOPRUEF's functions. And you need administration rights on each computer for installing. This may be annoying in a large network. If you want to avoid that hassle, there is another variant of KONTOPRUEF's offline version: a dynamic link library (DLL), called KtoLib30.dll. You can put that DLL onto a file server in your network and access it from all workstations, without any software installation. Different to COM server naming, the procedures and functions are named as in the Linux version, for example KtoPruefTestBlzKto instead of KtoPruef.TestBlzKto. The "calling convention" is stdcall, as usual for Windows system software.

All this sounds too good to be true, and indeed, there are some disadvantages using the DLL variant:

• All files from the KtoLib ZIP file must reside either in the same directory as your application software, or the KONTOPRUEF directory must be included in the PATH environment variable;
• since a DLL is executed in the processor's local address space of your application, there is no synchronization between different processes: for example, if one of your processes replaces the KONTOPRUEF data file by a new one, all other processes have to call KtoUpdateActivate themselves to activate the newly installed data file (with the COM server, the data file administration is centralized and automatically global for the whole computer);
• the DLL variant is possibly not 100% thread-safe;
• embedding a DLL into own applications is generally not as simple as a COM server.

Linux

For linux, there is just a single variant of KONTOPRUEF: a set of "shared libraries" which you can link to your application software.

To install the Linux version, do the following:

1. Download the file KtoPruef30.tar.gz.
2. Unpack the file using gunzip KtoPruef.tar and tar xvf KtoPruef.tar.
3. Include the directory where the KONTOPRUEF libraries reside into the environment variable LD_LIBRARY_PATH; for example, export LD_LIBRARY_PATH=/usr/local/ktopruef:$LD_LIBRARY_PATH.
4. Create the file /etc/KtoPruef.conf with the following content:

   [Directories]
   data=/usr/local/ktopruef

   (in the "data" line, you have to specify where the KONTOPRUEF data file resides; this is not necessarily the same directory as the libraries themselves).
5. Move the .h files to some directory where your compiler can find them.

Using the bank account verification functions is then pretty simple. A short gcc C program, called TestBlzKto.c, looks, for example, like this:

#include "KtoPruef.h"
int main(int argc, char *argv[])
{ int Result;
  if (argc!=3) { 
    printf("usage: %s Blz Kto\n", argv[0]);
    return 500; }
  Result = KtoPruefTestBlzKto(argv[1], argv[2]); 
  printf("Result: %d, this means: %s\n",
    Result, KtoPruefGetErrorMessage(Result));
  return Result; }

Compile this program with

gcc -o TestBlzKto TestBlzKto.c libKto*.so

(ignore the message bplKtoBase.so: the use of `tempnam' is dangerous, better use `mkstemp') and start the program TestBlzKto with the bank routing code and the account number as parameters. For example, using the bank routing code 76010085, you should get the result 0/Ok for the account number 1856, and the result 13/Check digit wrong for the account number 1857.

Of course, you can do the same with g++ C++; you just have to use the extern "C" directive for the KONTOPRUEF include files:

#include <iostream>
extern "C" {
#include "KtoPruef.h"
}
int main(int argc, char *argv[])
  { int Result;
    if (argc!=3) {
      std::cout << "usage: " << argv[0] << " Blz Kto\n";
      return 500; }
    Result = KtoPruefTestBlzKto(argv[1], argv[2]);
    std::cout << "Result: " << Result << 
      ", this means: " << KtoPruefGetErrorMessage(Result) << "\n";
    return Result; }

If you use some other software for your application development, first check if it can call "shared libraries" directly. If it cannot, you can almost always call external programs (mostly by some "exec" command). For example, an "external program" which just returns (silently) a bank account verification result by its exit code is as short as this:

#include "KtoPruef.h"
int main(int argc, char *argv[])
{ return KtoPruefTestBlzKto(argv[1], argv[2]); }

You can then process the exit code of KONTOPRUEF in your application software.

Testing and Demos

To check if KONTOPRUEF works with your application software, there are many testing possibilities without any purchase or inquiry.

Testing the Offline Version

With the offline version which you can download, you get a completely working software (which will not even change if you later decide to purchase the software); just the demo data file is limited to about 1,500 bank routing codes (instead of about 4,000 when you purchase the software).

Limited to the covered bank routing codes, using the downloaded version, you can execute all functions which are listed on the func page.

For a quick check if the software is working, call TestBlzKto with the bank routing code 76010085: With the account number 1856, KONTOPRUEF should return a result of 0/Ok; with the account number 1857, KONTOPRUEF should return a result of 13/Check digit wrong. If you get these results, you have installed KONTOPRUEF functioning!