Was muss ich bei einem Zahlungsterminal mit O.P.I. Schnittstelle einstellen?

O.P.I.-Zahlungsterminal in PhoenixDS Online-Pay

Zweck dieser Dokumentation

Diese Anleitung beschreibt die Einrichtung eines Zahlungsterminals über die O.P.I.-Schnittstelle in PhoenixDS Online-Pay.

Als Beispiel wird ein CCV Pad Next verwendet. Die genaue Bezeichnung der Menüpunkte am Terminal kann abhängig von Firmware, Netzbetreiber und Terminalkonfiguration abweichen.

Wichtig: Die O.P.I.-Funktion muss am Terminal beziehungsweise durch CCV oder den Netzbetreiber freigeschaltet und eingerichtet sein. Die Konfiguration in Online-Pay allein aktiviert O.P.I. nicht am Terminal.

Funktionsprinzip

O.P.I. verwendet zwei getrennte TCP-Verbindungen:

1. Befehlskanal: Online-Pay verbindet sich mit dem Zahlungsterminal.
2. Rückkanal: Das Zahlungsterminal verbindet sich zurück mit Online-Pay auf dem RDS-Server.

Online-Pay / RDS-Server                         CCV-Terminal

       Zahlungsanforderung  ----------------->  TCP-Port 20002
       TCP-Port 20007        <-----------------  Anzeigen und Belegdaten

Für eine funktionierende Verbindung müssen beide Kommunikationsrichtungen im Netzwerk und in der Firewall freigegeben sein.

Beispielkonfiguration

Die im Online-Pay-Protokoll angezeigte Adresse 127.0.0.1 mit einem zufälligen hohen Port gehört zur internen Kommunikation von Online-Pay. Sie ist nicht der O.P.I.-Port des Terminals.

Voraussetzungen

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

• Das CCV-Terminal ist für O.P.I. freigeschaltet.
• Terminal und RDS-Server können sich gegenseitig über das Netzwerk erreichen.
• Das Terminal besitzt nach Möglichkeit eine feste IP-Adresse oder eine feste DHCP-Zuordnung.
• Der O.P.I.-Befehlsport des Terminals ist bekannt. Beim CCV Pad Next ist dies häufig 20002.
• Der Rückkanal des Terminals ist auf die IP-Adresse des RDS-Servers und den vorgesehenen Rückkanal-Port eingestellt.
• Die Windows-Firewall erlaubt die benötigten Verbindungen.
• Bei mehreren Kassen wird für jede gleichzeitig aktive Kasse ein eigener Rückkanal-Port verwendet.

Vorbereitung des CCV-Terminals

Am Terminal oder durch den zuständigen Netzbetreiber müssen mindestens folgende Werte eingerichtet werden:

Die Änderung dieser Werte kann sich im geschützten Servicebereich des Terminals befinden. Falls die Einstellungen nicht sichtbar sind, muss CCV, der Terminalbetreuer oder der Netzbetreiber die O.P.I.-Konfiguration durchführen.

Einrichtung in Online-Pay

1. Online-Pay öffnen.
2. Mit der rechten Maustaste auf die gewünschte Kasse klicken.
3. Zahlungsterminal konfigurieren auswählen.
4. Zuerst die allgemeinen Kasseneinstellungen bearbeiten.
5. Anschließend den Unterordner O.P.I. Einstellungen öffnen.

Allgemeine Kasseneinstellungen

Zeichensatz: Für die getestete CCV-Konfiguration ist 28591 - Westeuropäisch (ISO) korrekt. Dadurch werden Umlaute in Beleg- und Anzeigetexten richtig verarbeitet.

O.P.I. Einstellungen

CCV Pad Next: Die Option XML-Namespace verwenden muss für die getestete Konfiguration deaktiviert sein. Bei aktiviertem Namespace antwortete das Terminal mit FatalError und ParsingError.

Windows-Firewall und Netzwerk

Für das Beispiel werden folgende Verbindungen benötigt:

Der eingehende Port muss auf dem RDS-Server in der Windows-Firewall freigegeben sein. Zusätzlich dürfen Netzwerk-Firewalls oder VLAN-Regeln die Kommunikation nicht blockieren.

Mehrere Kassen auf demselben RDS-Server

Jede gleichzeitig aktive O.P.I.-Kasse benötigt einen eigenen Rückkanal-Port.

Der jeweilige Port muss sowohl in Online-Pay als auch im zugehörigen Terminal eingetragen und in der Firewall freigegeben werden.

Verbindung testen

Nach dem Speichern der Einstellungen sollte Online-Pay beziehungsweise die betreffende Terminalverbindung neu gestartet werden.

Die Inbetriebnahme sollte in folgender Reihenfolge getestet werden:

1. Anmeldung beziehungsweise Initialisierung des Terminals.
2. Diagnose über das Kontextmenü der Kasse.
3. Testzahlung mit einem kleinen Betrag, beispielsweise 1,00 EUR.
4. Abbruch einer Zahlung am Terminal.
5. Erfolgreiche Zahlung einschließlich Kunden- und Händlerbeleg.
6. Tagesabschluss.

Bei einer erfolgreichen Initialisierung enthält das erweiterte Protokoll unter anderem:

PROVIDER PHXFrameworkOPI initialize Command=10.10.10.140:20002 DevicePort=20007
OPI TX <ServiceRequest RequestType="Login" ...>
OPI RX <ServiceResponse ...>

Im XML der Anforderung darf für die beschriebene CCV-Konfiguration kein zusätzliches xmlns-Attribut enthalten sein.

Protokolldateien

Die O.P.I.-Protokolle werden unterhalb des Online-Pay-Programmordners gespeichert:

<Programmordner>\Log\OPI\PHXFrameworkOPI_Kasse001_YYYYMMDD.log

Für die Einrichtung und Diagnose sollte die Einstellung Protokollierung vorübergehend auf Erweitert stehen.

Sensible Kartendaten wie PAN, Track-Daten, PIN-Informationen und Zugangsdaten werden nicht im Klartext protokolliert.

Fehlerbehebung

FatalError / ParsingError

Mögliche Ursache: Das Terminal kann die gesendete XML-Struktur nicht verarbeiten.

Prüfung:

• XML-Namespace verwenden deaktivieren.
• Als Zeichensatz 28591 - Westeuropäisch (ISO) einstellen.
• Verbindung anschließend neu initialisieren.

Ungültige O.P.I.-Nachrichtenlänge oder negativer Längenwert

Mögliche Ursache: Es wird der falsche Terminalport verwendet oder die Gegenstelle liefert auf diesem Port kein O.P.I.-XML.

Prüfung:

• Für das CCV-Beispiel den Befehlsport 20002 verwenden.
• Nicht den Rückkanal-Port als Befehlsport eintragen.
• Prüfen, ob O.P.I. am Terminal wirklich aktiviert ist.

Keine Verbindung zum Terminal

Mögliche Ursachen:

• IP-Adresse oder Port ist falsch.
• O.P.I. ist am Terminal nicht aktiviert.
• Eine Firewall blockiert den Befehlsport.
• Terminal und RDS-Server befinden sich in getrennten Netzen ohne passende Freigabe.

Zahlung startet, aber Anzeigen oder Belege fehlen

Mögliche Ursache: Der Rückkanal erreicht Online-Pay nicht.

Prüfung:

• Zieladresse des Rückkanals am Terminal kontrollieren.
• Rückkanal-Port am Terminal und in Online-Pay vergleichen.
• Eingehende Windows-Firewall-Regel prüfen.
• Bei mehreren Kassen sicherstellen, dass jeder Rückkanal-Port nur einmal verwendet wird.

Rückkanal-Port ist bereits belegt

Mögliche Ursache: Eine zweite Kasse oder ein anderes Programm verwendet denselben lokalen Port.

Lösung: Für jede O.P.I.-Kasse einen eigenen Rückkanal-Port konfigurieren.

Umlaute werden falsch dargestellt

Prüfung:

• Zeichensatz auf 28591 - Westeuropäisch (ISO) stellen.
• Beachten, dass eine fehlerhafte Darstellung nur im verwendeten Logreader auftreten kann, obwohl die eigentliche Datei korrekt gespeichert wurde.

Abnahmecheckliste

• O.P.I. ist am Terminal aktiviert.
• Terminal-IP-Adresse ist fest vergeben oder reserviert.
• Befehlsport stimmt mit der Terminalkonfiguration überein.
• Rückkanal zeigt auf die IP-Adresse des RDS-Servers.
• Rückkanal-Port stimmt in Terminal und Online-Pay überein.
• Windows-Firewall erlaubt beide Kommunikationsrichtungen.
• Workstation-ID ist eindeutig und korrekt zugeordnet.
• Zeichensatz ist 28591 - Westeuropäisch (ISO).
• XML-Namespace ist für das CCV Pad Next deaktiviert.
• Anmeldung und Diagnose wurden erfolgreich getestet.
• Erfolgreiche Zahlung wurde getestet.
• Zahlungsabbruch wurde getestet.
• Belegtexte und Umlaute wurden geprüft.
• Tagesabschluss wurde erfolgreich getestet.

Wichtige Hinweise

• O.P.I.-Details können abhängig von Terminalmodell, Firmware und Netzbetreiber abweichen.
• Die Befehlsnamen für Diagnose und Tagesabschluss sind herstellerabhängig und müssen im Zweifelsfall mit CCV oder dem Netzbetreiber abgestimmt werden.
• Bei einem unklaren Zahlungsergebnis darf eine Zahlung nicht ungeprüft wiederholt werden. Zuerst muss der Status am Terminal beziehungsweise beim Netzbetreiber kontrolliert werden.
• Die beschriebenen Werte bilden die erfolgreich getestete XML-Verarbeitung mit einem CCV-Terminal ab. Zahlung, Storno, Diagnose und Tagesabschluss müssen vor dem Produktivbetrieb vollständig abgenommen werden.

Weiterführende Herstellerinformationen

• CCV Pad Next – Produktinformation
• CCV System Manual mit O.P.I.-Hinweisen

Die vollständige CCV-O.P.I.-Spezifikation ist gegebenenfalls direkt bei CCV anzufordern.