Was ist lokale Integration?
Mit der lokalen Integration kann deine Kassensoftware Zahlungsanfragen direkt über dein lokales Netzwerk (WLAN oder Kabel) an dein Vivid-Zahlungsterminal senden. Das Terminal verbindet sich für Autorisierung und Abrechnung weiterhin mit der Cloud von Adyen — deine Software kommuniziert einfach lokal damit.
Diese Anleitung richtet sich an Händler und ihre Softwareanbieter, die das selbst einrichten möchten.
Bevor du beginnst
Stelle sicher, dass du Folgendes hast:
Ein Vivid-Zahlungsterminal, das bereits eingerichtet und mit dem Händlerkonto verknüpft ist.
Eine Kassensoftware, die HTTPS-Anfragen senden kann (deine eigene oder die deines Anbieters).
Ein lokales Netzwerk, in dem sich Kasse und Terminal gegenseitig erreichen können.
Eine im Vivid-App oder im Web konfigurierte Verschlüsselungs-Passphrase (siehe Schritt 3).
Schritt 1. Netzwerk einrichten
Stelle sicher, dass folgende Ports in der Firewall geöffnet sind:
Verbindung | Port | Wofür |
Zahlungsterminal → Internet | TCP 443 | Terminal kommuniziert mit Adyen |
Kasse → Zahlungsterminal | TCP 8443 | Lokale Zahlungsanfragen |
Setze diese beiden Domains namentlich auf die Zulassungsliste (nicht per IP — die IP-Adressen von Adyen ändern sich):
*.adyen.com
*.adyenpayments.com
Noch zwei Dinge:
Konfiguriere die Firewall nicht so, dass sie den TLS-Verkehr zum Terminal prüft oder herabstuft — das unterbricht die Verbindung.
Weise jedem Terminal eine feste IP-Adresse zu (per DHCP-Reservierung oder statischer IP), damit die Kasse es immer findet.
Schritt 2. Eine Adyen-Bibliothek installieren (optional, aber empfohlen)
Adyen bietet kostenlose Open-Source-Bibliotheken an, die den Großteil der technischen Arbeit in Schritt 3 und 4 übernehmen. Wenn deine Kassensoftware auf einer dieser Plattformen basiert, empfehlen wir, die passende Bibliothek zu verwenden:
Plattform | Bibliothek |
Java | |
.NET | |
Node.js | |
iOS |
Wenn deine Plattform nicht aufgeführt ist, kannst du die Integration trotzdem manuell abschließen.
Schritt 3. Verschlüsselung einrichten
Damit Zahlungsdaten in deinem lokalen Netzwerk sicher bleiben, musst du einen Verschlüsselungsschlüssel einrichten, der von Terminal und Kassensoftware gemeinsam genutzt wird. Das besteht aus drei Teilen.
Verschlüsselungsschlüssel in der Vivid-App einrichten:
Gehe in der Vivid-App oder im Web zu Einstellungen des Zahlungsterminals > Verschlüsselungsschlüssel und fülle aus:
Schlüsselkennung — ein Name für den Schlüssel.
Schlüssel-Passphrase — mindestens 12 Zeichen, mit mindestens einem Großbuchstaben, einem Kleinbuchstaben, einer Zahl und einem Sonderzeichen.
Schlüsselversion — eine Versionsnummer (eine beliebige positive ganze Zahl).
Tippe auf Speichern. Die Werte werden nach dem Speichern ausgeblendet — nutze das Augensymbol, um sie anzuzeigen. Um den Schlüssel zu löschen, leere alle drei Felder und tippe auf Speichern.
Schlüssel werden wirksam, sobald sich das Terminal das nächste Mal mit der Plattform verbindet, was in der Regel alle drei Stunden geschieht. Du kannst das auch manuell über Einstellungen am Terminal auslösen.
Adyens Stammzertifikat installieren:
Die Kasse muss dem Sicherheitszertifikat von Adyen vertrauen, um zu prüfen, dass sie mit dem richtigen Terminal kommuniziert.
Lade das Zertifikat herunter und installiere es gemäß der Anleitung für dein Betriebssystem: https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local#install-root-cert
Starte die Kassensoftware nach der Installation neu.
Kassensoftware konfigurieren:
Die Kassensoftware muss bei jeder Zahlungsanfrage zwei Dinge tun:
Das Zertifikat des Terminals gegen das Stammzertifikat von Adyen prüfen. Überspringe diesen Schritt nie und greife nie auf eine unverschlüsselte Verbindung zurück.
Die Anfrage mit der gemeinsamen Passphrase aus der Vivid-App verschlüsseln.
Wenn du die Adyen-Bibliothek aus Schritt 2 verwendest, geschieht das automatisch — du gibst einfach die Passphrase und den Pfad zum Zertifikat an.
Wenn du es manuell umsetzt, folge der Verschlüsselungsdokumentation von Adyen (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local), um Certificate Pinning, Schlüsselableitung und Nachrichtenverschlüsselung umzusetzen.
Schritt 4. Zahlungsanfragen senden
Die Kassensoftware sendet Zahlungsanfragen an das Terminal unter:
Das Terminal antwortet über dieselbe Verbindung. Wenn du die Adyen-Bibliothek verwendest, rufe die passende Sync-Methode auf. Wenn du es manuell umsetzt, baue die JSON-Anfrage, verschlüssle sie wie in Schritt 3 beschrieben und sende sie per POST.
Schritt 5. Langsame oder unterbrochene Verbindungen handhaben
Zahlungsvorgänge können manchmal etwas dauern — zum Beispiel, wenn ein Kunde mehr Zeit für die PIN-Eingabe braucht. Stelle sicher, dass die Kassensoftware:
Mindestens 120 Sekunden wartet, bevor eine Zahlungsanfrage ihr Timeout erreicht.
Wenn nach 150 Sekunden keine Antwort kommt, automatisch den Transaktionsstatus prüft, bevor sie die Zahlung als fehlgeschlagen einstuft.
Eine manuelle Option Letzte Transaktion prüfen für das Personal bietet, um unklare Situationen zu klären.
Jede Anfrage und Antwort protokolliert, einschließlich ServiceID, SaleID und POIID — diese werden benötigt, wenn du den Support kontaktierst.
Wofür Vivid verantwortlich ist
Vivid stellt das Zahlungsterminal bereit und richtet es auf dem Händlerkonto ein. Alles, was in dieser Anleitung beschrieben ist — Netzwerkkonfiguration, Zertifikate, Verschlüsselung und die Kassensoftware — liegt in deiner Verantwortung (oder der deines Anbieters). Vivid unterstützt oder zertifiziert keine Integrationen von Kassensoftware.
Für Hilfe mit dem Terminal selbst — Onboarding, Hardware oder den Verschlüsselungsschlüssel auf Terminalseite — wende dich an den Vivid-Support.
Wichtig: Verändere das Zahlungsterminal nicht. Du darfst keine Software darauf installieren, die Firmware nicht manipulieren und die Verbindung zu Adyen nicht beeinträchtigen. Andernfalls erlischt die Zertifizierung, die PCI-Konformität wird verletzt und das Terminal kann aus der Ferne deaktiviert werden.
Häufige Fragen
Hilft Vivid bei der Einrichtung meiner Kassensoftware?
Nein — die Integration deiner Kassensoftware liegt in deiner Verantwortung oder der deines Anbieters. Technische Hinweise findest du in der Dokumentation zur Adyen Terminal API (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local).
Der Verschlüsselungsschlüssel wird auf dem Terminal nicht angezeigt — was soll ich tun?
Schlüssel werden angewendet, sobald sich das Terminal das nächste Mal mit der Plattform verbindet, was in der Regel alle drei Stunden geschieht. Du kannst das auch manuell über Einstellungen am Terminal auslösen. Wenn das Problem weiterhin besteht, wende dich an den Vivid-Support.
Kann ich ein kabelgebundenes Netzwerk verwenden?
Ja, sowohl kabelgebundene als auch WLAN-Netzwerke funktionieren, solange Kasse und Terminal im selben Netzwerk sind und die Ports aus Schritt 1 geöffnet sind.
Wie aktualisiere oder entferne ich den Verschlüsselungsschlüssel?
Gehe in der Vivid-App oder im Web zu Einstellungen des Zahlungsterminals > Verschlüsselungsschlüssel. Gib neue Werte ein und tippe auf Speichern, um zu aktualisieren. Leere alle drei Felder und tippe auf Speichern, um den Schlüssel zu entfernen.