VibeFox Worldline for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

Worldline-Konto: ein Worldline-Direct-Händlerkonto (früher Ingenico Direct). Test- und Live-Konten sind getrennt und haben unterschiedliche Zugangsdaten. Für jedes Konto benötigen Sie die Händler-ID (Ihre PSPID), eine API-Schlüssel-ID mit dem geheimen API-Schlüssel sowie einen Webhook-Schlüssel mit dem zugehörigen Geheimnis. Alle werden im Worldline Merchant Portal erstellt (siehe Konfiguration).

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket wcp_worldline_gateway-oc3-(version).ocmod.zip und das OpenCart-4-Paket wcp_worldline_gateway.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen derselbe.

OpenCart 3

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_worldline_gateway-oc3-(version).ocmod.zip. Die Erweiterung hat keine OCMOD-Änderungen, daher muss Extensions > Modifications nicht aktualisiert werden. Statt des Installers können Sie auch den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox Worldline Gateway und klicken Sie auf Install (der grüne +-Button). Ihr Admin-Benutzer benötigt das Recht, die Liste der Zahlungserweiterungen zu ändern.

3. Klicken Sie auf Edit (der Stift-Button), um die Einstellungsseite zu öffnen. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie die Testzugangsdaten ein, klicken Sie auf Save und danach auf Test credentials.

5. Tragen Sie die Webhook-URL im Merchant Portal des Testkontos ein und geben Sie den Webhook-Schlüssel und das Geheimnis ein (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable, speichern Sie und führen Sie eine Testzahlung durch. Geben Sie danach die Live-Zugangsdaten ein, wiederholen Sie die Webhook-Einrichtung in Ihrem Live-Konto, klicken Sie auf Live credentials und deaktivieren Sie Test Mode.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_worldline_gateway.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox Worldline Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel, die Zugangsdaten und den Webhook ein wie in den Schritten 3 bis 6 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Webhook-URL ist anders (siehe Webhooks).

Nach einer Neuinstallation ist die Zahlungsmethode zunächst deaktiviert und der Testmodus aktiviert.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit. Die Abschnitte sind links aufgelistet; der Button Save unter der Liste speichert die gesamte Seite. Oberhalb der Einstellungen weist die Seite Sie darauf hin, wenn die Zugangsdaten des aktuellen Modus (Händler-ID, API-Schlüssel-ID, geheimer API-Schlüssel) unvollständig sind, da die Zahlungsmethode dann an der Kasse ausgeblendet wird. Solange der Testmodus aktiv ist, wird Test mode is on (pre-production environment): no real money is charged. angezeigt. Ohne das Recht, die Erweiterung zu ändern, zeigt die Seite die Einstellungen an, kann sie aber nicht speichern.

Beim Speichern darf Title nicht leer sein (höchstens 128 Zeichen), Sort Order muss eine ganze Zahl sein (negative Zahlen sind erlaubt), Total muss eine Zahl sein, 0 oder größer, und die Geo-Zone und die Bestellstatus müssen vorhanden sein. Andernfalls wird nichts gespeichert, und die Seite nennt das betreffende Feld. Unvollständige Zugangsdaten verhindern das Speichern nicht.

Worldline (Ingenico)

Enable/Disable: Enable Worldline Gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Zahlungsmethode in der Bestellung gespeichert. Standard: Worldline. Pflichtfeld, höchstens 128 Zeichen.

Description: der Text, den der Kunde im Schritt Confirm Order oberhalb der Bestätigungsschaltfläche sieht. Standard: Pay securely via Worldline.

Sort Order: die Position von Worldline unter den Zahlungsmethoden an der Kasse. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein.

Geo Zone: bietet Worldline nur für Zahlungsadressen in der gewählten Geo-Zone an. Standard: All zones. Geo-Zonen werden unter System > Localisation > Geo Zones eingerichtet.

Total: die Kassensumme in der Standardwährung des Shops, die eine Bestellung erreichen muss, bevor Worldline angeboten wird. Lassen Sie das Feld leer, um Worldline für jede Summe anzubieten.

Worldline Direct API

Die Zugangsdaten finden Sie im Worldline Merchant Portal des Testkontos und des Live-Kontos. Ihre PSPID ist die Händler-ID. Unter Developer > Payment API werden die API-Schlüssel-ID und der geheime API-Schlüssel erstellt, unter Developer > Webhooks der Webhook-Schlüssel und das Geheimnis. Der Abschnitt enthält Links zu beiden Portalen und zur Worldline-Dokumentation.

Test Mode: schaltet sowohl den API-Endpunkt als auch die Zugangsdaten um. Der Testmodus nutzt die Vorproduktionsumgebung und die Testzugangsdaten, der Livemodus die Produktivumgebung und die Live-Zugangsdaten. Standard: an. Schalten Sie ihn aus, um echte Zahlungen anzunehmen. Solange der Testmodus aktiv ist, sehen Kunden im Schritt Confirm Order den Hinweis Test mode — no real money is charged.

Testkonto (Vorproduktion)

Test Merchant ID (PSPID): die PSPID Ihres Testkontos.

Test API Key ID: die API-Schlüssel-ID, die unter Developer > Payment API des Testkontos erstellt wurde.

Test Secret API Key: der geheime API-Schlüssel, der zu dieser API-Schlüssel-ID gehört.

Test Webhook Key ID: optional. Wenn es gesetzt ist, werden nur Webhooks akzeptiert, die mit diesem Schlüssel gesendet wurden.

Test Webhook Secret: das Webhook-Geheimnis des Testkontos. Es wird verwendet, um die Signatur jedes Webhooks zu prüfen.

Live-Konto (Produktion)

Live Merchant ID (PSPID): die PSPID Ihres Live-Kontos.

Live API Key ID: die API-Schlüssel-ID, die unter Developer > Payment API des Live-Kontos erstellt wurde.

Live Secret API Key: der geheime API-Schlüssel, der zu dieser API-Schlüssel-ID gehört.

Live Webhook Key ID: optional. Wenn es gesetzt ist, werden nur Webhooks akzeptiert, die mit diesem Schlüssel gesendet wurden.

Live Webhook Secret: das Webhook-Geheimnis des Live-Kontos.

Gespeicherte geheime Schlüssel und Webhook-Geheimnisse werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Um einen gespeicherten Wert zu entfernen, setzen Sie unter dem Feld den Haken bei Clear the saved value und klicken Sie auf Save.

Zugangsdaten prüfen: die Schaltflächen Test credentials und Live credentials prüfen die gespeicherten Zugangsdaten des jeweiligen Kontos mit einem Testaufruf bei Worldline. Speichern Sie Ihre Änderungen zuerst. Die Antwort erscheint unter den Schaltflächen, zum Beispiel Test credentials: connection successful., API credentials are not configured. oder der von Worldline zurückgegebene Fehler.

Webhooks

Der Webhook informiert Ihren Shop über Zahlungen, auch wenn der Kunde nicht in den Shop zurückkehrt, etwa weil er den Browser geschlossen hat oder eine Zahlung später bestätigt wird. Öffnen Sie im Merchant Portal unter Developer > Webhooks das Testkonto und fügen Sie die URL hinzu, die in diesem Abschnitt unter Endpoint URL angezeigt wird. Auf OpenCart 3 lautet sie etwa https://your-store/index.php?route=extension/payment/wcp_worldline_gateway/webhook, auf OpenCart 4 https://your-store/index.php?route=extension/wcp_worldline_gateway/payment/wcp_worldline_gateway.webhook. Sie wird aus der Shop-Adresse Ihrer OpenCart-Installation gebildet. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen: Sie muss ohne Weiterleitungen antworten und aus dem Internet erreichbar sein. Tragen Sie danach die Webhook-Schlüssel-ID und das Geheimnis in Test Webhook Key ID und Test Webhook Secret ein. Verfahren Sie im Live-Konto ebenso mit den Live-Feldern.

Die Erweiterung beantwortet die Verifizierungsanfrage des Worldline-Endpunkts automatisch. Sie verarbeitet Zahlungsereignisse (Statusänderungen von Zahlungen) und Erstattungsereignisse (Statusänderungen von Erstattungen). Andere Ereignisse werden akzeptiert und ignoriert. Webhooks ohne gültige Signatur werden abgelehnt. Ein Ereignis muss mit dem Geheimnis des Kontos signiert sein, in dem die Zahlung erfolgt ist; daher bestätigt ein Testwebhook nie eine Live-Zahlung. Ein Webhook wird außerdem ignoriert, wenn er von einer anderen Händler-ID stammt als der des Kontos, dessen Geheimnis ihn signiert hat. Ohne Webhook wird eine Bestellung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Zahlungsseite und Bestellungen

Payment page template: optionaler Name einer gehosteten Kassenvorlage (Variante), die im Merchant Portal hochgeladen wurde, zum Beispiel SimplifiedCustomPaymentPage. Lassen Sie das Feld leer, um die Standardseite von Worldline zu verwenden.

Order Status After Payment: welchen Status eine eingezogene Zahlung setzt. Zahlungen werden immer als direkter Verkauf (Autorisierung und Erfassung) angefordert.

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung). Die Bestellung erhält erst einen Status, nachdem Worldline die Zahlung bestätigt hat. Jedes Feld unten listet Ihre OpenCart-Bestellstatus auf.

Paid Order Status: der Status nach einer eingezogenen Zahlung mit Payment accepted (processing). Standard: Processing.

Complete Order Status: der Status nach einer eingezogenen Zahlung mit Delivered (completed). Standard: Complete.

Awaiting Capture Status: die Zahlung ist autorisiert oder die Erfassung wurde angefordert; der Erfassungs-Webhook markiert die Bestellung als bezahlt. Standard: Pending.

On Hold (Review) Status: der bezahlte Betrag oder die Währung stimmt nicht mit der Bestellung überein. Eine Notiz erklärt den Grund. Standard: Pending, da OpenCart keinen Status On hold hat. Sie können eigene Status unter System > Localisation > Order Statuses anlegen und hier auswählen.

Payment Error Status: Worldline hat die Zahlung einer Bestellung, die auf die Erfassung wartete, abgelehnt oder abgebrochen. Standard: Failed.

Refunded Status: die Zahlung wurde auf der Bestellseite vollständig erstattet. Standard: Refunded.

Erweitert

Logging: schreibt alle API-Anfragen und Webhooks in wlg_debug.log.php im Protokollordner von OpenCart (storage/logs). Die Datei kann nicht über das Web geöffnet werden; bei 5 MB wird sie nach wlg_debug.old.log.php verschoben. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel, Kartendaten und personenbezogene Daten werden maskiert. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Delete Data: ist die Option aktiv, entfernt das Deinstallieren der Erweiterung die Einstellungen des Gateways und das Protokoll. Die Worldline-Transaktionen und Erstattungen bleiben immer erhalten, weil bestehende Bestellungen sie für Erstattungen benötigen. Standard: aus.

Import / Export

Export: Download JSON speichert die Einstellungen als JSON-Datei. Geheime Schlüssel und Webhook-Geheimnisse werden nicht exportiert.

Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Die gespeicherten Geheimnisse bleiben erhalten.

Kasse

Im Schritt Payment Method wählt der Kunde die Zahlungsmethode (standardmäßig Worldline). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Klickt der Kunde auf Confirm Order, erstellt die Erweiterung eine gehostete Worldline-Kasse für den Bestellbetrag in der Bestellwährung und leitet den Kunden zur Zahlungsseite von Worldline weiter. Dort bezahlt der Kunde mit einer Karte, einer digitalen Geldbörse oder einer anderen Zahlungsmethode, die in Ihrem Worldline-Konto aktiviert ist. Name, Adresse, E-Mail und Telefonnummer für die Rechnung werden an Worldline übergeben, und die Zahlungsseite öffnet sich in der Sprache des Kunden, sofern Worldline diese unterstützt. Jeder Zahlungsversuch erhält eine eigene Referenz aus der Bestellnummer und einem Zufallsteil. Auf OpenCart 4 wählt der Kunde die Zahlungsmethode mit der Schaltfläche Choose im Block der Zahlungsmethode im Fenster Payment method options und klickt unten auf der Kassenseite auf Confirm Order.

Nach der Zahlung kehrt der Kunde zu Ihrem Shop zurück. Die Erweiterung prüft die Rückkehr anhand des gespeicherten Versuchs und liest den Zahlungsstatus serverseitig bei Worldline aus. Die Bestellung wird erst als bezahlt markiert, wenn Worldline bestätigt: durch diese Statusprüfung oder durch einen signierten Webhook. Die Bestellung erhält dann ihren Status auf die übliche OpenCart-Weise, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die OpenCart-Erfolgsseite mit Your payment with Worldline has been received. Ist die Zahlung autorisiert, aber noch nicht erfasst, zeigt die Seite Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Schlägt die Zahlung einer solchen Bestellung fehl, zeigt die Seite Your Worldline payment was not completed. Please contact us about this order.

Wurde die Zahlung nicht abgeschlossen, behält die Bestellung keinen Status, der Warenkorb bleibt erhalten, und der Kunde kehrt mit einer Meldung zur Kasse zurück:

Konnte der Status noch nicht geprüft werden, zeigt eine Seite Payment confirmation die Meldung We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. mit den Schaltflächen Check again und Back to checkout. Der Webhook setzt den Bestellstatus, sobald er eintrifft.

Auf OpenCart 4 werden diese Meldungen über der Kasse angezeigt.

OpenCart 3 legt jedes Mal, wenn der Schritt Confirm Order angezeigt wird, eine neue Bestellung an; OpenCart 4 behält für die Kasse eine Bestellung und aktualisiert sie, daher bezahlt der Kunde nach einem Abbruch oder einer Ablehnung dieselbe Bestellung auf einer neuen Worldline-Zahlungsseite. Vor einer neuen Zahlung prüft die Erweiterung den Warenkorb: Ist eine andere Bestellung desselben Warenkorbs bereits bezahlt oder wurde der vorherige Versuch inzwischen bezahlt, gelangt der Kunde direkt zur Erfolgsseite und wird nicht doppelt belastet. Ist die vorherige Zahlungsseite derselben Bestellung noch offen, für denselben Betrag und Modus, und wurde sie vor weniger als 30 Minuten erstellt, wird der Kunde dorthin zurückgeschickt.

Auf OpenCart 4, wenn die Zahlung der Bestellung der Kasse nach der Autorisierung abgelehnt oder abgebrochen wurde, schickt der nächste Confirm Order den Kunden mit der Meldung zur abgelehnten Zahlung statt zur Erfolgsseite zurück zur Kasse. Hat der Shop diese Bestellung geschlossen (zum Beispiel storniert oder erstattet), lautet die Meldung Your previous order was closed by the shop (cancelled / refunded). Please confirm the order again to pay with a new order. In beiden Fällen bezahlt der nächste Confirm Order eine neue Bestellung. Ist die Bestellung der Kasse bereits bezahlt, der Warenkorb seitdem aber geändert, auch durch eine neue Menge, wird der Kunde zur Kasse zurückgeschickt, und der neue Warenkorb wird mit einer neuen Bestellung bezahlt.

Kann Worldline die Zahlung nicht starten, bleibt der Kunde im Schritt Confirm Order mit der Meldung Payment error: Could not create checkout session. Please try again. oberhalb der Schaltfläche. Der Grund wird im Protokoll festgehalten. Fehlen die Zugangsdaten des aktuellen Modus, sieht der Kunde This payment method is not available at the moment. Please choose another payment method.

Der Webhook und die Rückkehr des Kunden funktionieren auch, während der Shop im Wartungsmodus ist: OpenCart 3 lässt Anfragen von Zahlungserweiterungen durch, und auf OpenCart 4 fügt die Erweiterung dafür eine Startaktion hinzu.

Die Erweiterung nimmt einmalige Zahlungen als direkten Verkauf auf der Seite von Worldline entgegen. Sie bietet keine gespeicherten Karten oder Tokenisierung, keine Abonnements, kein eingebettetes Kartenformular, keinen reinen Autorisierungsmodus mit Erfassung oder Stornierung aus OpenCart, keine Aufschläge und keine automatische Registrierung von Webhooks.

Bestellungen und Erstattungen

Bestellstatus

Kein Status (fehlende Bestellung): der Kunde wurde zu Worldline weitergeleitet und hat nicht bezahlt, oder Worldline hat die Zahlung noch nicht bestätigt. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt.

Paid Order Status oder Complete Order Status (Standard Processing oder Complete): die Zahlung wurde erfasst. Der Status folgt Order Status After Payment. Eine Notiz zeigt den Betrag, die Worldline-Zahlungs-ID und wie die Zahlung bestätigt wurde (signierter Webhook oder Statusprüfung).

Awaiting Capture Status (Standard Pending): Worldline meldet die Zahlung als autorisiert oder die Erfassung als angefordert, aber noch nicht erfasst. Die Bestellung wechselt in den bezahlten Status, wenn der Webhook die Erfassung bestätigt. Sagt die Notiz, dass die Zahlung nicht erfasst ist, erfassen Sie sie im Worldline Merchant Portal.

On Hold (Review) Status (Standard Pending): die Zahlung passt nicht zur Bestellung, zum Beispiel weil Betrag oder Währung abweichen oder die Zahlung zu einem anderen Versuch gehört. Die Notiz zeigt den bezahlten Betrag, die Bestellsumme und die Referenz. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.

Payment Error Status (Standard Failed): Worldline hat die Zahlung einer Bestellung, die auf die Erfassung wartete, abgelehnt oder abgebrochen.

Refunded Status (Standard Refunded): die Zahlung wurde über die Erweiterung vollständig erstattet.

Trifft eine Zahlung für eine stornierte oder erstattete Bestellung ein, wird die Bestellung nicht wieder geöffnet. Eine Notiz bittet Sie, die Zahlung im Worldline Merchant Portal zu stornieren oder zu erstatten oder die Bestellung manuell wiederherzustellen. Der zurückkehrende Kunde sieht Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. Trifft eine zweite Zahlung für eine bereits bezahlte Bestellung oder für eine andere Bestellung eines bereits bezahlten Warenkorbs ein, wird die Bestellung nicht verändert. Eine Notiz an der bezahlten Bestellung bittet Sie, die zweite Zahlung im Worldline Merchant Portal zu erstatten.

Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht. Sie beginnen mit dem Wort Worldline.

Reiter VibeFox Worldline Gateway

Öffnen Sie unter Sales > Orders eine mit Worldline bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt der Reiter VibeFox Worldline Gateway den Block Worldline payment mit Payment ID, Merchant reference, Hosted checkout, dem Status des Versuchs, Amount charged / refunded, einem Kennzeichen Test environment für Testzahlungen, dem Erstattungsformular, dem Erstattungsverlauf und den Payment notes der Bestellung. Der Reiter wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Erstattungen

Geben Sie im Reiter VibeFox Worldline Gateway den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via Worldline. Bestätigen Sie die Frage Refund this amount through Worldline? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Die Zahlung muss erfasst sein. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Erstattungen erfolgen in dem Betrag und der Währung, die Worldline belastet hat; nach einer Abweichung von Betrag oder Währung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird immer an die Umgebung der ursprünglichen Zahlung (Test oder Live) mit den Zugangsdaten dieses Kontos gesendet, daher müssen diese eingerichtet sein. Eine Erstattung, die nach einem Timeout erneut versucht wird, wird nicht zweimal ausgeführt, und pro Bestellung läuft immer nur eine Erstattung gleichzeitig. Lehnt Worldline die Erstattung ab, zeigt der Reiter den Fehler, und es wird keine Erstattung erfasst. Eine akzeptierte Erstattung wird dem Erstattungsverlauf und den Notizen mit der Worldline-Erstattungs-ID und dem Status hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, ohne den Kunden zu benachrichtigen und ohne Produkte in den Bestand zurückzubuchen, wie bei einer manuellen Statusänderung. Eine Teilerstattung ändert den Status nicht.

Produktrückgaben unter Sales > Returns senden kein Geld über Worldline zurück.

Statusänderungen von Erstattungen kommen von Worldline per Webhook, aktualisieren den Erstattungsverlauf und werden den Notizen hinzugefügt. Im Merchant Portal vorgenommene Erstattungen ändern den Bestellstatus nicht; aktualisieren Sie ihn bei Bedarf manuell.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Worldline Gateway ist der erste Block auf Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) und die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-payment-worldline und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit dem Recht Modify für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (Englisch und Russisch sind enthalten).

Wenn der Schlüssel nicht akzeptiert wird, zeigt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Shop-Adresse aus der OpenCart-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Worldline Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der im Admin-Bereich im selben Browser angemeldet ist, sieht die Zahlungsmethode im Shop weiterhin, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Unter OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Zahlungsmethode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Admin-Bereichs. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Wenn eine Lizenz abläuft, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Admin-Bereichs oder die Seite Edit öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.

Fehlerbehebung

Worldline erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus eine Händler-ID, eine API-Schlüssel-ID und einen geheimen API-Schlüssel hat: die Testfelder im Testmodus, die Live-Felder im Livemodus. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen. Prüfen Sie außerdem, ob die Zahlungsadresse in der gewählten Geo Zone liegt und ob die Bestellung die in den Einstellungen festgelegte Total erreicht.

Die Zahlung ist erfolgt, aber die Bestellung bleibt ohne Status: der Webhook funktioniert nicht. Prüfen Sie im Merchant Portal des von Ihnen genutzten Kontos (Test oder Live), ob der Endpunkt existiert und ob seine URL genau der unter Endpoint URL angezeigten entspricht, ohne Weiterleitungen. Prüfen Sie, ob das Webhook-Geheimnis dieses Kontos im passenden Feld steht (Test Webhook Secret oder Live Webhook Secret) und ob das Feld für die Webhook-Schlüssel-ID leer ist oder dem Schlüssel entspricht. Die Bestellung erhält ihren Status auch dann, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Webhook answers Webhook secret not configured: keines der beiden Webhook-Geheimnisse ist gesetzt. Tragen Sie das Webhook-Geheimnis in den Einstellungen ein. Worldline wiederholt den Webhook.

Webhook answers Invalid signature: das Webhook-Geheimnis gehört zu einem anderen Konto oder einem anderen Schlüssel, oder die Webhook-Schlüssel-ID stimmt nicht mit dem Schlüssel überein, der den Webhook gesendet hat. Prüfen Sie, ob die Test- und Live-Geheimnisse vertauscht sind.

Webhook answers Missing signature, Empty body or Invalid JSON: die Anfrage kam nicht in der erwarteten Form von Worldline, oder ein Proxy oder eine Weiterleitung hat sie verändert. Prüfen Sie, ob die URL ohne Weiterleitungen antwortet.

Webhook answers Ignored: der Webhook stammt von einer anderen Händler-ID als der in den Einstellungen dieses Modus. Prüfen Sie Test Merchant ID (PSPID) bzw. Live Merchant ID (PSPID).

Webhook answers Retry later: die Bestellung wurde im selben Moment von einer anderen Anfrage bestätigt, oder der Bestellstatus konnte nicht gesetzt werden. Worldline wiederholt den Webhook. Den Grund finden Sie im Feld Log.

Die Webhook-URL zeigt Method not allowed im Browser: das ist normal. Die URL akzeptiert nur Anfragen von Worldline.

Test credentials oder Live credentials zeigt einen Fehler: speichern Sie die Einstellungen zuerst und prüfen Sie dann, ob Händler-ID, API-Schlüssel-ID und geheimer API-Schlüssel aus demselben Konto stammen und ob die Testwerte in den Testfeldern und die Livewerte in den Live-Feldern stehen.

Der Kunde sieht nach Confirm Order einen Fehler: sehen Sie im Feld Log auf der Erweiterungsseite nach. Fehler werden auch dann protokolliert, wenn Logging aus ist. Für vollständige Details zu den Anfragen aktivieren Sie Logging und versuchen Sie es erneut.

Testzahlungen bestätigen keine Live-Zahlung: Test und Live sind getrennt. Stellen Sie Test Mode auf den gewünschten Modus und verwenden Sie die Zugangsdaten und den Webhook dieses Kontos.

Bestellung ist nach der Zahlung im Prüfstatus oder wartet auf die Erfassung: lesen Sie die Notizen im Reiter VibeFox Worldline Gateway (siehe Bestellstatus). Entweder hat Worldline die Erfassung noch nicht bestätigt (der Webhook schließt die Bestellung ab), oder der bezahlte Betrag oder die Währung wich von der Bestellung ab.

Kein Erstattungsformular im Reiter: der Reiter nennt den Grund: keine erfasste Worldline-Zahlung, die Zahlung ist vollständig erstattet, Ihre Benutzergruppe hat kein Recht, die Erweiterung zu ändern, oder die Zugangsdaten der Umgebung der Zahlung sind nicht gesetzt.

Erstattung schlägt mit einer Meldung zur Umgebung fehl: die Zahlung wurde in der Test- oder Live-Umgebung gemacht, und die Zugangsdaten dieser Umgebung sind nicht gesetzt. Geben Sie sie ein und versuchen Sie es erneut.

Für Entwickler: Bevor die gehostete Kasse erstellt wird, löst die Erweiterung das OpenCart-Ereignis wlg_hosted_checkout_data mit den Anfragedaten und der Bestellung aus, zum Beispiel um die angezeigten Zahlungsmethoden einzuschränken.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox Worldline Gateway auf Uninstall (der rote −-Button). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart entfernt immer die eigenen Einstellungen der Erweiterung: Enable/Disable, Sort Order, Geo Zone, Total und die Bestellstatus aus dem Abschnitt Payment page and orders, die bei einer erneuten Installation auf ihre Standardwerte zurückgesetzt werden. Auch das OpenCart-Ereignis der Erweiterung wird entfernt (auf OpenCart 4 auch seine Ereignisse und seine Startaktion, die im Wartungsmodus den Webhook und die Rückkehr des Kunden durchlässt). Ist Delete Data aktiv, werden die übrigen Gateway-Einstellungen (Titel, Beschreibung, Testmodus, Zugangsdaten, Webhook-Geheimnisse, Seitenvorlage, Protokollierung) und das Protokoll entfernt. Ist die Option aus, bleiben sie für eine spätere Neuinstallation erhalten. Die Worldline-Transaktionen und -Erstattungen bleiben immer erhalten, sodass vorher bezahlte Bestellungen auch nach einer Neuinstallation erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Auf OpenCart 4 entfernen Sie die Dateien der Erweiterung ebenfalls, indem Sie nach der Deinstallation zu Extensions > Installer gehen, neben VibeFox Worldline Gateway in der Liste der installierten Erweiterungen auf Uninstall (die orangefarbene −-Schaltfläche) klicken und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Worldline ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Worldline verbunden und wird von Worldline nicht unterstützt.