VibeFox Nexi XPay for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.
Währung: Die Warenkorbwä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 Alias (Terminal-ID) und MAC-Schlüssel Ihres Terminals. Test- und Live-Zugangsdaten sind getrennt: Testdaten erhalten Sie im Testbereich von Nexi XPay oder im Entwicklerportal (developer.nexi.it), Live-Daten in Ihrem Nexi-XPay-Back-Office, nachdem das Händlerkonto freigeschaltet wurde. Im Back-Office von Nexi muss nichts eingerichtet werden: Die Benachrichtigungsadresse wird bei jeder Zahlung übermittelt.
Öffentliche Website: Die Benachrichtigungs-URL muss aus dem Internet erreichbar sein, ohne Basisauthentifizierung oder Firewall-Regel, die Nexi blockiert. Der Wartungsmodus Ihres Shops blockiert sie nicht. Kann die Benachrichtigung den Shop nicht erreichen, wird die Zahlung trotzdem durch die signierte Rückkehr des Kunden bestätigt.
VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.
Installation
1. Gehen Sie im Back-Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.
2. Klicken Sie nach Abschluss des Uploads auf Configure, oder suchen Sie später VibeFox Nexi XPay Gateway in der Modulliste und klicken Sie auf Configure.
3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Lassen Sie Test Mode eingeschaltet und geben Sie Test-Alias und Test-MAC-Schlüssel ein (siehe Konfiguration).
5. Schalten Sie Enable/Disable ein, klicken Sie auf Save und legen Sie eine Testbestellung an. Wenn alles funktioniert, geben Sie Live-Alias und Live-MAC-Schlüssel ein und schalten Sie Test Mode aus.
Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Nexi XPay payment und Nexi XPay payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken. Ein Land, das nach der Installation des Moduls im Shop aktiviert wird, muss dort ebenfalls angehakt werden.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Test mode is on: payments go to the Nexi XPay test environment, no real money is charged., solange der Testmodus eingeschaltet ist. Sie erhalten eine Warnung, wenn die Zahlungsart aktiviert ist, aber Alias oder MAC-Schlüssel des aktuellen Modus fehlen, oder wenn die Standardwährung des Shops nicht EUR ist. In diesen Fällen wird die Zahlungsart an der Kasse ausgeblendet. Leerzeichen und Zeilenumbrüche um eingefügte Werte werden beim Speichern entfernt.
Nexi XPay
Enable/Disable: Enable Nexi XPay Gateway schaltet die Zahlungsart ein oder aus. Standard: off.
Title: der Titel der Zahlungsart, der dem Kunden an der Kasse angezeigt wird. Er ist zugleich der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Credit Card (Nexi). Im Testmodus fügen Kasse und Bestellung (TEST MODE) dem Titel hinzu.
Description: die Beschreibung der Zahlungsart, die dem Kunden an der Kasse angezeigt wird. 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 Test-MAC-Schlüssel erhalten Sie im Testbereich von Nexi XPay oder im Entwicklerportal (developer.nexi.it).
Test Mode: verwendet die Testumgebung von Nexi XPay und die Testzugangsdaten. Schalten Sie dies aus, um echte Zahlungen mit den Live-Zugangsdaten anzunehmen. Standard: on.
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 Live-MAC-Schlüssel werden in Ihrem Nexi-XPay-Back-Office (ecommerce.nexi.it) angezeigt, nachdem Ihr Händlerkonto freigeschaltet wurde.
Live Alias: der Alias (Terminal-ID) Ihres Nexi-XPay-Live-Terminals.
Live MAC Key: der MAC-Berechnungsschlüssel Ihres Nexi-XPay-Live-Terminals.
Gespeicherte MAC-Schlüssel 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.
Gespeicherte Geheimnisse entfernen: Haken Sie Test MAC Key oder Live MAC Key an und klicken Sie auf Save, um einen gespeicherten Schlüssel zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Zahlung
Notification URL: wird zur Information angezeigt. Sie wird bei jeder Zahlung an Nexi übermittelt, daher muss im Nexi-Back-Office nichts konfiguriert werden. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, eventuell mit einem Sprachcode wie /it/, und mit der Warenkorbnummer am Ende. Nexi sendet das Zahlungsergebnis Server-zu-Server an diese URL und übergibt es außerdem mit der Rückkehr des Kunden. Beide sind gleich signiert und werden mit dem MAC-Schlüssel der Umgebung, in der die Zahlung erfolgte, dem Alias dieser Umgebung und dem für diesen Warenkorb ausgestellten Transaktionscode geprüft. Ergebnisse, die die Prüfung nicht bestehen, werden abgelehnt und ändern nichts.
Erfassung: wann das Geld eingezogen wird.
Order Status After Payment: der Status der Bestellung nach einer erfolgreichen Zahlung.
Erweitert
Debug Log: protokolliert Zahlungsereignisse in logs/nexi_ip_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. MAC-Schlüssel, MACs, 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 ausgeschaltet ist. Standard: off.
Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.
Delete Data on Uninstall: wenn eingeschaltet, entfernt die Deinstallation des Moduls alle Moduleinstellungen und das Protokoll. Die Nexi-XPay-Zahlungsdaten der Bestellungen und die Bestellstatus bleiben erhalten. Standard: off.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit Card (Nexi)) und bestätigt. Die nächste Seite zeigt Redirecting to Nexi XPay for payment... und leitet den Kunden automatisch zur Nexi-XPay-Seite weiter, mit einer Schaltfläche Pay Now als Alternative. Die Zahlung wird in EUR für die Warenkorbsumme gesendet, mit einem neuen Transaktionscode, der E-Mail-Adresse des Kunden, der Beschreibung Cart, der Warenkorbnummer und dem Namen Ihres Shops. Die Nexi-Seite öffnet sich in der Warenkorbsprache, wenn diese Italienisch, Englisch, Spanisch, Französisch, Deutsch, Japanisch, Chinesisch, Arabisch, Russisch oder Portugiesisch ist, andernfalls auf Englisch. Zu diesem Zeitpunkt existiert noch keine Bestellung.
Der Kunde zahlt und kehrt in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn ein geprüftes Nexi-Ergebnis mit genau dem Warenkorbbetrag und der Warenkorbwährung vorliegt: aus der Server-zu-Server-Benachrichtigung oder der signierten Rückkehr des Kunden, je nachdem, was zuerst eintrifft. Danach wird die Bestellung angelegt und der Kunde sieht die übliche Bestellbestätigungsseite mit Your Nexi XPay payment has been received. Meldet Nexi die Zahlung als ausstehend, zeigt die Seite Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Bei einer Bestellung auf Wartend (verzögerte Erfassung oder manuelle Prüfung) zeigt sie We have received your Nexi XPay payment authorization. Your order will be processed shortly. Schlägt eine ausstehende Zahlung später fehl, zeigt die Seite The payment was not completed. Please contact us.
Wenn das Ergebnis bei der Rückkehr des Kunden noch nicht verarbeitet ist, erscheint eine Seite mit We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. und einer Schaltfläche Check again. Die Benachrichtigung legt die Bestellung an, sobald sie eintrifft.
Wird die Zahlung abgelehnt oder bricht der Kunde auf der Nexi-Seite ab, kehrt er zur Kasse zurück und sieht eine dieser Meldungen: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. oder We could not confirm the payment. If your card was charged, please contact us before paying again. Es wird keine Bestellung angelegt und der Warenkorb bleibt erhalten, sodass der Kunde erneut zahlen kann. Hat der Warenkorb bereits eine Bestellung (zum Beispiel wurde in einem anderen Tab bezahlt), gelangt der Kunde zur Bestellbestätigung statt zu einer neuen Zahlung.
Ist das Modul für den aktuellen Modus nicht eingerichtet, sieht der Kunde This payment method is not available right now. Please choose another payment method.
Die Benachrichtigung funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.
Das Modul nimmt Zahlungen nur auf der Nexi-XPay-Seite an. Es gibt keine Erstattungen aus PrestaShop, keine gespeicherten Karten oder OneClick, keine Abonnements oder wiederkehrenden Zahlungen, kein Pay-By-Link, keine eingebetteten XPay-Build-Felder und keine in PrestaShop ausgewählten Zahlungsmethoden: Die Nexi-Seite zeigt die auf Ihrem Terminal aktivierten Methoden.
Bestellungen und Erstattungen
Bestellstatus
Noch keine Bestellung: Der Kunde wurde zu Nexi weitergeleitet und hat nicht bezahlt, abgebrochen oder wurde abgelehnt, oder Nexi hat die Zahlung noch nicht bestätigt. Nur der Warenkorb existiert.
Payment accepted, Delivered or Nexi XPay payment on hold: Nexi hat die Zahlung bestätigt. Der Status folgt Order Status After Payment. Die Zahlung wird mit dem Nexi-Transaktionscode als Transaktions-ID erfasst, und eine Notiz zeigt den Autorisierungscode, den Transaktionscode, die Kartenmarke und die Nachricht von Nexi.
Nexi XPay payment on hold (authorized): Verzögerte Erfassung ist gewählt und die Zahlung ist nur autorisiert. Erfassen Sie sie mit Capture Nexi XPay payment auf der Bestellseite.
Awaiting Nexi XPay payment: Nexi hat die Zahlung als ausstehende Bestätigung gemeldet. Die Bestellung wird durch das endgültige Ergebnis aktualisiert.
Nexi XPay payment on hold after payment: Betrag oder Währung von Nexi stimmten nicht mit dem Warenkorb überein (die Bestellung wird nicht als bezahlt markiert), oder eine erfolgreiche Zahlung kam für eine bereits stornierte Bestellung an. Die Notiz erklärt es. Prüfen Sie die Zahlung im Nexi-XPay-Back-Office und bearbeiten Sie die Bestellung oder erstatten Sie sie.
Zahlungsfehler: Eine ausstehende Zahlung ist fehlgeschlagen. Derselbe Warenkorb kann nicht erneut bezahlt werden, daher muss der Kunde eine neue Bestellung aufgeben.
Eine bezahlte Bestellung wird durch einen späteren Fehler nie herabgestuft. Trifft eine weitere erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, bittet eine Notiz Sie, sie im Nexi-XPay-Back-Office zu erstatten, falls es sich um ein Duplikat handelt.
Nexi-XPay-Zahlungsblock
Die Bestellseite zeigt einen Block Nexi XPay payment mit dem Transaktionscode (codTrans), dem Status und dem Ergebnis von Nexi, dem Erfassungsmodus, dem an Nexi gesendeten und dem empfangenen Betrag, dem Autorisierungscode, der Kartenmarke, der Nachricht von Nexi und dem Datum, einem Abzeichen Test environment für Testzahlungen und den Nexi XPay notes der Bestellung.
Verzögerte Erfassung
Klicken Sie bei einer autorisierten, wartenden Bestellung im Block auf Capture Nexi XPay payment (die Schaltfläche zeigt den Betrag) und bestätigen Sie die Frage Capture the authorized amount through Nexi XPay? Dazu benötigen Sie das Recht, Bestellungen zu bearbeiten. Das Modul erfasst den autorisierten Betrag in der Umgebung der Zahlung mit deren Schlüsseln, speichert die Zahlung und setzt den Status gemäß Order Status After Payment. Schlägt die Erfassung fehl, zeigt der Block den Fehler, eine Notiz wird hinzugefügt und die Bestellung bleibt auf Wartend. Eine zweite Erfassung derselben Zahlung wird abgelehnt.
Erstattungen
Erstattungen werden nicht aus PrestaShop vorgenommen, daher gibt es keine Erstattungsschaltfläche für Nexi XPay. Nehmen Sie die Erstattung im Nexi-XPay-Back-Office vor und erfassen Sie sie anschließend manuell in PrestaShop. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über Nexi zurück.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Nexi XPay Gateway ist der erste Block auf Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-nexi und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).
Wird der Schlüssel nicht akzeptiert, nennt 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. Nach einer Änderung der Shop-Adresse oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.
Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch in einem Multistore-Aufbau. Wenn Sie den Schlüssel aus dem Shop entfernen, wird dessen 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 This payment method is not available. Please choose another one. Die Kundenseite von PrestaShop weiß nicht, dass Sie im Back Office angemeldet sind; daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und autorisierte Zahlungen können weiterhin erfasst werden.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird bei der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
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 Warenkorbwährung EUR ist. Die Einstellungsseite zeigt in diesen Fällen eine Warnung. Prüfen Sie unter Payment > Preferences, ob das Modul für EUR, das Land des Kunden und die Kundengruppe erlaubt ist.
Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: 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 schalten Sie Debug Log ein, um im Feld Log auf der Modulseite zu sehen, was Nexi gesendet hat.
Die Benachrichtigung antwortet invalid_mac oder invalid_alias: MAC-Schlüssel oder Alias in den Einstellungen stimmen nicht mit dem Terminal überein, das das Ergebnis gesendet hat. Kopieren Sie sie erneut aus dem Nexi-Testbereich oder dem Back-Office.
Die Benachrichtigung antwortet unknown_transaction: Der Transaktionscode wurde von diesem Shop für diesen Warenkorb nicht ausgestellt. Das Ergebnis wird ignoriert.
Die Benachrichtigung antwortet not_configured oder busy: Alias oder MAC-Schlüssel der Umgebung der Zahlung sind leer, oder die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert, oder die Bestellung konnte nicht angelegt werden (etwa weil das Modul deaktiviert ist). Nexi wiederholt die Benachrichtigung.
Die Benachrichtigungs-URL zeigt im Browser method_not_allowed: Das ist normal. Die URL akzeptiert nur Anfragen von Nexi.
Bestellung ist Nexi XPay payment on hold after payment: Lesen Sie die Nexi XPay notes im Bestellblock. Verzögerte Erfassung ist gewählt (erfassen Sie die Zahlung mit der Schaltfläche), Betrag oder Währung stimmten nicht überein, eine Zahlung kam für eine stornierte Bestellung an, oder Nexi XPay payment on hold ist als Status nach der Zahlung gewählt.
Capture Nexi XPay payment fehlt oder schlägt fehl: Die Schaltfläche wird nur bei Nexi-XPay-Bestellungen angezeigt, die als autorisiert mit verzögerter Erfassung auf Wartend stehen, und nur für Mitarbeiter, die Bestellungen bearbeiten dürfen. Sind Alias oder MAC-Schlüssel der Umgebung der Zahlung leer, teilt der Block dies mit. Schlägt die Erfassung fehl, lesen Sie den Fehler im Block und in den Notizen, zum Beispiel Nexi XPay refused the capture mit dem Code und der Nachricht von Nexi.
Testzahlungen bestätigen keine Live-Zahlung: Jede Zahlung wird mit den Schlüsseln der Umgebung geprüft, in der sie gestartet wurde. Stellen Sie Test Mode auf den gewünschten Modus und verwenden Sie Alias und MAC-Schlüssel dieses Modus.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Nexi XPay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall eingeschaltet, werden die Moduleinstellungen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Nexi-XPay-Zahlungsdaten der Bestellungen und die Bestellstatus Awaiting Nexi XPay payment und Nexi XPay payment on hold bleiben immer erhalten, sodass autorisierte Zahlungen auch nach einer Neuinstallation erfasst werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Nexi und XPay sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist weder mit Nexi verbunden noch wird es von Nexi unterstützt.