Was muss ich bei einem SumUp Zahlugsterminal einstellen?

SumUp-Terminal in PhoenixDS Online-Pay

Zweck dieser Dokumentation

Diese Anleitung beschreibt die Einrichtung eines SumUp Solo oder Virtual Solo in PhoenixDS Online-Pay.

Die Anbindung erfolgt über die SumUp Cloud API. Online-Pay und das SumUp-Terminal kommunizieren daher nicht direkt über eine lokale IP-Adresse miteinander. Beide Geräte benötigen eine funktionierende Internetverbindung.

Wichtig: Für Zahlungen werden ein SumUp-Händlerkonto, ein geheimer API-Key und die für Kartenpräsenz-Zahlungen vorgesehenen Affiliate-Daten benötigt. Die Zugangsdaten müssen vertraulich behandelt werden.

Funktionsprinzip

PhoenixDS Online-Pay  ------ HTTPS ------>  SumUp Cloud API
                                                |
                                                |
                                                v
                                       SumUp Solo / Virtual Solo

Online-Pay übermittelt die Zahlungsanforderung an SumUp. Die SumUp Cloud leitet sie an den gekoppelten Reader weiter. Das Ergebnis wird anschließend von Online-Pay abgefragt und an das Kassensystem zurückgegeben.

Das SumUp-Terminal muss sich nicht im selben lokalen Netzwerk wie der Online-Pay-Server befinden. Beide Seiten müssen jedoch das Internet erreichen können.

Unterstützte Funktionen

Die aktuelle SumUp-Anbindung unterstützt:

Zahlung
Zahlungsablehnung und Abbruch am Terminal
Abbruch eines laufenden Reader-Checkouts durch Online-Pay
Diagnose und Reader-Status
Geräteinformationen
Kopplung eines Solo oder Virtual Solo

Folgende Vorgänge werden derzeit nicht über die SumUp-Anbindung angeboten:

Gutschrift
Storno einer bereits abgeschlossenen Zahlung
Belegwiederholung
Tagesabschluss

Diese Funktionen werden in Online-Pay für eine SumUp-Kasse nicht angeboten beziehungsweise mit einer eindeutigen Meldung abgewiesen.

Voraussetzungen

Vor der Einrichtung müssen folgende Voraussetzungen erfüllt sein:

Ein vollständig eingerichtetes SumUp-Händlerkonto ist vorhanden.
Ein unterstützter SumUp Solo oder Virtual Solo ist vorhanden beziehungsweise im SumUp-Konto freigeschaltet.
Online-Pay kann die SumUp Cloud über HTTPS erreichen.
Das SumUp-Terminal besitzt eine aktive Internetverbindung über WLAN oder Mobilfunk.
Ein geheimer SumUp API-Key ist vorhanden.
Affiliate-Key und zugehörige Affiliate-App-ID sind vorhanden.
Der Reader ist für eine neue API-Kopplung vom bisherigen Benutzerkonto abgemeldet.

Eine lokale Terminal-IP-Adresse und ein lokaler Terminalport werden für SumUp nicht benötigt.

SumUp API-Key erstellen

Der API-Key gehört zum SumUp-Händlerkonto und erlaubt Online-Pay den Zugriff auf die benötigten SumUp-Funktionen.

Im SumUp Dashboard anmelden.
Das Profil öffnen und Einstellungen auswählen.
Für Entwickler und anschließend Toolkit öffnen.
Den Bereich API Keys auswählen.
Einen neuen geheimen API-Key erstellen und eindeutig benennen, beispielsweise PhoenixDS Online-Pay.
Den Schlüssel unmittelbar sicher speichern.

Der im Dashboard angezeigte Public Key ist nicht der benötigte API-Key. Für Online-Pay wird der geheime API-Key verwendet, der üblicherweise mit sup_sk_ beginnt.

SumUp zeigt einen neu erzeugten geheimen Schlüssel möglicherweise nur einmal vollständig an. Geht er verloren, muss ein neuer Schlüssel erstellt und der alte Schlüssel widerrufen werden.

Affiliate-Daten

Für Zahlungen an einem physischen oder virtuellen SumUp-Reader werden zusätzlich benötigt:

Affiliate-Key
Affiliate-App-ID

Diese Daten identifizieren die Kartenpräsenz-Integration gegenüber SumUp. Sie werden von PhoenixDS beziehungsweise im Rahmen der Freigabe durch SumUp bereitgestellt und dürfen nicht durch frei erfundene Werte ersetzt werden.

Allgemeine Kasseneinstellungen in Online-Pay

Online-Pay öffnen.
Mit der rechten Maustaste auf die gewünschte Kasse klicken.
Zahlungsterminal konfigurieren auswählen.
Die allgemeinen Einstellungen der Kasse öffnen.

Einstellung	Empfohlener Wert	Beschreibung
Aktiv	aktiviert	Aktiviert die Verarbeitung für diese Kasse.
Terminalprotokoll	`SumUp`	Verwendet die SumUp Cloud API.
Verbindungsart	ohne Bedeutung für SumUp	SumUp verwendet immer eine HTTPS-Verbindung zur Cloud.
IP-Adresse	leer beziehungsweise ohne Bedeutung	Für SumUp wird keine lokale Terminal-IP verwendet.
Port	ohne Bedeutung	Für SumUp wird kein lokaler Terminalport verwendet.
Timeout 1	`5000`	Zeitlimit für den Aufbau einer Cloud-Verbindung in Millisekunden.
Timeout 2	`180000`	Maximale Wartezeit für einen Zahlungsvorgang in Millisekunden.
Protokollierung	`Erweitert`	Empfohlen für Einrichtung und Fehleranalyse.
Sprache	`DE`	Gemeinsame Spracheinstellung der Kasse.
Währung	`EUR`	ISO-Währungscode für Zahlungen.
Zeichensatz/CodePage des Terminals	ohne Bedeutung für SumUp	Die SumUp Cloud API überträgt Daten als Unicode.

Andere Kassen auf demselben Online-Pay-System können weiterhin mit ZVT, PhoenixDS ZVT, Hobex ZVT oder O.P.I. betrieben werden.

SumUp-Einstellungen

Die anbieterspezifischen Einstellungen befinden sich im Unterordner SumUp Einstellungen der betreffenden Kasse.

Sie können außerdem in der geöffneten Terminalserver-Oberfläche aufgerufen werden:

Rechtsklick in die Meldungsliste und SumUp-Einstellungen und Kopplung auswählen.
Alternativ im Menü Tools den Eintrag SumUp-Einstellungen und Kopplung auswählen.

Beschreibung der Einstellungen

Einstellung	Eingabe	Beschreibung
API-Key	erforderlich	Geheimer API-Key des SumUp-Händlerkontos. Er wird verschlüsselt gespeichert und nicht protokolliert.
Merchant-Code	optional	Händlercode des SumUp-Kontos. Bleibt das Feld leer, versucht Online-Pay ihn automatisch über die SumUp API zu ermitteln.
Reader-ID	automatisch	Eindeutige ID des gekoppelten Readers. Sie wird nach erfolgreicher Kopplung automatisch gespeichert.
Affiliate-Key	für Zahlungen erforderlich	Geheimer Schlüssel für Kartenpräsenz-Zahlungen. Er wird verschlüsselt gespeichert und nicht protokolliert.
Affiliate-App-ID	erforderlich	Zum Affiliate-Key gehörende Anwendungs-ID, beispielsweise `at.phoenixds.onlinepay`. Den von PhoenixDS oder SumUp vorgegebenen Wert verwenden.
Reader-Name	frei wählbar	Bezeichnung des Readers im SumUp-Konto, beispielsweise `PhoenixDS Kasse 01`.
Kopplungscode	nur zur Kopplung	Einmaliger 8- oder 9-stelliger Code, der am Solo oder Virtual Solo angezeigt wird.

API-Key und Affiliate-Key sind geheime Zugangsdaten. Sie dürfen nicht per unverschlüsselter E-Mail versendet, in Screenshots veröffentlicht oder in Supportprotokolle kopiert werden.

SumUp Reader koppeln

1. Reader vorbereiten

Für die API-Kopplung darf der Solo nicht mit einem Benutzer am SumUp-Konto angemeldet sein.

Falls der Reader bereits angemeldet ist:

Das obere Menü am Solo öffnen.
Einstellungen öffnen.
Den Bereich Über / About auswählen.
Vom bestehenden Konto abmelden.

Anschließend:

Den Solo einschalten.
Eine Internetverbindung herstellen.
API auswählen.
Connect / Verbinden auswählen.
Den angezeigten Kopplungscode bereithalten.

Der Kopplungscode ist laut SumUp nur für kurze Zeit gültig. Die Kopplung sollte daher unmittelbar abgeschlossen werden.

2. Kopplung in Online-Pay starten

Die betreffende Kasse in Online-Pay öffnen.
SumUp-Einstellungen und Kopplung aufrufen.
API-Key, Affiliate-Key und Affiliate-App-ID kontrollieren.
Einen eindeutigen Reader-Namen eintragen.
Den am Reader angezeigten Kopplungscode eingeben.
Speichern und koppeln auswählen.
Die Kopplung am SumUp-Gerät bestätigen.
In Online-Pay anschließend Connect auswählen.

Nach erfolgreichem Start der Kopplung speichert Online-Pay die von SumUp zurückgegebene Reader-ID automatisch. Der verwendete Kopplungscode wird danach aus den Einstellungen entfernt.

Beim normalen Programm- oder Dienststart wird niemals automatisch ein neuer Reader gekoppelt. Die Kopplung ist eine bewusst ausgelöste Aktion in der Oberfläche.

Verbindung und Zahlung testen

Nach der Kopplung sollte die Inbetriebnahme in folgender Reihenfolge geprüft werden:

In Online-Pay Connect auswählen.
Reader-Status und Geräteinformationen über die Diagnose prüfen.
Eine Testzahlung mit einem kleinen Betrag, beispielsweise 1,00 EUR, starten.
Eine Zahlung bewusst am Reader abbrechen und die Rückmeldung prüfen.
Eine Zahlung erfolgreich durchführen.
Kontrollieren, ob Betrag, Ergebnis und Belegnummer korrekt an das Kassensystem zurückgegeben werden.

Das SumUp-Terminal sollte während des Betriebs eingeschaltet, mit dem Internet verbunden und nach Möglichkeit mit Strom versorgt sein.

Netzwerk und Firewall

Online-Pay benötigt eine ausgehende HTTPS-Verbindung zur SumUp Cloud:

Richtung	Quelle	Ziel	Port
Ausgehend	Online-Pay / RDS-Server	`api.sumup.com`	TCP `443`

Es wird kein eingehender Port auf dem RDS-Server für das SumUp-Terminal benötigt.

Falls ein Proxy, Webfilter oder eine Firewall eingesetzt wird, muss die HTTPS-Kommunikation zur SumUp API erlaubt sein. Eine TLS-Auftrennung oder Inhaltsmanipulation durch Sicherheitssoftware kann die Verbindung beeinträchtigen.

Protokolldateien

Die SumUp-Protokolle werden je Kasse unterhalb des Online-Pay-Programmordners gespeichert:

<Programmordner>\Log\SumUp\PHXFrameworkSumUp_Kasse001_YYYYMMDD.log

Für die Einrichtung und Fehleranalyse sollte die gemeinsame Einstellung Protokollierung auf Erweitert stehen.

API-Key und Affiliate-Key werden nicht in das Protokoll geschrieben. Identifikatoren und technische Transaktionsangaben können für die Nachverfolgung eines Vorgangs enthalten sein.

Fehlerbehebung

API-Key fehlt oder ist ungültig

Mögliche Ursachen:

Es wurde versehentlich der öffentliche Schlüssel statt des geheimen API-Keys eingetragen.
Der API-Key wurde widerrufen.
Beim Kopieren wurden Zeichen ausgelassen.
Der Schlüssel gehört nicht zum erwarteten SumUp-Händlerkonto.

Lösung: Im SumUp Dashboard einen gültigen geheimen API-Key kontrollieren oder neu erstellen und anschließend in Online-Pay speichern.

Merchant-Code konnte nicht ermittelt werden

Mögliche Ursachen:

Der API-Key ist ungültig.
Das SumUp-Konto ist noch nicht vollständig eingerichtet.
Der Zugriff zur SumUp API wird blockiert.

Lösung: Zuerst API-Key und Internetverbindung prüfen. Falls erforderlich, den Merchant-Code aus dem SumUp-Konto ausdrücklich in Online-Pay eintragen.

Affiliate-Key oder Affiliate-App-ID fehlt

Ohne gültige Affiliate-Daten kann Online-Pay keine Kartenpräsenz-Zahlung am Reader starten.

Lösung: Die von PhoenixDS beziehungsweise SumUp bereitgestellten Werte vollständig eintragen. Die Affiliate-App-ID darf nicht unabhängig vom zugehörigen Affiliate-Key geändert werden.

Kopplungscode wird nicht akzeptiert

Mögliche Ursachen:

Der Kopplungscode ist abgelaufen.
Der Reader ist noch mit einem SumUp-Benutzer angemeldet.
Der Code wurde falsch eingegeben.
Reader und Online-Pay haben keine Internetverbindung.

Lösung: Am Reader einen neuen Code erzeugen und die Kopplung innerhalb weniger Minuten erneut durchführen.

Reader-ID fehlt

Ohne Reader-ID ist noch kein Gerät vollständig mit dieser Kasse gekoppelt.

Lösung: Die Kopplung über SumUp-Einstellungen und Kopplung durchführen. Die Reader-ID nicht manuell erfinden.

Reader ist gekoppelt, aber nicht erreichbar

Prüfung:

Ist der Reader eingeschaltet?
Besteht eine Internetverbindung?
Ist der Reader im richtigen SumUp-Händlerkonto vorhanden?
Zeigt das Gerät noch einen Kopplungs- oder Anmeldebildschirm?
Ist in Online-Pay die zur Kopplung gehörende Reader-ID gespeichert?

Zeitüberschreitung oder unklares Zahlungsergebnis

Wenn eine Zahlungsanforderung bereits von SumUp angenommen wurde und danach die Verbindung abbricht, kann das Ergebnis zunächst unklar sein.

Nicht sofort erneut kassieren. Zuerst den Vorgang im SumUp Dashboard beziehungsweise anhand der im Protokoll enthaltenen Transaktionskennungen prüfen. Dadurch wird eine mögliche Doppelzahlung vermieden.

Der interne Fehlercode 7005 kennzeichnet in der SumUp-Anbindung ein unklares Ergebnis, das manuell überprüft werden muss.

Vorgang wird als „nicht unterstützt“ gemeldet

Gutschrift, Storno einer abgeschlossenen Zahlung, Belegwiederholung und Tagesabschluss sind in der aktuellen SumUp-Anbindung nicht umgesetzt. Für diese Vorgänge muss der vorgesehene Ablauf im SumUp Dashboard beziehungsweise nach Vorgabe des Zahlungsdienstleisters verwendet werden.

Test- und Produktivbetrieb

SumUp bietet für API-Tests ein Sandbox-Händlerkonto an. Die Sandbox verarbeitet keine echten Zahlungen. Sie ersetzt jedoch nicht in jedem Fall das Verhalten eines realen oder von SumUp bereitgestellten virtuellen Readers.

Vor dem Produktivbetrieb müssen deshalb mindestens folgende Fälle mit dem vorgesehenen SumUp-Gerät getestet werden:

erfolgreiche Zahlung
abgelehnte Zahlung
Abbruch am Terminal
Verbindungsunterbrechung während einer Zahlung
Verhalten bei Zeitüberschreitung
Wiederanlauf von Online-Pay und Reader

Abnahmecheckliste

Sicherheitshinweise

API-Key und Affiliate-Key wie Passwörter behandeln.
Schlüssel niemals in Tickets, Screenshots oder normalen E-Mails veröffentlichen.
Bei Verdacht auf Offenlegung den betreffenden Schlüssel unverzüglich widerrufen und ersetzen.
Nur berechtigten Mitarbeitern Zugriff auf die SumUp-Einstellungen geben.
SumUp Dashboard und hinterlegte Transaktionen regelmäßig kontrollieren.

Weiterführende Informationen

Die verfügbaren Funktionen und Freigabeanforderungen können sich durch Änderungen bei SumUp verändern. Bei einer Neueinrichtung sollten die aktuellen SumUp-Unterlagen geprüft werden.