Glossar
Die Fachwörter aus Zahlungsverkehr und ZVT-Protokoll in einfachen Worten – von ACK bis Zwischenstatus.
Kurzfassung
Kurze Erklärungen zu den Begriffen, die in diesem Handbuch und in der Live-Anzeige vorkommen, alphabetisch. Die Werte, die du in deiner Kasse einträgst, stehen nicht hier, sondern im Kapitel Kasse anbinden.
Ausführlich
ACK (Quittung). Die kurze Bestätigung „angekommen und verstanden" (80 00 00). Fast jedes Telegramm wird damit quittiert, bevor das eigentliche Ergebnis folgt.
NAK (negative Quittung). Die Gegenantwort zum ACK: 84 <Fehlercode> 00. Die Instanz sendet 84 9A für ein Kommando, das sie nicht kennt, und für ein falsches Registrierungs-Passwort – die ZVT-Spezifikation kennt für beides keinen eigenen Code.
API. Eine Schnittstelle, über die ein Programm ein anderes steuert. Hier: die Steuer-API, mit der deine Pipeline die Instanz bedient.
API-Schlüssel. Ein langes Geheimwort, mit dem sich eine Pipeline gegenüber der Schnittstelle ausweist. Beginnt mit zvtsim_. Erzeugt und widerrufen wird er auf der verlinkten Seite; angezeigt wird er nur einmal, später lässt er sich nicht mehr ansehen.
APDU. Die Dateneinheit des ZVT-Protokolls: Steuerfeld, Länge, Daten. In diesem Handbuch sagen wir meistens „Telegramm".
Autorisierung. Die Anfrage der Kasse an das Terminal, eine Zahlung durchzuführen (Befehl 06 01).
Abbruch. Die Kasse bricht einen laufenden Vorgang ab (Befehl 06 B0). Nicht zu verwechseln mit 06 1E: Das ist die Gegenrichtung, mit der das Terminal einen Vorgang als gescheitert abschließt. Der Modus abort simuliert, dass das Terminal abbricht (siehe Fehlerszenarien).
Bearer. Die Art, einen Schlüssel im Kopf einer Anfrage mitzuschicken: Authorization: Bearer <Schlüssel>.
Beleg-Nummer. Die Nummer, unter der das Terminal einen Vorgang auf dem Beleg und in der Status-Information (Bitmap 87) ausweist. Bei einer Reservierung ist sie der Schlüssel, mit dem die Kasse sie später bucht oder storniert.
CI/CD. Automatisierte Tests und Auslieferung bei jeder Codeänderung (zum Beispiel mit GitHub Actions).
Instanz. Dein eigener Terminalsimulator, der für dich gestartet wurde. Höchstens einer je Konto. IP-Adresse und Port dazu zeigt die Seite Simulator an.
Kasse (ECR). Die Kassensoftware, der Teil, der das Terminal steuert. In ZVT-Texten „ECR" (electronic cash register).
Kassenschnitt. Der Tagesabschluss (Befehl 06 50): Das Terminal meldet die Umsätze seit dem letzten Schnitt und setzt sie zurück. Als Teilabrechnung 06 52; 06 10 meldet dieselben Summen, ohne abzurechnen.
Kommando-Präfix. Der vordere Teil des Modus-Textes, der angibt, für welches Kommando eine Fehlereinstellung gilt: die beiden Steuerbytes, dann ein Schrägstrich, zum Beispiel 06 30/decline:already-reversed für den Storno. Ohne Präfix gilt die Autorisierung (06 01). Siehe Fehlerszenarien.
Live-Anzeige. Die Darstellung des Verkehrs zwischen Kasse und Instanz im Browser, in Echtzeit.
Logoff (Abmeldung). Das Gegenstück zur Registrierung (Befehl 06 02): Die Kasse meldet sich beim Terminal ab. Die Instanz quittiert nur mit 80 00; danach ist die Kasse nicht mehr registriert, und jedes weitere Kommando bekommt 84 6B, bis sie sich neu registriert.
Maskieren. Schützenswerte Stellen (zum Beispiel Kartennummern) unkenntlich machen.
Maskierungswerkzeug (Mask-Tool). Das kleine Programm, das einen Mitschnitt maskiert. Es läuft ohne Installation; heruntergeladen wird es auf der verlinkten Seite.
Mitschnitt. Eine Aufzeichnung des ZVT-Verkehrs, meist als .dif-Datei. Siehe auch „Sniffer / Mitschnitt".
Mitschnitt-Analyse. Die Auswertung eines hochgeladenen Mitschnitts in ZVTSIM, in derselben Darstellung wie die Live-Anzeige. Die Anleitung dazu steht im Kapitel Mitschnitte auswerten.
Modus. Das Verhalten, das du für den nächsten Vorgang eines Kommandos einstellst (success, decline, timeout, …), bei Bedarf mit Kommando-Präfix und Ergebniscode.
OpenAPI / Swagger. Standardformat und Weboberfläche, mit denen eine Schnittstelle beschrieben und ausprobiert wird. Unter /api/docs und /api/openapi/v1.json, beides nur angemeldet.
oneShot. „Nur einmal": Der Modus gilt für den nächsten Vorgang des gewählten Kommandos und fällt dann zurück auf Erfolg. Der Zähler läuft je Kommando: Eine Zahlung verbraucht keinen scharf gestellten Storno-Fehler.
Pipeline. Der automatische Ablauf, der bei jeder Änderung Tests ausführt.
Port. Die „Tür" auf dem Server, an der deine Instanz lauscht. Welche Nummer es bei dir ist, sagt dir die Simulator-Seite; in diesem Handbuch steht dafür <PORT>.
IP-Adresse (Host). Die IP-Adresse, auf die deine Kasse ihre ZVT-Verbindung aufbaut. Im Feld „Host“ oder „IP-Adresse“ deiner Kassenkonfiguration trägst du sie ein. Sie ist nicht dieselbe wie der Name, unter dem du ZVTSIM im Browser aufhast. Welche es bei dir ist, sagt dir die Simulator-Seite; in diesem Handbuch steht dafür <IP>.
Registrierung. Die Anmeldung der Kasse beim Terminal (Befehl 06 00) mit Passwort und Einstellungen. Nicht zu verwechseln mit der Registrierung eines Kontos bei ZVTSIM.
Port-Reservierung. Die Zusage, dass dein Port dir gehört, auch wenn die Instanz gerade nicht läuft (Pro-Abo 7 Tage rollierend, Pro-Abo Plus unbegrenzt, Tages-Pass für die Laufzeit des Passes). Siehe Tarife und Freischaltung.
Reservierung (Zahlung, 06 22–06 26). Die Zusage eines Höchstbetrags, bevor der endgültige Betrag feststeht (Befehl 06 22), zum Beispiel an der Tankstelle. Sie zählt nicht in die Tagesumsätze; gebucht wird später mit 06 24 (benutzter Betrag) oder 06 23 (unbenutzter Betrag wird freigegeben), storniert mit 06 25 – und mit 06 26 auch die Reservierung eines fremden Terminals, die über die Trace-Nummer statt über die Beleg-Nummer angesprochen wird. Offene Reservierungen stehen im Status unter openReservations. Nicht zu verwechseln mit der Port-Reservierung. Siehe Kasse anbinden.
Rückvergütung. Die Rückzahlung an den Kunden (Befehl 06 31).
Sitzung (Session). Die Kennung deiner laufenden Instanz. Die Schnittstelle braucht sie in der Webadresse.
Sniffer / Mitschnitt. „Sniffer" ist der übliche Werkzeugname für ein Programm, das den Datenverkehr zwischen Kasse und Terminal mitliest; was dabei herauskommt, ist ein Mitschnitt (auch „ZVT-Trace", meist eine .dif-Datei). Bei ZVTSIM heißt die Auswertung solcher Dateien deshalb Mitschnitt-Analyse – früher „Sniffer-Analyse". Die alte Webadresse leitet auf die neue weiter.
Status-Telegramm. Das Ergebnis eines Vorgangs, das das Terminal der Kasse meldet (04 0F), samt Ergebniscode. Ein Vorgang kann mehrere davon enthalten; abgeschlossen ist er erst mit 06 0F (Erfolg) oder 06 1E (Fehlschlag).
Stripe. Der Zahlungsdienst, über den du deinen Tarif bezahlst. Die Kartenerfassung findet dort statt, nicht in ZVTSIM.
Storno. Die Rücknahme einer Zahlung (Befehl 06 30).
Telegramm. Eine einzelne Nachricht zwischen Kasse und Terminal.
Terminal-ID. Die Nummer des Terminals, die die Instanz in der Antwort auf die Registrierung meldet und auf die Belege druckt. Der Testwert steht in Kasse anbinden.
Timeout. Die Zeitüberschreitung: Eine Antwort bleibt aus. Der Modus timeout erzwingt das.
Vorautorisierung. Anderes Wort für die Reservierung eines Betrags (Befehl 06 22): Das Terminal sagt den Betrag zu, ohne ihn schon zu buchen. Siehe „Reservierung (Zahlung)“.
ZVT. Kurzform von „Zahlungsverkehrsterminal“. Gemeint ist die ZVT-Schnittstelle (offiziell „ZVT-Standard Kassenschnittstelle“), über die eine Kasse ein Zahlungsterminal ansteuert. Sie wird vom Verband der Terminalhersteller e.V. gepflegt. ZVTSIM ist ein unabhängiger Simulator und steht in keiner Verbindung zum Verband.
Zwischenstatus. Meldungen während eines Vorgangs („Karte einführen", „PIN eingeben"), Befehl 04 FF.
Zwischenstatus-Skript. Eine von dir vorgegebene Folge von Zwischenstatus-Meldungen für den nächsten Vorgang eines Kommandos, zum Beispiel 0A, 17, 15:Falsche PIN. Es gibt sie nur in der Steuer-API (POST /api/sessions/{sessionId}/intermediate).