VibeFox Worldline for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

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 Merchant ID (Ihre PSPID), eine API Key ID mit dem zugehörigen Secret API Key sowie einen Webhook-Schlüssel mit dem zugehörigen Secret. Alles wird im Merchant Portal von Worldline erstellt (siehe „Configuration“).

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

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Alternativ können Sie den Ordner wcp_worldline_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage oder klicken Sie auf der Seite „Plugins“ unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Geben Sie die Testzugangsdaten ein, speichern Sie die Einstellungen und klicken Sie auf Test credentials.

6. Tragen Sie die Webhook-URL im Merchant Portal des Testkontos ein und geben Sie den Webhook-Schlüssel und das Secret ein (siehe „Configuration“).

7. Aktivieren Sie Enable/Disable und führen Sie eine Testzahlung durch. Geben Sie danach die Live-Zugangsdaten ein, richten Sie den Webhook in Ihrem Live-Konto ebenso ein, klicken Sie auf Live credentials und deaktivieren Sie Test Mode.

Configuration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Worldline (Ingenico). In der Liste der Zahlungsarten ist Worldline als „Einrichtung erforderlich“ markiert, bis der aktuelle Modus eine Merchant ID, eine API Key ID und einen Secret API Key hat. Auf der Einstellungsseite sind die Zugangsdatenfelder des nicht verwendeten Modus abgeblendet.

General

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Worldline.

Description: der Text unter der Zahlungsart an der Kasse. Standard: Pay securely via Worldline.

Worldline Direct API

Holen Sie die Zugangsdaten im Merchant Portal von Worldline, sowohl für das Testkonto als auch für das Live-Konto. Ihre PSPID ist die Merchant ID. Unter Developer > Payment API werden die API Key ID und der Secret API Key erstellt, unter Developer > Webhooks der Webhook-Schlüssel und das Secret. Der Abschnitt enthält Links zu beiden Portalen und zur Worldline-Dokumentation.

Test Mode: Enable test mode (pre-production environment, no real money) schaltet sowohl den API-Endpunkt als auch die Zugangsdaten um. Der Testmodus nutzt die Vorproduktionsumgebung und die Testzugangsdaten, der Live-Modus die Produktionsumgebung und die Live-Zugangsdaten. Standard: an. Deaktivieren Sie die Option, um echte Zahlungen anzunehmen. Solange der Testmodus aktiv ist, sehen Kunden unter der Zahlungsart Test mode — no real money is charged.

Testkonto (Vorproduktion)

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

Test API Key ID: die API Key ID, die unter Developer > Payment API im Testkonto erstellt wurde.

Test Secret API Key: der Secret API Key zu dieser API Key ID.

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

Test Webhook Secret: das Webhook-Secret des Testkontos. Es dient dazu, 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 Key ID, die unter Developer > Payment API im Live-Konto erstellt wurde.

Live Secret API Key: der Secret API Key zu dieser API Key ID.

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

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

Zugangsdaten prüfen

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

Webhooks

Der Webhook informiert Ihren Shop über Zahlungen, auch wenn der Kunde nicht in den Shop zurückkehrt, etwa nach dem Schließen des Browsers oder wenn eine Zahlung später bestätigt wird. Öffnen Sie im Merchant Portal des Testkontos Developer > Webhooks und fügen Sie die Endpunkt-URL hinzu, die in diesem Abschnitt der Einstellungen angezeigt wird. Sie sieht etwa so aus: https://your-site/wc-api/wlg_worldline_webhook/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen: Sie muss ohne Weiterleitungen antworten, prüfen Sie daher Sprachpräfixe sowie erzwungene www- oder https-Weiterleitungen. Tragen Sie danach die Webhook-Schlüssel-ID und das Secret in Test Webhook Key ID und Test Webhook Secret ein. Verfahren Sie im Live-Konto genauso mit den Live-Feldern.

Das Plugin beantwortet die Verifizierungsanfrage des Worldline-Endpunkts automatisch. Es verarbeitet Zahlungsereignisse (Änderungen des Zahlungsstatus) und Erstattungsereignisse (Änderungen des Erstattungsstatus). Andere Ereignisse werden angenommen und ignoriert. Webhooks ohne gültige Signatur werden abgelehnt. Ein Webhook wird auch ignoriert, wenn er von einer anderen Merchant ID stammt als der des Kontos, dessen Secret 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 Checkout-Vorlage (Variante), die im Merchant Portal hochgeladen wurde, zum Beispiel SimplifiedCustomPaymentPage. Lassen Sie das Feld leer, um die Standard-Zahlungsseite von Worldline zu verwenden.

Order Status After Payment: der Bestellstatus, sobald Worldline die erfasste Zahlung bestätigt. Der Status wird sofort gesetzt, ohne zweiten Statuswechsel. Zahlungen werden immer als direkter Verkauf (Autorisierung und Erfassung) angefordert.

Logging: Enable debug logging schreibt alle API-Anfragen und Webhooks in WooCommerce > Status > Logs, Quelle wcp_worldline_gateway. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel, Kartendaten und personenbezogene Daten werden maskiert. Standard: aus.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. Das Deaktivieren des Plugins löscht nie etwas. Zahlungsdaten, die in Bestellungen gespeichert sind, bleiben erhalten, weil sie für Erstattungen benötigt werden. Standard: aus.

Bei einem Update von Version 1.0 wird der bisherige einzelne Satz an Zugangsdaten in die Test- oder Live-Felder übernommen, je nachdem, welchen Modus der Shop verwendet hat.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Worldline) und gibt die Bestellung auf. Das Plugin erstellt eine gehostete Worldline-Zahlungsseite für den Bestellbetrag in der Bestellwährung und leitet den Kunden auf die Zahlungsseite von Worldline weiter. Dort zahlt der Kunde mit Karte, einer Wallet oder einer anderen in Ihrem Worldline-Konto aktivierten Zahlungsart. Rechnungsname, Adresse, E-Mail-Adresse und Telefonnummer werden an Worldline übergeben, und die Zahlungsseite öffnet sich in der Sprache Ihres Shops, sofern Worldline sie unterstützt. Jeder Zahlungsversuch erhält eine eigene Referenz, die aus der Bestellnummer und einem Zufallsteil besteht.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Das Plugin prüft die Rückkehr anhand des gespeicherten Versuchs und liest den Zahlungsstatus serverseitig von Worldline aus. Die Bestellung wird erst als bezahlt markiert, wenn Worldline die Zahlung bestätigt: durch diese Statusabfrage oder durch einen signierten Webhook. Danach sieht der Kunde die Bestellbestätigungsseite.

Wurde die Zahlung nicht abgeschlossen, gelangt der Kunde zur Seite Pay for order mit einer Meldung:

Ein Kunde kann eine unbezahlte Bestellung über die Seite Pay for order erneut bezahlen. Wurde der vorherige Versuch inzwischen bezahlt, gelangt der Kunde direkt zur Bestellbestätigungsseite und wird nicht doppelt belastet. Ist die vorherige Zahlungsseite für denselben Betrag und Modus noch geöffnet und vor weniger als 30 Minuten erstellt worden, wird der Kunde zu ihr zurückgeschickt.

Kann Worldline die Zahlung nicht starten, sieht der Kunde Payment error: Could not create checkout session. Please try again. und kann eine andere Zahlungsart wählen. Der Grund wird den Bestellnotizen und dem Protokoll hinzugefügt. Fehlen die Zugangsdaten des aktuellen Modus, sieht der Kunde This payment method is not available at the moment. Please choose another payment method.

Die Zahlungsart funktioniert an der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order. Sie ist mit der WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin nimmt einmalige Zahlungen als direkten Verkauf auf der Worldline-Seite entgegen. Es unterstützt keine gespeicherten Karten oder Tokenisierung, keine Abonnements, kein eingebettetes Kartenformular, keinen reinen Autorisierungsmodus mit Erfassung oder Stornierung aus WooCommerce, keine Zuschläge und keine automatische Registrierung von Webhooks.

Bestellungen und Erstattungen

Order statuses

Pending payment: Der Kunde wurde zu Worldline weitergeleitet und hat noch nicht bezahlt, oder Worldline hat die Zahlung noch nicht bestätigt. Eine Notiz zeigt die ID der gehosteten Zahlungsseite, die Referenz und den Modus (Test oder Live).

Processing or Completed: Die Zahlung wurde erfasst. Der Status richtet sich nach Order Status After Payment. Die Bestellnotiz zeigt den Betrag, die Worldline-Zahlungs-ID und wie die Zahlung bestätigt wurde (signierter Webhook oder Statusabfrage). Die Transaktions-ID der Bestellung ist die Worldline-Zahlungs-ID.

On hold, waiting for capture: Worldline meldet die Zahlung als autorisiert oder die Erfassung als angefordert, aber noch nicht erfasst. Die Bestellnotiz erklärt dies. Die Bestellung wird automatisch als bezahlt markiert, sobald der Webhook die Erfassung bestätigt. Wenn in der Notiz steht, dass die Zahlung nicht erfasst ist, erfassen Sie sie im Merchant Portal von Worldline.

On hold, held for manual review: Die Zahlung passt nicht zur Bestellung, zum Beispiel weichen Betrag oder Währung ab (die Bestellung wurde nach Beginn der Zahlung geändert), oder die Zahlung gehört zu einem anderen Versuch. Die Notiz zeigt den bezahlten Betrag, die Bestellsumme und die Referenz. Prüfen Sie die Bestellung und führen Sie sie aus oder erstatten Sie die Zahlung.

Failed: Worldline hat die Zahlung des letzten Versuchs abgelehnt oder abgebrochen, oder der Kunde war für die gewählte Zahlungsart nicht berechtigt.

Cancelled: Die Bestellung wurde von Ihnen oder durch das Zeitlimit der Lagerreservierung in WooCommerce storniert. 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 Merchant Portal von Worldline zu erstatten oder zu stornieren 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 ein, wird die Bestellung nicht erneut geändert. Eine Notiz bittet Sie, die zweite Zahlung im Merchant Portal von Worldline zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Worldline (Ingenico). Vollständige und teilweise Erstattungen werden unterstützt. Die Zahlung muss erfasst sein. 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 nach einem Timeout wiederholte Erstattung wird nicht doppelt ausgeführt. Lehnt Worldline die Erstattung ab, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst. Eine akzeptierte Erstattung wird mit der Worldline-Erstattungs-ID und dem Status in den Bestellnotizen vermerkt.

Statusänderungen bei Erstattungen kommen von Worldline per Webhook und werden in den Bestellnotizen vermerkt. Im Merchant Portal vorgenommene Erstattungen werden nicht automatisch als WooCommerce-Erstattungen erfasst. Erstellen Sie bei Bedarf eine manuelle Erstattung in WooCommerce ohne Refund via Worldline (Ingenico).

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Worldline (Ingenico). Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren 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. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Seite „Plugins“ und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, für Updates und Support ist aber eine Verlängerung nötig. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Worldline erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus eine Merchant ID, eine API Key ID und einen Secret API Key hat: die Testfelder im Testmodus, die Live-Felder im Live-Modus. Fehlen Angaben, markiert die Zahlungsliste die Zahlungsart als „Einrichtung erforderlich“.

Die Zahlung war erfolgreich, aber die Bestellung bleibt bei Pending payment: Der Webhook funktioniert nicht. Prüfen Sie im Merchant Portal des verwendeten Kontos (Test oder Live), ob der Endpunkt existiert und ob seine URL genau der Angabe in den Einstellungen entspricht, ohne Weiterleitungen. Prüfen Sie, ob das Webhook-Secret dieses Kontos im passenden Feld steht (Test Webhook Secret oder Live Webhook Secret) und ob Webhook Key ID leer ist oder zum Schlüssel passt. Die Bestellung wird auch bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Webhook antwortet Webhook secret not configured: Es ist kein Webhook-Secret gesetzt. Tragen Sie das Webhook-Secret in den Einstellungen ein. Worldline wiederholt den Webhook.

Webhook antwortet Invalid signature: Das Webhook-Secret gehört zu einem anderen Konto oder einem anderen Schlüssel, oder die Webhook Key ID stimmt nicht mit dem Schlüssel überein, der den Webhook gesendet hat.

Webhook antwortet Missing signature, Empty body oder 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 antwortet Ignored: Der Webhook stammt von einer anderen Merchant ID als der in den Einstellungen dieses Modus. Prüfen Sie Test Merchant ID (PSPID) bzw. Live Merchant ID (PSPID).

Webhook antwortet Retry later: Die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert. Worldline wiederholt den Webhook.

Test credentials oder Live credentials zeigt einen Fehler: Speichern Sie die Einstellungen zuerst und prüfen Sie dann, ob Merchant ID, API Key ID und Secret API Key vom selben Konto stammen und ob die Testwerte in den Testfeldern und die Live-Werte in den Live-Feldern stehen.

Der Kunde sieht beim Aufgeben der Bestellung einen Fehler: Öffnen Sie die Bestellnotizen oder WooCommerce > Status > Logs, Quelle wcp_worldline_gateway. Fehler werden auch dann protokolliert, wenn das Debug-Logging aus ist. Für vollständige Details der Anfragen aktivieren Sie Logging und versuchen Sie es erneut.

Testzahlungen bestätigen keine Live-Bestellung: Test und Live sind getrennt. Ein mit dem Testsecret signierter Webhook bestätigt nie einen Live-Zahlungsversuch und umgekehrt. Stellen Sie Test Mode auf den gewünschten Modus um und verwenden Sie die Zugangsdaten und den Webhook dieses Kontos.

Bestellung nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Entweder hat Worldline die Erfassung noch nicht bestätigt (der Webhook schließt die Bestellung ab), oder der bezahlte Betrag bzw. die Währung wich von der Bestellung ab.

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

Entwickler: Der Filter wlg_hosted_checkout_data ändert die Anfrage an die gehostete Zahlungsseite, zum Beispiel um die angezeigten Zahlungsarten einzuschränken, und wlg_gateway_icon ändert das Symbol der Zahlungsart.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Einstellungen des Gateways und die Protokolle werden nur entfernt, wenn Delete Data aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Die in Bestellungen gespeicherten Worldline-Zahlungsdaten bleiben immer erhalten, weil sie für Erstattungen benötigt werden. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Worldline ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Worldline verbunden noch wird es von Worldline unterstützt.