FileMaker – her mit der Kohle!
Kreditkartenzahlungen mit FileMaker Go und SumUp Air entgegennehmen.
Im Folgenden möchte ich beschreiben, wie wir eine Kundenanforderung zum Empfang von Kreditkartenzahlungen vor Ort (POS / Point of Sale) umgesetzt haben.
Ausgangssituation
Unser Kunde hat seid Jahren eine selbst entwickelte Kassenlösung, die “alle Stückln spielt” – das ist ja der große Vorteil von FileMaker, dass man eben keine Lösung von der Stange kauft und die Firma dann an die Software ausrichten muss, sondern dass man die eigene FileMaker Lösung an die Firma anpassen kann.
Zahlungen von Endkunden können bar oder per Kreditkarte bezahlt werden. Bei Kreditkartenzahlungen wurde der Endbetrag, zB “134,50 €” dann an der Kassa angezeigt und vom Kassier per Hand als 13450 (als Centbetrag) ins Kreditkartenterminal eingegeben, zum Endkunden gedreht, der dann per Kreditkarte bezahlt hat. Sobald der Endkunde fertig war, drehte der Kassier das Terminal wieder zu sich um zu sehen, ob die Zahlung geklappt hat oder eben nicht.
Das funktioniert, hat aber den Nachteil dass es umständlich, zeitaufwändig und fehleranfällig ist (zB bei einem Zahlendreher, wenn der Kassier 13540 eingibt anstatt 13450. Das kam zwar nicht oft vor, aber es kam vor.
Da der Kunde bereits SumUp Terminals im Betrieb verwendete, haben wir uns die Schnittstellen für diese Terminals angesehen. Leider ist nicht alles Gold das glänzt…
SumUp
Es gibt von SumUp das “Air Kartenterminal”, welches nur im Zusammenspiel mit einer iOS oder Android App funktioniert, also nicht “Stand alone”.
Dann gibt es das “SumUp Solo”, das wie der Name impliziert, “solo”, also “Stand alone” ohne weitere Apps oder Geräte funktioniert. Das Blöde ist nur, dass die notwendigen REST APIs zum Ansteuern des Geräts seit Ewigkeiten auf “coming soon” steht – also in der Praxis noch nicht nutzbar ist (oder damals zum Entwicklungszeitpunkt so war, ich weiß nicht, wie das heute ist. Wissen Sie mehr? Bitte gerne unten in die Kommentare!)
Damit konnten wir nur das SumUp Air nutzen und haben uns die entsprechenden Schnittstellen angesehen. Wahnsinnig viel findet man nicht, aber es gibt eine 5 Jahre alte Dokumentation unter https://github.com/sumup/sumup-ios-url-scheme
Mit einer kleinen FileMaker Datei für FileMaker Go und diesen Infos haben wir eine funktionierende Demo gebaut und das ganze ausprobiert – und: es klappt!
(Die Datei können Sie unten kostenlos herunterladen!)
Ablauf
In der Praxis sieht es nun so aus, dass die FileMaker Kassenlösung, die vom Kassier bedient wird, die Zahlungsinfo an ein (altes) iPhone mit FileMaker Go schickt. Dieses iPhone ist in Endkundenrichtung ausgerichtet und zeigt dem Kunden dann den Endbetrag an. Sobald der Kassier die Zahlung startet, wird ein Script in FileMaker Go gestartet und die SumApp Anwendung startet automatisch und natürlich mit dem korrekten Betrag.
Der Endkunde hält seine Kreditkarte ans SumUp Air Terminal, bestätigt die Zahlung und FileMaker Go wird wieder automatisch aufgerufen.
Das klingt vielleicht kompliziert und fehleranfällig, aber ist es nicht. In der Praxis funktioniert das einwandfrei.
In FileMaker Go weiß ich nun, ob die Zahlung funktioniert hat oder nicht und ich kenne die Transaktions-ID. Mehr Infos bekommt FileMaker leider nicht.
Das ist aber nicht weiter schlimm: Über die Transaktions-ID und über die SumUp REST API können weitere Metadaten zur Zahlung abgerufen werden, wie beispielsweise die verwendete Kreditkarte, die Spesen oder einen Link zum Beleg (falls notwendig).
Hier ein Beispiel (gekürzt):
{
"id": "97753405-7701-42a7-12345678901234567890",
"transaction_code": "TCXHKZ337Q",
"foreign_transaction_id": "123456789012345678901234567890",
"merchant_code": "SCHUBECTEST",
"username": "office@schubec.com",
"amount": 1,
"currency": "EUR",
"timestamp": "2021-10-15T15:16:49.892Z",
"lat": 47.8005065917969,
"lon": 13.0698626311777,
"horizontal_accuracy": 29.16,
"status": "SUCCESSFUL",
"payment_type": "POS",
"simple_payment_type": "EMV",
"entry_mode": "contactless",
"verification_method": "none",
"card": {
"last_4_digits": "2012",
"type": "MASTERCARD"
},
"product_summary": "iPOS Test ",
"local_time": "2021-10-15T15:16:49.892Z",
"payout_date": "2021-10-19",
"payout_plan": "SINGLE_PAYMENT",
"payout_type": "BANK_ACCOUNT",
"installments_count": 1,
"products": [
{
"name": "iPOS Test",
"price": 1,
"quantity": 1,
"total_price": 1
}
],
"links": [
{
"rel": "receipt",
"href": "https://receipts-ng.sumup.com/v0.1/receipts/97753405-7701-42a7-a7db-18372cc3fcfe?mid=MDGF46AE&format=png",
"type": "image/png"
}
],
"auth_code": "12345",
"client_transaction_id": "urn:sumup:pos:sale:TEST:TEST"
}Weiter unten finden Sie ein Video zum Ablauf, denn ein Bild (Bewegtbild) sagt mehr als 1000 Worte!
FileMaker Go wiederum triggert ein Script auf der FileMaker Pro Kassenlösung, die Zahlung ist abgeschlossen und aus dem Drucker kommt der Beleg.
Bestimmt wollen Sie das nun selbst ausprobieren 🙂
Terminals
Bestellen Sie online ein SumUp Air Terminal, die Dinger kosten nicht viel (ca 40 €). Letztens habe ich die Geräte auch bei MediaMarkt zum Kaufen gesehen. Man bekommt die also mittlerweile überall nachgeschmissen.
SumUp Account einrichten
Sie brauchen dann noch einen SumUp Account. Ein solcher kann hier angemeldet werden.
Der Account selbst ist kostenlos, daher können Sie ziemlich risikofrei experimentieren.
Kosten entstehen erst in Form von Spesen bei tatsächlichen Transaktionen.
Beachten Sie jedoch, dass SumUp nicht alle Geschäftsmodelle als Partner akzeptiert.
Wenn Sie also eine “Sexuelle Begegnungsfirma” betreiben, “Illegale oder hinsichtlich der Legalität fragwürdige Geschäfte und Produkte” verkaufen, “Rauschmittel” am Bahnhof verchecken, “Schneeballsystem” aufsetzen oder andere fragwürdige Dienstleistungen wie FileMaker Programmierung anbieten, so können Sie SumUp nicht nutzen.
Kein Scherz! Mein Firmenaccount für die “schubec GmbH” wurde von SumUp nach 4 Monaten geschlossen. Was genau das Problem ist, weiß ich eigentlich bis heute nicht, ist mir aber auch egal, da ich persönlich eh keinen “Point-of-Sale” Verkauf in meinem (Home)office habe. Ärgern tut es mich trotzdem.
Mein Kunde, der die Geräte wirklich in seinem Laden einsetzt, hatte hier keine Probleme.
Wenigstens war SumUp so kulant und hat meine bezahlten Terminals per UPS abholen lassen, obwohl ich keine Verpackung mehr hatte und hat das Geld unkompliziert rücküberwiesen.
SumUp Entwicklereinstellungen
Ich gehe mal aus, dass Sie seriöseren Geschäften nachgehen als ich das tue und dass Sie einen Account bei SumUp registrieren konnten.
Rechts oben klicken Sie dann auf “Für Entwickler”.
Hier fügen Sie eine App-ID hinzu, zB com.ihr-firmenname.filemakergo oder ähnliches. Und ganz wichtig: com.sumup.appswitch, denn sonst funktioniert das Ganze nicht.
Das sind übrigens die Details, die solche Integrationen so kompliziert machen, denn solche Infos findet man oft erst nach stundenlanger Recherche im hintersten Winkel des Internets, wenn man schon an sich selbst und der Welt zweifelt, warum die Demo nicht läuft. Naja, in diesem Fall haben Sie es einfach und können es hier nachlesen 🙂
Einrichtung unter iOS
Auf ihrem iPhone / iPad installieren Sie nun die kostenlose SumUp App sowie FileMaker Go.
In FileMaker Go brauchen wir nun ein Script das eine URL aufruft. Die URL sieht wie folgt aus:
sumupmerchant://pay/1.0?amount=1¤cy=EUR&foreign-tx-id=97753405-7701-42a7-a7db-18372cc3fcfe&affiliate-key=184a65d9-198b-XXXXXXXXXXX&title=Test%20aus%20FileMaker&callbackfail=fmp%3A%2F%2F%24%2FSumUp.fmp12%3Fscript%3Dpos_sumup_error&callbacksuccess=fmp%3A%2F%2F%24%2FSumUp.fmp12%3Fscript%3Dpos_sumup_succes&skip-screen-success=trueAlles klar?
Zerlegen wir das mal in Einzelteile:
sumupmerchant://pay/1.0 sagt dem iPhone, dass wir die SumUp aufrufen wollen, um dort eine Zahlung zu starten.
?amount=1¤cy=EUR heißt, dass wir 1 Euro kassieren wollen.
&foreign-tx-id=97753405-7701-42a7-a7db-18372cc3fcfe ist unsere selbst genrierte Zahlungs-ID. Damit finden wir die Zahlung später im Webinterface von SumUp oder per REST-API.
&affiliate-key=184a65d9-198b-XXXXXXXXXXX ist Ihr persönlicher Affiliate Key, den Sie bei SumUp im Menü “Für Entwickler” sehen. Damit weiß SumUp, wer sie sind und wo die Kohle hingehen soll.
&title=Test%20aus%20FileMaker ist die URL-Kodierte Bezeichnung der Transaktion.
&callbackfail=fmp%3A%2F%2F%24%2FSumUp.fmp12%3Fscript%3Dpos_sumup_error sagt der SumUp App, welche URL aufgerufen werden soll, falls die Zahlung fehlschlägt. Besser sichtbar wird es, wenn wir die URL einmal dekodieren: fmp://$/SumUp.fmp12?script=pos_sumup_error
Die SumUp App wird also gebeten, FileMaker Go (fmp://) mit der bereits geöffneten Datei (das Dollar-Zeichen) SumUp.fmp12 aufzurufen und das Script pos_sumup_error zu starten.
Das heißt, wenn die Datei bei Ihnen NICHT SumUp.fmp12 heißt, oder Sie einen anderen Scriptnamen verwenden möchte oder die Datei nicht lokal am iPhone liegt sondern vom Server gehostet wird, dann MÜSSEN Sie die Werte anpassen, damit das ganze funktioniert!
&callbacksuccess=fmp%3A%2F%2F%24%2FSumUp.fmp12%3Fscript%3Dpos_sumup_succes ist das Äquivalent zu callbackfail. Hier sagen wir SumUp, dass FileMaker Go aufgerufen wird, aber mit dem Script pos_sumup_succes (inklusive dem Schreibfehler bei succes, aber Hauptsache das Script in der Datei heißt so wie wir es hier angegeben haben!)
&skip-screen-success=true letztlich sagt der SumUp App, dass wir keinen “Danke, die Zahlung war erfolgreich”-Schirm sehen wollen sondern dass direkt FileMaker Go aufgerufen werden soll (und wir dann dort selbst für entsprechende Meldungen sorgen.)
That’s it. Rufen Sie die oben genannte URL am iPhone/iPad auf, zB mit dem FileMaker-Befehl URL öffnen.
SumUp App
Zum Einrichten der SumUp App starten Sie diese am iPhone/iPad und erlauben Sie Bluetooth, damit die App das Kreditkartenterminal finden kann.
Loggen Sie sich in Ihren Account ein.
Klicken Sie auf “Jetzt loslegen”, damit die App sich mit dem Terminal verbindet.
Starten Sie das Verbinden…
..und warten Sie, bis die Verbindung geklappt hat. Sie sind nun Einsatzbereit!
Sie können nun (mit FileMaker) Kreditkartenzahlungen entgegennehmen!
Video zum Ablauf
Wenn Sie auf den Playbutton klicken, wird das Video von YouTube geladen. Dabei werden persönliche Daten wie IP-Adressen und ev. Cookies an YouTube übertragen.
Ausblick
Wie im Video kurz zu sehen sowie oben als Beispiel gekürzt ausgegeben, kann man per REST-API sehr viele Metadaten zu den einzelnen Transaktionen abrufen. Falls hier Interesse besteht, werde ich das in einem zukünftigen Beitrag beschreiben.
Demodatei herunterladen
Hier können Sie eine kostenlose Demodatei herunterladen, damit Sie das oben Genannte einfach ausprobieren und ggf. in Ihre Lösung integrieren können.
Alternativen
Das Beispiel zeigte die Integration von SumUp Kreditkartenterminals. Wenn Sie auch so eine pöse pöse FileMaker-Softwarebude haben und keinen SumUp Vertrag bekommen (siehe oben), dann gibt es auch andere Kreditkartenterminals die per REST API angesprochen werden können. Zum Beispiel hier in Österreich das hobex ViA Pro Terminal. Da kann man dann einfach per HTTP POST Abfrage und ein bisschen JSON eine Zahlung starten. Mit dem Parameter tid wird gesteuert, welches Terminal die Zahlung entgegen nehmen soll. Einfacher geht es fast nicht mehr.
curl -X POST \
https://hobexplus.brunn.hobex.at/api/transaction/payment \
-H 'content-type: application/json' \
-H 'token: XXXXX \
-d ' {
"transaction": {
"transactionType": 1,
"transactionId": "20181009140821075",
"tid": "3510224",
"currency": "EUR",
"reference": "123",
"amount": 1.5,
"language": "DE"
}
}'
Die Ansteuerung dieser Terminals werde ich ebenfalls in einem zukünftigen Blogartikel beschreiben!
Im Dialog bleiben!
Es freut mich, wenn Sie bis hier her gelesen haben!
War der Beitrag interessant?
War etwas ungenau beschrieben oder haben Sie einen Fehler entdeckt?
Haben Sie Interesse an neuen Beiträgen? Wenn ja, zu welchen Themen?
Nutzen Sie die Kommentarfunktion hier auf der Seite, diskutieren Sie im FileMagazin Forum, schreiben Sie mir ein Email an bernhard.schulz@schubec.com und abonnieren Sie den Newsletter um über neue Beiträge informiert zu werden! Bleiben wir in Kontakt!
