EZLeser

EZLeser: An automatic payment stub reader

In Switzerland, it appears to be common to pay bills via payment stubs called "Einzahlungsscheine". When paying bills online, it is necessary to enter some of the information from the stub into the online bill-payment form. This is particularly tedious for the orange-colored version of the payment stub, since it has a 27-digit reference number that needs to be typed in by hand.

There are stub-reader scanner-pens available (e.g., "PayPen") to simplify this task, but as far as I know, they don't support Linux. Furthermore, the readers are not cheap (SFr. 150 or more). Considering that a fair number of people already own a scanner (e.g., through an All-in-One device), it seems silly to have to pay that much and have to deal with yet another device on your desk, when you already have a perfectly good scanner.

To alleviate these problems, we created a Firefox-extension which will automatically scan a payment stub, read the reference-number, payment-amount, and the account-numbers off the stub, and then enter the information in the appropriate places on the online bill-payment form.

EZLeser is free and distributed under GNU GPL v3.

Usage

Once installed (see "Installation" for details), typical usage is as follows:

Log onto your online bill payment system.
When you're ready to make a payment, put the Einzahlungsschein in the scanner (orientation doesn't matter), then right-click inside the browser-window and call up "Einzahlungsschein Lesen".
The browser's status-bar should now show "EZ Leser: Am Dokument Lesen".
A few seconds after the scanner finishes scanning the Einzahlungsschein, the browser's status-bar should display "EZ Leser: 6 Werte gefunden".
The payment form should now have the payment account-number, the amount, and the reference-number prefilled with the values read from the Einzahlungsschein.

That's it!

Troubleshooting

If reading a payment stub fails with the message "EZ Leser: Keine Felder gefunden" you could try to reorient the stub in the scanner. Reading the stub may work better if its aligned with the edge of the scan-surface. Specifically, it may work best if the long side of the stub is aligned with the short side of the scanner. In any case, if reading of a stub fails, I'd appreciate it if you could send me a copy of the scanned image (assuming you're comfortable sharing the image of the payment stub with me). This is most easily done with the following script:

#!/bin/sh
file="test-$(date +%y%m%d-%H%M%S)"
ppm="$file.ppm"
tiff="$file.tiff"
/usr/bin/scanimage --mode color --resolution 300 > /tmp/$ppm
ppm2tiff -c lzw /tmp/$ppm /tmp/$tiff
/usr/bin/mime-construct --to dmosberger@gmail.com \
        --subject "Test image $tiff" \
        --file-attach /tmp/$tiff
/bin/rm -f /tmp/$tiff /tmp/$ppm
exit 0

You can download this script here. With this script installed, simply execute "do-scan" and the image will be scanned and emailed to me.

If reading the payment stub works, but you don't get the form filled in automatically, you may need to edit the map file and adjust it for your payment-site. See "Installation" for details.

Prerequisites

A Linux-computer.

A scanner that is supported by SANE. The scanner should be able to produce a color-image with the command:
```
/usr/bin/scanimage --mode color --resolution 300 >/tmp/image.ppm
```
/usr/bin/ppm2tiff needs to be installed (on Debian, it's part of the libtiff-tools package).

Installation

The "EZ Leser" is distributed as a Firefox-extension. Firefox v2 and v3 are supported. From within Firefox, click on this link to install the extension:
EZ Leser Extension for Firefox
Once installed, restart Firefox so the extension is active. You can tell the extension is active when the status bar displays "EZ Leser: Bereit" in the lower-right corner of the Firefox window. The extension has a preference which you can use to specify the name of the SANE device to use. You can get to this preference by clicking "Edit->Preferences->Main->Manage Add-ons...->Einzahlungsschein Leser 2.0->Preferences".
Depending on the web-site you use for bill-payment, you may need to edit the map file, which is stored in the Extension directory. For example in
```
	$HOME/.firefox/default/*/extensions/ezleser\@mosberger-consulting.com/map
      
```
This file tells the EZLeser what the names of the input-fields are that need to be filled in. There are several type of input-fields:

refnr
27-digit reference number.
amount
The payment amount, as a decimal number (e.g., "150.35").
amountWhole

The whole part ("Franken") of the payment amount (e.g., "150").
amountFraction
The fractional part ("Rappen") of the payment amount (e.g., "35").
acctnr
The account number as a string of digits (e.g., "12356789").
acctnrFormatted
The account number formatted with dashes (e.g., "12-35678-9").

You can map an HTML input-element name to a field-type simply by writing on one line the name, an equal sign (=), and then the field type. For example, on the online-bill-payment system of the Neue Aargauer Bank, input-element names are "referenceNumber", "amount", and "creditAccount", so the following entries would make sure the form gets filled in properly:
```
      creditAccount=acctnrFormatted
      amount=amount
      referenceNumber=refnr
    
```
To find out what the names of the input-fields should be, log into your online-bill-payment system and go to the page where it prompts you for the bill information. Right-click in the brower's window and select "View Page Source". In the window that displays the page source, search for "<input" tags. The name specified in the "name" attribute of these tags is what you need to use in the map file.
You can add as many mappings to the map file as you like. If you wish, you can provide us with the mappings for the web-sites you use and we'll include them in future distributions. At the moment, the map-file included in the distribution supports the Raiffeisen and Neue Aargauer Bank web-sites.
The map file supports line comments. Any characters appearing after a hash-mark ("#") are ignored up to the end of the line. To include a literal hash-mark, prefix it with a backslash (e.g., "\#");

Sources

The EZLeser sources are distributed under GNU GPL v3. The source code for ezleser, ppmautorot, and extract_fields are available here:

ezleser-src-100711.tar.gz

The JavaScript code used by EZLeser is included in the Firefox extension file (.xpi). Just unzip that file to get at its contents.

The Tesseract OCR reader is distributed by Google Code. To get Tesseract to reliably recognize numbers in the OCR font used on the payment stubs, I used this training file:

ocrb-train1.tiff

This file, in turn, was created with OpenOffice, using the freely available OCRB10 TrueType font available here.

Credits

EZLeser uses Tesseract as its OCR engine.