Skip to main content

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

Komponente Beispielwert
IP-Adresse des CCV-Terminals 10.10.10.140
IP-Adresse des RDS-Servers beispielsweise 10.10.10.10
O.P.I.-Befehlsport am Terminal 20002
O.P.I.-Rückkanal-Port in Online-Pay 20007
Kasse 01
Workstation-ID 01

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:

Einstellung am Terminal Beispiel Bedeutung
Schnittstelle O.P.I. Aktiviert die Kassenanbindung über O.P.I.
Befehlskanal / Port 20002 Port, auf dem das Terminal Anforderungen von Online-Pay annimmt
Zieladresse des Rückkanals IP-Adresse des RDS-Servers Adresse, zu der das Terminal Anzeigen und Belegdaten sendet
Rückkanal-Port 20007 Muss mit der Einstellung in Online-Pay übereinstimmen
Workstation-ID 01 Kennung der zugeordneten Kasse

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

Einstellung Empfohlener Wert für das Beispiel Beschreibung
Aktiv aktiviert Aktiviert die Verarbeitung für diese Kasse.
Terminalprotokoll O.P.I. Verwendet die O.P.I.-Schnittstelle.
Verbindungsart TCP/IP Verbindung zum Terminal über das Netzwerk.
IP-Adresse 10.10.10.140 IP-Adresse des Zahlungsterminals.
Port 20002 O.P.I.-Befehlsport des Terminals.
Timeout 1 5000 Zeitlimit für den Verbindungsaufbau in Millisekunden.
Timeout 2 180000 Maximale Wartezeit für einen Zahlungsvorgang in Millisekunden.
Protokollierung Erweitert Empfohlen für Einrichtung und Fehleranalyse.
Sprache DE Sprache für die Kommunikation mit dem Terminal.
Währung EUR ISO-Währungscode für Zahlungen.
Zeichensatz/CodePage des Terminals 28591 - Westeuropäisch (ISO) Entspricht ISO-8859-1 und ist für das getestete CCV-Terminal erforderlich.

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

Einstellung Empfohlener Wert für das Beispiel Beschreibung
Rückkanal-Port 20007 Port, auf dem Online-Pay Verbindungen vom Terminal annimmt.
Lokale IP-Adresse 0.0.0.0 Online-Pay lauscht auf allen lokalen Netzwerkadressen. Alternativ kann die feste IP-Adresse des RDS-Servers eingetragen werden.
Workstation-ID 01 Kassenkennung im O.P.I.-Protokoll. Muss zur Terminalkonfiguration passen.
POP-ID leer Optionale Point-of-Payment-ID. Nur eintragen, wenn CCV oder der Netzbetreiber einen Wert vorgibt.
Application-Sender PhoenixDS Online-Pay Name der sendenden Kassenanwendung.
XML-Namespace verwenden deaktiviert Beim getesteten CCV Pad Next muss diese Option deaktiviert sein.
Unterschrift automatisch bestätigen deaktiviert Nur aktivieren, wenn ein organisatorisch und technisch abgesicherter Freigabeablauf besteht.
Nachlaufzeit Rückkanal ms 500 Kurze Wartezeit, damit abschließende Anzeige- oder Belegdaten übernommen werden können.
Diagnose-Anforderung Diagnosis Herstellerabhängiger O.P.I.-Befehlsname für die Diagnose.
Tagesabschluss-Anforderung ReconciliationWithClosure Herstellerabhängiger O.P.I.-Befehlsname für den Tagesabschluss.

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:

Richtung Quelle Ziel TCP-Port
Ausgehend RDS-Server / Online-Pay CCV-Terminal 20002
Eingehend CCV-Terminal RDS-Server / Online-Pay 20007

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.

Kasse Beispiel Rückkanal-Port
Kasse 01 20007
Kasse 02 20008
Kasse 03 20009

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

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

No comments to display

Back to top