VibeFox Nexi XPay for WooCommerce — Hilfe

Voraussetzungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv.

PHP: 8.0 oder neuer.

Währung: Die Shop- bzw. Bestellwährung muss EUR sein. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.

Nexi-XPay-Konto: Sie benötigen ein Nexi-XPay-Händlerkonto („Pagamento Semplice“, Weiterleitungsintegration) mit dem Alias (Terminal-ID) und dem MAC-Schlüssel Ihres Terminals. Test- und Live-Zugangsdaten sind getrennt: Testdaten erhalten Sie im Testbereich von Nexi XPay oder im Developer-Portal (developer.nexi.it), Live-Daten im Back-Office von Nexi XPay, sobald das Händlerkonto aktiviert ist. Im Nexi-Back-Office muss nichts eingerichtet werden: Die Benachrichtigungsadresse wird bei jeder Zahlung übermittelt.

Öffentliche Website: Die Benachrichtigungs-URL muss aus dem Internet erreichbar sein, ohne Wartungsmodus, Basisauthentifizierung oder Firewall-Regel, die Nexi blockiert. Andernfalls wird die Zahlung trotzdem durch die signierte Rückkehr des Kunden bestätigt.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert für eine 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_nexi_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Nexi XPay > Manage, oder klicken Sie auf der Plugins-Seite 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. Lassen Sie Test Mode eingeschaltet und geben Sie den Test-Alias und den MAC-Schlüssel ein (siehe Konfiguration).

6. Schalten Sie Enable/Disable ein und führen Sie eine Testbestellung durch. Wenn alles funktioniert, geben Sie Live-Alias und MAC-Schlüssel ein und deaktivieren Sie Test Mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Nexi XPay. Oberhalb der Felder zeigt die Seite Der Testmodus ist aktiv: Zahlungen gehen an die Testumgebung von Nexi XPay, es wird kein echtes Geld belastet., solange der Testmodus eingeschaltet ist. Sie warnt, wenn das Gateway aktiviert ist, aber Alias oder MAC-Schlüssel des aktuellen Modus fehlen, oder wenn die Shopwährung nicht EUR ist. In beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet. Leerzeichen und Zeilenumbrüche um eingefügte Schlüssel werden beim Speichern entfernt.

Allgemein

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

Title: der Titel der Zahlungsart, den der Kunde an der Kasse sieht. Standard: Credit Card (Nexi). Im Testmodus fügt die Kasse dem Titel (TEST MODE) hinzu.

Description: die Beschreibung der Zahlungsart, die der Kunde an der Kasse sieht. Standard: Pay securely with your credit card via Nexi XPay.

Testumgebung

Testzahlungen gehen an int-ecommerce.nexi.it und belasten nie echte Karten. Test-Alias und MAC-Schlüssel erhalten Sie im Testbereich von Nexi XPay oder im Developer-Portal (developer.nexi.it).

Test Mode: Enable test mode nutzt die Testumgebung von Nexi XPay und die Testzugangsdaten. Deaktivieren Sie es, um echte Zahlungen mit den Live-Zugangsdaten anzunehmen. Standard: ein.

Test Alias: der Alias (Terminal-ID) Ihres Nexi-XPay-Testterminals.

Test MAC Key: der MAC-Berechnungsschlüssel Ihres Nexi-XPay-Testterminals.

Live-Umgebung

Live-Alias und MAC-Schlüssel werden in Ihrem Back-Office von Nexi XPay (ecommerce.nexi.it) angezeigt, nachdem Ihr Händlerkonto aktiviert wurde.

Live Alias: der Alias (Terminal-ID) Ihres Live-Terminals von Nexi XPay.

Live MAC Key: der MAC-Berechnungsschlüssel Ihres Live-Terminals von Nexi XPay.

Zahlung

Die Benachrichtigungs-URL wird bei jeder Zahlung an Nexi übermittelt, daher muss im Back-Office nichts eingerichtet werden. Der Abschnitt zeigt sie an; sie sieht etwa so aus: https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, am Ende mit der Bestell-ID. Nexi sendet das Zahlungsergebnis Server-zu-Server an diese URL und übergibt es außerdem bei der Rückkehr des Kunden. Beide sind gleich signiert und werden mit dem MAC-Schlüssel der Umgebung, in der bezahlt wurde, dem Alias dieser Umgebung und der für diese Bestellung ausgestellten Transaktionsnummer geprüft. Ergebnisse, die die Prüfung nicht bestehen, werden abgelehnt und ändern nichts.

Capture: wann das Geld eingezogen wird.

Immediate capture: die Zahlung wird sofort erfasst und die Bestellung als bezahlt markiert (Standard).

Deferred capture (authorize only): die Erfassung richtet sich nach Ihrem Terminal-Profil. Die Bestellung wird als autorisiert auf Wartend gesetzt, bis Sie sie mit der Bestellaktion Capture Nexi XPay payment erfassen oder im Nexi-Back-Office erfassen und die Bestellung dann auf In Bearbeitung setzen.

Order Status After Payment: der Status der Bestellung nach erfolgreicher Zahlung. Der Status wird sofort gesetzt, mit einer Statusänderung und einer E-Mail.

In Bearbeitung (WooCommerce-Standard): der Standard.

Abgeschlossen: jede bezahlte Bestellung wird Abgeschlossen.

Wartend: jede bezahlte Bestellung wartet auf Ihre manuelle Prüfung.

Erweitert

Debug Log: Enable logging protokolliert Zahlungsereignisse unter WooCommerce > Status > Logs, Quelle wcp_nexi_gateway. MAC-Schlüssel, Kartendaten und E-Mail-Adressen werden nicht protokolliert. Fehler und Warnungen, zum Beispiel eine fehlgeschlagene MAC-Prüfung, werden immer protokolliert, auch wenn die Option aus ist. Standard: aus.

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Credit Card (Nexi)) und gibt die Bestellung auf. Die nächste Seite zeigt Weiterleitung zu Nexi XPay für die Zahlung... und leitet den Kunden automatisch zur Nexi-XPay-Seite weiter, mit einer Schaltfläche Pay Now als Alternative. Die Zahlung wird in EUR mit einem neuen Transaktionscode, der E-Mail-Adresse des Kunden und der Beschreibung Order, der Bestellnummer und Ihrem Shopnamen übermittelt. Die Nexi-Seite öffnet sich in der Shop-Sprache, wenn es Italienisch, Englisch, Spanisch, Französisch, Deutsch, Japanisch, Chinesisch, Arabisch, Russisch oder Portugiesisch ist, sonst auf Englisch.

Der Kunde zahlt und kehrt zur Bestellbestätigungsseite Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn ein geprüftes Nexi-Ergebnis mit genau dem Bestellbetrag und der Bestellwährung vorliegt: entweder die Server-zu-Server-Benachrichtigung oder die signierte Rückkehr des Kunden, je nachdem, was zuerst eintrifft.

Wird die Zahlung abgelehnt oder bricht der Kunde auf der Nexi-Seite ab, kehrt er zur Kasse zurück (oder zur Seite Pay for order, wenn der Warenkorb leer ist) und sieht eine dieser Meldungen: Die Zahlung wurde nicht abgeschlossen. Bitte versuchen Sie es erneut oder wählen Sie eine andere Zahlungsart., Die Zahlung wurde abgebrochen. Bitte versuchen Sie es erneut. oder Wir konnten die Zahlung nicht bestätigen. Wenn Ihre Karte belastet wurde, kontaktieren Sie uns bitte, bevor Sie erneut zahlen. Ein Abbruch auf der Nexi-Seite lässt die Bestellung unverändert, sodass der Kunde erneut zahlen kann.

Ist das Plugin für den aktuellen Modus nicht eingerichtet, sieht der Kunde Diese Zahlungsart ist derzeit nicht verfügbar. Bitte wählen Sie eine andere Zahlungsart.

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

Das Plugin nimmt Zahlungen nur über die Nexi-XPay-Seite an. Es gibt keine Erstattungen aus WooCommerce, keine gespeicherten Karten oder OneClick, keine Abonnements oder wiederkehrenden Zahlungen, kein Pay-By-Link, keine eingebetteten XPay-Build-Felder und keine in WooCommerce ausgewählten Zahlungsarten: Die Nexi-Seite zeigt die auf Ihrem Terminal aktivierten Methoden.

Bestellungen und Erstattungen

Bestellstatus

Zahlung ausstehend: Der Kunde wurde zu Nexi weitergeleitet und hat noch nicht gezahlt oder auf der Nexi-Seite abgebrochen.

In Bearbeitung, Abgeschlossen oder Wartend: Nexi hat die Zahlung bestätigt. Der Status richtet sich nach Order Status After Payment. Die Bestellnotiz zeigt den Autorisierungscode, den Transaktionscode, die Kartenmarke und die Nachricht von Nexi. Die Transaktions-ID ist der Transaktionscode von Nexi.

Wartend (autorisiert): Verzögerte Erfassung ist gewählt und die Zahlung ist nur autorisiert. Erfassen Sie sie mit der Bestellaktion Capture Nexi XPay payment.

Wartend (ausstehend): Nexi hat die Zahlung als ausstehende Bestätigung gemeldet. Die Bestellung wird durch das Endergebnis aktualisiert.

Wartend nach Zahlung: Betrag oder Währung von Nexi stimmten nicht mit der Bestellung überein (die Bestellung wird nicht als bezahlt markiert), oder eine erfolgreiche Zahlung kam für eine bereits stornierte Bestellung an. Die Bestellnotiz erklärt es. Prüfen Sie die Zahlung im Back-Office von Nexi XPay und verarbeiten oder erstatten Sie die Bestellung.

Fehlgeschlagen: Der letzte Zahlungsversuch wurde abgelehnt, abgebrochen oder endete mit einem Fehler. Der Kunde kann erneut zahlen.

Eine bezahlte Bestellung wird durch eine spätere Fehlzahlung nie herabgestuft. Kommt eine weitere erfolgreiche Zahlung für eine bereits bezahlte Bestellung an, fordert eine Notiz Sie auf, sie im Back-Office von Nexi XPay zu erstatten, falls es ein Duplikat ist.

Verzögerte Erfassung

Öffnen Sie für eine autorisierte Bestellung auf Wartend die Bestellung, wählen Sie Capture Nexi XPay payment bei den Bestellaktionen und klicken Sie auf den Pfeil. Das Plugin erfasst den autorisierten Betrag in der Umgebung der Zahlung und markiert die Bestellung mit dem Status aus Order Status After Payment als bezahlt. Schlägt die Erfassung fehl, wird der Fehler auf dem Bestellbildschirm angezeigt und in den Bestellnotizen ergänzt, und die Bestellung bleibt auf Wartend.

Erstattungen

Erstattungen werden nicht aus WooCommerce ausgeführt, daher gibt es keine Schaltfläche Refund via. Führen Sie die Erstattung im Back-Office von Nexi XPay durch und erfassen Sie sie anschließend manuell in WooCommerce.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Nexi XPay. 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 aktiv 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 für eine 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 Nexi XPay Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde Diese Zahlungsart ist nicht verfügbar. Bitte wählen Sie eine andere. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert als (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und verzögerte Zahlungen können weiterhin erfasst werden.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Nexi XPay erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktuelle Modus beide Zugangsdaten hat (Test Alias und Test MAC Key im Testmodus, Live Alias und Live MAC Key im Live-Modus) und die Shop- oder Bestellwährung EUR ist. Die Einstellungsseite zeigt in diesen Fällen eine Warnung.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt auf Zahlung ausstehend: Weder die Benachrichtigung noch die Rückkehr des Kunden wurde akzeptiert. Prüfen Sie, ob der Shop aus dem Internet erreichbar ist, ob MAC-Schlüssel und Alias zur Umgebung (Test oder Live) der Zahlung passen, und aktivieren Sie Debug Log, um unter WooCommerce > Status > Logs, Quelle wcp_nexi_gateway, zu sehen, was Nexi gesendet hat.

Die Benachrichtigung antwortet mit invalid_mac oder invalid_alias: MAC-Schlüssel oder Alias in den Einstellungen passen nicht zu dem Terminal, das das Ergebnis gesendet hat. Kopieren Sie sie erneut aus dem Testbereich oder dem Back-Office von Nexi.

Die Benachrichtigung antwortet mit unknown_transaction: Der Transaktionscode wurde von diesem Shop für diese Bestellung nicht ausgestellt. Das Ergebnis wird ignoriert.

Die Benachrichtigung antwortet mit not_configured oder busy: Alias oder MAC-Schlüssel der Umgebung der Zahlung ist leer, oder eine andere Anfrage aktualisierte gerade die Bestellung. Nexi wiederholt die Benachrichtigung.

Die Bestellung ist nach der Zahlung auf Wartend: Lesen Sie die Bestellnotiz. Verzögerte Erfassung ist gewählt (erfassen Sie die Zahlung mit der Bestellaktion), Betrag oder Währung stimmten nicht überein, eine Zahlung kam für eine stornierte Bestellung an, die Zahlung ist bei Nexi ausstehend oder Wartend ist als Status nach Zahlung gewählt.

Capture Nexi XPay payment fehlt oder schlägt fehl: Die Aktion wird nur für Nexi-Bestellungen angezeigt, die als autorisiert auf Wartend mit verzögerter Erfassung stehen. Schlägt sie fehl, lesen Sie den Fehler in den Bestellnotizen; die Erfassung verwendet die Schlüssel der Umgebung, in der die Zahlung getätigt wurde.

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 Website-Adresse 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 Gateway-Einstellungen und die Protokolle werden nur entfernt, wenn Delete Data on Uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Nexi und XPay sind Marken ihrer jeweiligen Inhaber. Dieses Plugin ist nicht mit Nexi verbunden und wird von Nexi nicht unterstützt.