Wir haben lange nach einem Bezahlautomat (Bargeldeinzahlung an der Kasse mit Bargeldwechsler) gesucht. Da unsere Kassensystem unter Linux laufen und wir die Anbindung selbst machen wollten, war unsere erste Anfrage an einige Herstellter in Deutschland / Europa nach der Dokumentation, wie man den Bezahlautomaten ansprechen kann. Kurz: Wir haben nirgends eine brauchbare Rückmeldung erhalten. Das Ziel der deutschen Hersteller scheint immer zu sein, noch zusätzlich das eigene Kassensystem zu verkaufen.

Dann haben wir auf chinesischen B2B Plattformen das Suchen angefangen und nach kurzer Zeit hatten wir eine brauchbare API Beschreibung der Cashgenic Bezahlautomaten auf dem Tisch. Darauf hin haben wir das Gerät (in China) dort gekauft.

curl ist manchmal etwas komplexer. Deswegen machen wir diese Seite als kurze Hilfe zum Einstieg (mehr holt man sich dann aus der Dokumentation).

Hinweis: Natürlich gibt es curl auch für andere Betriebssysteme. Es gibt fast kein Betriebssystem wo curl nicht läuft. Daher gilt diese Anleitung nicht nur für Linux.

erster Schritt

Bargeldautomaten auf API Zugriff umstellen. Damit werden die Bluetoothverbindungen abgeschaltet und der Automat muss über Wlan oder Kabel verbunden sein. Laut Dokumentation sollte damit dann der Webeserver auf den Standard http und https Ports Informationen ausgeben - macht er bei uns nicht. Beide Ports sind zu. Das ist aber nicht wichtig. Bei der Aktivierung des API Zugriffes muss man einen Usernamen und ein Passwort vergeben.

jetzt geht es los

Token erstellen.

Das Token ersetzt in den weiteren Schritten Username und Passwort. Soweit ich das auswendig weiß, ist es einen Tag gültig. Wichtig ist es, curl mit der Option --insecure zu starten. Damit akzeptiert er das selbstsignierte Webserverzertifikat.

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' --insecure "https://IPADRESSE:44333/token?grant_type=password&username=USER&password=PASSWORT"

Wir schreiben mit folgendem 3 Zeiler das Token auf die Festplatte des Kassensystemes:

token=`curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' --insecure "https://IPADRESSE​:44333/token?grant_type=password&username=USER&password=PASSWORT" `
token=`echo $token|sed 's/.*access_token":"//'|sed 's/".*//'`
echo $token >.token.txt

verschiedene Befehle

(alle setzten voraus, dass das Token in der Datei .token.txt im jeweiligen Verzeichnis liegt). Wichtig ist, dass die Beträge ohne Punkt und Komma immer mit 2 Nachkommastellen angegeben werden. Also 1€ muss als 100 an den Bezahlautomaten gesendet werden (wie halt bei Kartenlesern auch).

Starten eines Kassiervorganges

curl -X POST --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer `cat .token.txt`" -d '{"request":"PayAmount","value":BEZAHLBETRAG}' "https://IPADRESSE:44333/session"

Kassiervorgang beenden (wenn er sauber fertig und abgeschlossen ist)

curl -X POST --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer `cat .token.txt`" -d '{"request":"CloseSession"}' https://IPADRESSE:44333/session

(das kann man auch zum Testen ob der Zahlvorgang schon abgeschlossen ist, verwenden)

Ansonsten kann man auch (das ist etwas sauberer) mit der Session ID, die mit dem Start des Kassiervorganges zurückgegeben wird, den Status abfragen:

curl -X GET --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer `cat .token.txt`" https://IPADRESSE:44333/status?transaction=IDKASSIERVORGANG

Kassiervorgang außerplanmäßig stoppen

curl -X POST --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer `cat .token.txt`" -d '{"request":"stopPayment"}' https://IPADRESSE:44333/session

Danach muss man noch ein CloseSession machen

Auszahlung aus der Kasse

curl -X POST --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer `cat .token.txt`"" -d '{"request":"RefundAmount","value":"AUSZAHLUNGSBETRAG"}' https://IPADRESSE:44333/session

Einstellung, wieviel Scheine zum Wechseln bereitgestellt werden sollen

Bei uns war, nach einem Ausbau des Scheinwechslers auf einmal kein Schein zum Wechseln mehr in der graphischen Oberfläche sichtbar und auswählbar. Sprich: Der Automat hätte nur noch mit Münzen gewechselt.

Per Api konnte man die Menge und Scheine neu definieren (und die sind danach auch in der GUI wieder aufgetaucht)

curl -X POST --insecure -H 'Content-Type: application/json' -H "Authorization: Bearer  `cat .token.txt`" -d '{"denominations":[{"country":"EUR","value":500,"enabled":true,"route":"Payout","floatLevel":5,"maxStoredLevel":0}]}' https://IPADRESSE:44333/denomination

Zum System

Der Cashgenic Bargeldautomat läuft unter Android auf einem Tinkerboard. Tinkerboard ist die Raspberry PI Alternative von Asus.  Das Board kommt mit anschaltbaren ADB Zugriff. Damit ist es möglich eine Shell auf dem Automaten zu starten und zusätzliche Programme zu installieren.  Das gibt viel Freiheit und macht Spaß.

Generell tut der Cashgenic einfach das was es machen soll: Geld kassieren und Wechseln.

Es gibt aber ein paar Einschränkungen, die nicht optimal sind.

• Das Gehäuse ist nicht so stabil, wie es für einen "Tresor" gehört. Wir haben hab daher zusätzliche Sensoren, die an die Alarmanlage angeschlossen sind, verbaut. Zusätzlich entleeren wir relativ oft.
• Der Münzzähler hat Einschränkungen: Wenn man beim Befüllen die Münzen "handvoll" einwirft, kommt es dazu dass die nicht sauber einzeln erfasst werden. Das Problem daraus: Er gibt zuviel Wechselgeld heraus. Das gleiche Problem trifft beim Schüttel, umkippen oder ruppigen Umtragen des Gerätes auf.
• Wir haben unsere Selbstbedienungskasse mehrsprachig. Obwohl der Cashgenic auch mehrere Sprachen kann, lassen sich diese nicht per API umschalten ...
• Der Schein- und der Münzwechsler sind so eng nebeneinander verbaut, dass man, wenn das Gerät verstopft ist, immer den jeweiligen Wechlser komplett ausbauen muss. D.h. pro Wechlser muss man 4 Schrauben lösen und die Kabel abziehen. Dann kann der komplette Wechsler aus dem Gehäuse entfernt werden und man kommt an alle Bereiche (ist auch zum periodischem Säubern so nötig).
• Die Pulverbeschichtung enstpricht nicht dem deutschen Standard. Ich weiß nicht, ob die deutschen Distributoren das Teil nachlackieren. Unsere Chinaversion hatte jedenfalls gravierende Mängel.  Ist nicht schlimm. Dafür haben wir nur weniger als 1/3 des deutschen Verkaufspreises bezahlt. Dafür kann man schon mal Fehler ignorieren oder nachlackieren.
• Nach einem Stromausfall und anschließenden Neustart hat der Cashgenic zwar die IP Adresse im Netzwerk angezeigt, war aber im Netzwerk unauffindbar. Ein sauberer Softwarereboot hat das Problem dann gelöst.
• Wir hätten gerne den Bildschirm des Geldwechsler zum Abschalten oder so, dass wir hier eigene Inhalte anzeigen können. Leider geht das aktuell mit der vorhandenen Software nicht. Vielleicht rüsten wir das nach.

Hintergrundinfos

Cashgenic ist ein Markenname für ein Komplettpaket für Bezahlsysteme. Diese wird von der englischen Firma Innovative Technology entwickelt und verkauft. Die API Dokumentation und weitere Infos bekommt man von deren Webseite: https://www.innovative-technology.com

Allerdings muss man sich einmalig mit Emailadresse anmelden um Zugriff auf die Supportdokumente zu erhalten. Das lohnt sich aber, weil man damit auch die Reinigungstipps für den Geldschein- und Münzwechsler bekommt. Innovative Technology bietet auch viele Ersatzteile auf deren Homepage an (englische Firma: Der Einkauf dort ist ähnlich komplex wie in China, England ist halt nicht mehr Teil der EU).

Dann gibt es zig Hersteller, die diese cashgenic Komponenten in ein eigenes Gehäuse packen (auch einige deutsche Firmen). Auch eine Heidelberger Firma (Produktname PerfectMoney) macht dies. Nur haben die einen kleineren Bildschirm und die Positionen von Schein- und Münzwechsler sind bei unseren Geräten genau anders ... und die Lackierung schaut auf den Bildern besser aus, als unsere.

Damit ist unser Bargeldwechsler ein typisches "Weltprodukt". Software, wichtige Hartware Teile kommen mit englischen KnowHow und teilweise aus England. Asus (Tinkerboard) ist eine taiwanesische Firma. Zusammengeschraubt und mit Gehäuse versehen wird das Zeug in China ...