VibeFox Nets Nexi for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer mit der cURL-Erweiterung. Das Modul lässt sich auf älteren PHP-Versionen oder ohne cURL nicht installieren.
Nets-Konto: Sie benötigen die geheimen Schlüssel Ihres Nets-Easy-Kontos (Test und Live). Nur die geheimen Schlüssel werden verwendet. Die Checkout-Schlüssel werden nicht benötigt, weil Kunden auf der gehosteten Zahlungsseite von Nets bezahlen.
Währungen und Zahlungsarten: Das Modul beschränkt Währungen und Länder nicht selbst. Verwenden Sie die in Ihrem Nets-Konto aktivierten Währungen; eine nicht unterstützte Währung meldet Nets beim Anlegen der Zahlung. Welche Zahlungsarten der Kunde sieht, hängt von Ihrem Nets-Vertrag, Land und Währung ab.
HTTPS für Webhooks: Nets ruft nur öffentliche HTTPS-Adressen mit höchstens 256 Zeichen ohne „&“ auf. Ihr Shop benötigt daher HTTPS und suchmaschinenfreundliche URLs, um Webhooks zu empfangen. Ohne Webhooks wird die Zahlung trotzdem bestätigt, sobald der Kunde in den Shop zurückkehrt oder mit der Statusprüfung auf der Bestellseite.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.
Installation
1. Im Back Office gehen Sie zu Modules > Module Manager und klicken auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Nets Nexi Gateway später 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. Kopieren Sie den geheimen Testschlüssel aus dem Nets-Easy-Testportal und fügen Sie ihn in Test Secret Key ein (siehe Konfiguration).
5. Aktivieren Sie Enable/Disable, lassen Sie Test Mode eingeschaltet, klicken Sie auf Save und legen Sie eine Testbestellung an. Geben Sie danach den Live-Schlüssel ein und schalten Sie Test Mode aus.
Bei der Installation legt das Modul den Bestellstatus Nets payment on hold an. PrestaShop verknüpft ein neues Zahlungsmodul nur mit den Ländern, die zum Zeitpunkt der Installation aktiv sind. Prüfen Sie die Währungen, Länder und Kundengruppen des Moduls unter Payment > Preferences.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern warnt die Seite, wenn der geheime Schlüssel des gewählten Modus fehlt, zum Beispiel mit Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., und zeigt Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged., solange der Testmodus eingeschaltet ist.
Nets Nexi (nordische Länder)
Der Abschnittstitel zeigt TEST oder LIVE für den gewählten Modus.
Enable/Disable: Enable Nets Nexi Gateway schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Titel der Zahlungsart, der dem Kunden beim Checkout angezeigt wird. Er ist zugleich der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Nets Easy. Pflichtfeld: Ein leerer Titel erzeugt den Fehler Enter a title for the payment method., und nichts wird gespeichert.
Description: die Beschreibung der Zahlungsart, die dem Kunden beim Checkout angezeigt wird. Standard: Pay securely with Nets Easy.
API-Schlüssel
Kopieren Sie die geheimen Schlüssel aus dem Nets-Easy-Portal unter Company > Integration: das Testportal (test.portal.dibspayment.eu) für den Testschlüssel und das Live-Portal (portal.dibspayment.eu) für den Live-Schlüssel. Die Checkout-Schlüssel werden nicht benötigt.
Test Mode: Der Testmodus verwendet test.api.dibspayment.eu mit dem geheimen Testschlüssel; der Live-Modus verwendet api.dibspayment.eu mit dem geheimen Live-Schlüssel. Erstattungen und Erfassungen einer Bestellung verwenden immer die Umgebung, in der sie bezahlt wurde. Standard: ein. Solange er eingeschaltet ist, sehen Kunden Test mode: no real money will be charged. unter der Zahlungsart.
Test Secret Key: Ihr geheimer API-Schlüssel für die Nets-Testumgebung.
Live Secret Key: Ihr geheimer API-Schlüssel für die Nets-Live-Umgebung.
Gespeicherte 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.
Clear saved secrets: Markieren Sie einen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Zahlung
Webhooks: Nets-Benachrichtigungen (Webhooks) werden bei jeder Zahlung automatisch registriert. Im Nets-Portal ist nichts einzurichten. Der Abschnitt zeigt die Adresse, an die sie gesendet werden. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_nets_nexi_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Ist die Adresse keine öffentliche HTTPS-Adresse, warnt Sie der Abschnitt, dass der Shop keine Webhooks empfängt; die Zahlungen werden dann bestätigt, wenn der Kunde in den Shop zurückkehrt, oder mit Nets: check payment status and capture auf der Bestellseite. Folgende Ereignisse werden registriert:
Jeder Webhook muss das zufällige Geheimnis enthalten, das das Modul für diese Zahlung erzeugt hat. Webhooks ohne das richtige Geheimnis werden abgelehnt. Der Webhook teilt dem Modul nur mit, welche Zahlung sich geändert hat: Die Zahlung selbst wird immer mit dem geheimen Schlüssel der Umgebung, in der sie erfolgt ist, über die Nets-API abgerufen. Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.
Order Status After Payment: der Status der Bestellung, nachdem Nets die Zahlung bestätigt und abgebucht hat.
Erweitert
Debug log: protokolliert API-Aufrufe und Zahlungsstatusänderungen in logs/nng_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert. Schlüssel und Kundendaten werden nicht protokolliert. Standard: aus.
Log: zeigt die Größe und die letzten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.
Delete Data on Uninstall: löscht die Moduleinstellungen und Protokolle bei der Deinstallation. Zahlungsdaten, die in Bestellungen gespeichert sind, bleiben immer erhalten. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Nets Easy) und bestätigt. Das Modul legt eine Nets-Zahlung über die Summe des Warenkorbs in der Warenkorbwährung an, mit den Produkten, dem Versand, der Geschenkverpackung und den Rabatten als Bestellpositionen, und leitet den Kunden auf die gehostete Zahlungsseite von Nets weiter. Die Zahlungsreferenz bei Nets ist die Warenkorbnummer. E-Mail-Adresse, Name, Anschrift und Telefonnummer des Kunden werden an Nets übergeben, sofern Nets deren Format akzeptiert. Die AGB-Seite Ihrer Kasse wird auf der Nets-Seite verlinkt (ist keine festgelegt, die Startseite des Shops). Zu diesem Zeitpunkt existiert noch keine Bestellung.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Nets die Zahlung bestätigt: Das Modul liest die Zahlung über die Nets-API, vergleicht den reservierten Betrag und die Währung mit dem Warenkorb, bucht die Reservierung ab und legt erst dann die Bestellung an. Dies geschieht beim Webhook oder bei der Rückkehr des Kunden, je nachdem, was zuerst eintritt. Der Kunde sieht dann die übliche Bestellbestätigungsseite. Konnte die Zahlung noch nicht bestätigt werden (Nets war nicht erreichbar oder eine andere Anfrage bestätigte sie gerade), zeigt eine Seite Payment confirmation den Text Your Nets payment is being confirmed. Your order will be created as soon as it is confirmed — please do not pay again. mit den Schaltflächen Check again und Back to checkout.
Bricht der Kunde auf der Nets-Seite ab, kehrt er zur Kasse zurück, mit The Nets payment was cancelled. You can try again or choose another payment method. Wurde nichts bezahlt, lautet die Meldung The payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Bei einem neuen Versuch prüft das Modul zuerst die vorherige Zahlung; ist sie bereits bezahlt, wird die Bestellung statt einer neuen Zahlung angelegt. Andernfalls wird die vorherige Nets-Sitzung geschlossen, bevor eine neue beginnt.
Kann Nets die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. oder The payment service could not be reached. Please try again in a moment. Eine Warenkorbsumme von null führt zu The order total must be greater than zero to pay with Nets. Die Details werden im Protokoll festgehalten.
Das Modul nutzt nur die gehostete Zahlungsseite. Es hat keinen eingebetteten Nets-Checkout auf der Seite, keine Abonnements oder wiederkehrenden Zahlungen, keine gespeicherten Karten, keine Rechnungsgebühren, keinen Modus „nur autorisieren“ und keine Teilerfassungen pro Versand.
Bestellungen und Erstattungen
Bestellstatus
No order yet: Der Kunde wurde zu Nets geschickt und hat nicht bezahlt, oder die Zahlung ist noch nicht bestätigt. Es existiert nur der Warenkorb.
Payment accepted or Delivered: Nets hat die Zahlung bestätigt und abgebucht. Der Status folgt Order Status After Payment. Die Zahlung wird mit der Nets-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungs-ID, die Abbuchungs-ID und die Zahlungsart.
Nets payment on hold: Betrag oder Währung bei Nets weichen vom Warenkorb ab (nicht erfasst), die Erfassung wurde abgelehnt, oder der Kunde hat gezahlt, nachdem die Bestellung storniert worden war (reserviert, nicht erfasst). Die Notiz erklärt es. Nichts wird automatisch erfasst. Nach Prüfung der Bestellung erfassen Sie mit Nets: check payment status and capture oder stornieren die Reservierung im Nets-Portal.
Canceled: Die Reservierung einer wartenden Bestellung wurde storniert, zum Beispiel im Nets-Portal.
Refunded: Die Zahlung wurde über das Modul vollständig erstattet.
Wiederholte Webhooks und Seitenneuladen belasten nie doppelt und fügen keine doppelten Notizen hinzu; eine bezahlte Bestellung wird durch Nets-Ereignisse nie erneut verändert. Wird ein alter Zahlungslink für eine bereits bezahlte Bestellung abgeschlossen, wird die zweite Reservierung automatisch freigegeben; wurde sie bereits abgebucht, fordert eine Notiz Sie auf, sie im Nets-Portal zu erstatten.
Nets-Easy-Zahlungsblock
Die Bestellseite zeigt einen Block Nets Easy payment mit der Zahlungs-ID, der Abbuchungs-ID, der Umgebung (mit dem Abzeichen Test environment bei Testzahlungen), dem Status, den bei Nets reservierten und abgebuchten Beträgen, der Bestellsumme und dem erstatteten Betrag, dem Erstattungsverlauf und den Nets notes der Bestellung. Die Schaltflächen des Blocks funktionieren für alle Mitarbeiter, die Bestellungen bearbeiten dürfen; der Zugriff auf die Modulseiten ist nicht nötig.
Nets: check payment status and capture: wird bei Bestellungen angezeigt, die noch nicht bezahlt sind. Die Zahlung wird bei Nets abgerufen und eine zur Bestellung passende Reservierung erfasst, auch nach einer fehlgeschlagenen Erfassung oder nachdem Sie eine wartende Bestellung geprüft haben. Ändert sich nichts, erklärt eine Notiz den Grund, zum Beispiel dass der Kunde die Zahlung noch nicht abgeschlossen hat.
Erstattungen
Geben Sie im Block Nets Easy payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Nets. Bestätigen Sie die Frage Refund this amount through Nets? This cannot be undone. Vollständige und teilweise Erstattungen sind möglich, sobald die Zahlung abgebucht ist; eine nur reservierte Zahlung kann im Nets-Portal storniert werden. Die Erstattung erfolgt auf die Abbuchung der Bestellung in der Umgebung, in der bezahlt wurde. Lehnt Nets die Erstattung ab, zeigt der Block den Fehler und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Nets-Erstattungs-ID hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über Nets zurück. Erstattungen, die im Nets-Portal vorgenommen werden, werden nicht synchronisiert; aktualisieren Sie die Bestellung bei Bedarf manuell.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Nets Nexi Gateway ist der erste Block auf Modules > Module Manager > VibeFox Nets Nexi 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-nets-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 Nets 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 Erstattungen funktionieren.
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
Nets Nexi erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der gewählte Modus einen geheimen Schlüssel hat: Test Secret Key im Testmodus, Live Secret Key im Live-Modus. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.
Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: Der Webhook hat Ihren Shop nicht erreicht. Prüfen Sie, ob der Shop HTTPS und suchmaschinenfreundliche URLs verwendet, sodass die Adresse unter Webhooks eine öffentliche HTTPS-Adresse ohne „&“ ist, und ob der geheime Schlüssel der Umgebung der Zahlung eingetragen ist. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.
Der Webhook antwortet Unauthorized: Der Webhook enthielt nicht das Geheimnis dieser Zahlung. Webhooks werden nur mit dem bei der Zahlung registrierten Geheimnis akzeptiert.
Der Webhook antwortet Busy, retry later, Payment lookup failed oder Payment not reserved yet: Eine andere Anfrage bestätigte gerade denselben Warenkorb, die Nets-API war nicht erreichbar, oder die Reservierung war noch nicht sichtbar. Nets wiederholt den Webhook automatisch.
Der Webhook antwortet Order could not be created, retry later: Die Bestellung konnte nicht angelegt werden, zum Beispiel weil das Modul deaktiviert ist. Aktivieren Sie Debug log, um den Grund zu sehen.
Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die Adresse akzeptiert nur Anfragen von Nets.
Der Kunde sieht beim Wählen von Nets einen Fehler: Aktivieren Sie Debug log und sehen Sie im Feld Log auf der Modulseite nach. This payment method is temporarily unavailable. Please choose another payment method. bedeutet meist einen falschen oder fehlenden geheimen Schlüssel. Eine abgelehnte Währung meldet Nets im Protokoll.
Die Bestellung ist nach der Zahlung Nets payment on hold: Lesen Sie die Nets notes im Block. Wurde die Erfassung abgelehnt, versuchen Sie es erneut mit Nets: check payment status and capture oder buchen Sie den Betrag im Nets-Portal ab. Weichen Betrag oder Währung ab, prüfen Sie die Zahlung im Nets-Portal. Hat der Kunde nach der Stornierung gezahlt, prüfen Sie die Bestellung und erfassen oder stornieren Sie die Reservierung.
Refund via Nets fehlt oder schlägt fehl: Erstattungen sind nur möglich, nachdem die Zahlung abgebucht wurde; der Block zeigt dann eine Abbuchungs-ID. Eine Erstattung verwendet den geheimen Schlüssel der Umgebung, in der die Bestellung bezahlt wurde; dieser Schlüssel muss gesetzt sein, sonst nennt der Block den fehlenden Umgebungsschlüssel.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Nets Nexi 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 Nets-Zahlungsdaten der Bestellungen (Zahlungen, Abbuchungen und Erstattungen) und der Bestellstatus Nets payment on hold bleiben immer erhalten, sodass bereits bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Nets, Nets Easy und Nexi sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist weder mit Nets noch mit Nexi verbunden und wird von keinem der beiden unterstützt.