VibeFox Netopia for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer mit den Erweiterungen OpenSSL, DOM und SimpleXML. Ohne sie lässt sich das Modul nicht installieren.

Währung: Die Warenkorbwährung muss RON, EUR, USD oder GBP sein. EUR, USD und GBP müssen in Ihrem Netopia-Konto aktiviert sein. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.

Netopia-Konto: Sie benötigen ein Netopia-Payments-Verkäuferkonto mit einem Verkaufspunkt. In dessen technischen Einstellungen brauchen Sie die Kontosignatur und für jede Umgebung, die Sie nutzen (Sandbox und Live), das öffentliche Zertifikat (.cer) und den privaten Schlüssel (.key). Auf Netopia-Seite muss nichts eingerichtet werden: Die IPN-Adresse wird mit jeder Zahlungsanfrage übermittelt.

Öffentlicher Shop: Die IPN-(Bestätigungs-)URL muss aus dem Internet erreichbar sein, nicht hinter einer Anmeldung oder Basisauthentifizierung. Bestellungen werden nur durch die Netopia-IPN angelegt.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder finden Sie VibeFox Netopia Gateway später in der Modulliste und klicken Sie dort 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. Öffnen Sie im Netopia-Admin Ihren Verkaufspunkt, kopieren Sie die Kontosignatur und laden Sie das Zertifikat und den privaten Schlüssel der Sandbox- und der Live-Umgebung herunter. Fügen Sie die Signatur und den vollständigen Dateiinhalt in die Einstellungen ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Sandbox-Modus und schalten Sie danach Test mode aus, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting Netopia payment und Netopia payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können es unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Netopia Gateway > Configure. Jeder Abschnitt hat seinen eigenen Button Save, der die gesamte Seite speichert. Oberhalb der Felder warnt Sie die Seite, wenn Kontosignatur, Zertifikat oder privater Schlüssel der aktiven Umgebung fehlen (die Zahlungsart wird dann an der Kasse ausgeblendet). Solange der Testmodus aktiv ist, zeigt sie Test mode is on: payments go to the Netopia sandbox and no real money is charged. an. Beim Speichern wird ein ungültiges Zertifikat oder ein ungültiger privater Schlüssel mit einer Fehlermeldung abgelehnt, und der bisherige Wert bleibt erhalten; die übrigen Felder werden gespeichert.

IPN (confirm) URL

Sie wird oben auf der Seite schreibgeschützt angezeigt. Bei aktivierten Freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_netopia_gateway/notify, gegebenenfalls mit einem Sprachcode wie /en/. Sie wird mit jeder Zahlungsanfrage als Bestätigungs-URL übermittelt, Sie müssen sie daher nicht im Netopia-Admin eintragen. Netopia sendet die IPN an diese URL. Das Modul entschlüsselt sie mit dem privaten Schlüssel der Umgebung, in der die Zahlung gestartet wurde, und prüft Ihre Kontosignatur und die Zahlungsanfrage. Netopia meldet folgende Aktionen:

Eine Benachrichtigung mit einem Netopia-Fehlercode (zum Beispiel einer abgelehnten Karte) setzt eine wartende Bestellung auf Payment error; ohne Bestellung kann der Kunde erneut zahlen. Benachrichtigungen, die sich nicht entschlüsseln lassen, eine andere Kontosignatur tragen oder auf keine Zahlungsanfrage dieses Warenkorbs antworten, werden abgelehnt und ändern nichts.

Kasse

Enable/Disable: Enable Netopia Payments schaltet die Zahlungsart ein oder aus. Standard: off.

Title: der Titel der Zahlungsart, der an der Kasse angezeigt wird. Er ist zugleich der Name der Zahlungsart, der in der Bestellung gespeichert wird. Standard: Card Payment (Netopia).

Description: die Beschreibung der Zahlungsart, die an der Kasse angezeigt wird. Standard: Pay securely with your credit or debit card via Netopia.

Netopia-Konto

Im Netopia-Admin gehen Sie zu Seller accounts > your point of sale > Technical settings: Kopieren Sie die Kontosignatur und laden Sie das öffentliche Zertifikat (.cer) und den privaten Schlüssel (.key) jeder Umgebung herunter. Öffnen Sie die Dateien in einem Texteditor und fügen Sie ihren vollständigen Inhalt ein, einschließlich der BEGIN/END-Zeilen.

Account signature: die Kontosignatur des Verkäuferkontos (Format XXXX-XXXX-XXXX-XXXX-XXXX), für Sandbox und Live dieselbe.

Test mode: nutzt die Netopia-Sandbox (sandboxsecure.mobilpay.ro) und die Sandbox-Schlüssel. Standard: on. Schalten Sie ihn aus, um mit den Live-Schlüsseln echte Zahlungen anzunehmen.

Sandbox public certificate (.cer): der Inhalt der Datei mit dem öffentlichen Sandbox-Zertifikat. Er wird zur Verschlüsselung der Zahlungsanfrage verwendet.

Sandbox private key (.key): der Inhalt der Datei mit dem privaten Sandbox-Schlüssel. Er wird zur Entschlüsselung der IPN verwendet.

Live public certificate (.cer): der Inhalt der Datei mit dem öffentlichen Live-Zertifikat.

Live private key (.key): der Inhalt der Datei mit dem privaten Live-Schlüssel.

Gespeicherte private Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer, und sein Hilfetext beginnt mit A private key is saved. Lassen Sie es leer, um den gespeicherten Schlüssel zu behalten, oder fügen Sie einen neuen Schlüssel ein, um ihn zu ersetzen. Ein leeres Zertifikatsfeld entfernt das Zertifikat.

Gespeicherte private Schlüssel löschen: Markieren Sie einen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Schlüssel.

Bestellungen

Order status after payment: der Status einer bezahlten Bestellung.

Erweitert

Debug log: schreibt Anfragen und die IPN-Verarbeitung in logs/netopia_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Kartendaten, Schlüssel und Kundendaten werden nicht protokolliert. Fehler, zum Beispiel abgelehnte IPNs, 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: entfernt beim Deinstallieren des Moduls die Gateway-Einstellungen, die Netopia-Zahlungsdatensätze des Moduls und das Protokoll. Bestellungen bleiben erhalten. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Card Payment (Netopia)) und bestätigt. Die nächste Seite zeigt Redirecting you to Netopia for secure payment… und leitet den Kunden automatisch zur Netopia-Zahlungsseite weiter; als Alternative stehen die Buttons Proceed to payment und Cancel (zurück zur Kasse) bereit. Die Zahlungsanfrage wird mit Ihrem Netopia-Zertifikat verschlüsselt und enthält die Warenkorbsumme in der Warenkorbwährung, Cart # mit der Warenkorbnummer sowie die Rechnungs- und Lieferkontaktdaten. Im Sandbox-Modus geht die Anfrage an die Netopia-Sandbox. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Der Kunde bezahlt mit Karte auf der Netopia-Seite und kehrt in Ihren Shop zurück. Die Rückkehr selbst legt nie eine Bestellung an und bezahlt auch keine. Die Bestellung wird erst als bezahlt markiert, wenn Netopia dies per IPN bestätigt. Existiert die Bestellung, sieht der Kunde die übliche Bestellbestätigungsseite. Bei einer wartenden Bestellung zeigt sie Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Bei einer Bestellung im Status On hold zeigt sie Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Bei einer stornierten Bestellung zeigt sie The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Bei einer Bestellung mit Zahlungsfehler zeigt sie The payment was declined by Netopia.

Wenn die IPN beim Zurückkehren des Kunden noch nicht eingetroffen ist, zeigt eine Seite Payment confirmation denselben Text „noch nicht bestätigt“ mit den Buttons Check again und Back to checkout. Die Bestellung wird angelegt, sobald die IPN eintrifft.

Hat Netopia eine Stornierung oder Ablehnung gemeldet, bevor eine Bestellung angelegt wurde, kehrt der Kunde zur Kasse zurück, mit The payment was cancelled at Netopia. You can try again or choose another payment method. bzw. The payment was declined by Netopia. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Jeder neue Versuch ist eine neue Zahlungsanfrage; frühere Anfragen zu diesem Warenkorb bleiben gültig, sodass eine verspätete IPN eines früheren Versuchs trotzdem erfasst wird.

Ist das Modul nicht korrekt eingerichtet, bleibt der Kunde an der Kasse mit Netopia gateway is not configured properly. Please contact the store administrator. Weitere Meldungen sind Netopia cannot process payments in mit der Währung, This order has nothing to pay. und Payment encryption failed. Please try again or contact support. Der technische Grund wird im Protokoll festgehalten.

Die IPN funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Das Modul akzeptiert Kartenzahlungen ausschließlich über das Kartenprotokoll Netopia v1. Es bietet keine Erstattungen oder Erfassungen aus PrestaShop, keine gespeicherten Karten oder Ein-Klick-Zahlungen, keine Abonnements, Ratenzahlungen oder andere Zahlungsarten und kein Netopia API v2.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu Netopia weitergeleitet und hat noch nicht bezahlt, oder Netopia hat die IPN noch nicht gesendet. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Netopia hat die Zahlung bestätigt. Der Status folgt Order status after payment. Die Zahlung wird mit der Netopia-Transaktion als Transaktions-ID erfasst, und eine private Notiz zeigt Betrag, maskierte Kartennummer und die Netopia-Transaktion; Sandbox-Zahlungen sind mit [sandbox] gekennzeichnet.

Awaiting Netopia payment: Die Zahlung ist eine Vorautorisierung, die auf Erfassung im Netopia-Admin wartet, oder sie wird bei Netopia geprüft. Noch ist keine Zahlung erfasst. Die Bestellung wechselt in den bezahlten Status, sobald Netopia sie bestätigt.

Netopia payment on hold: Der Rechnungsbetrag oder die Währung weicht vom Warenkorb oder der Bestellung ab, nur ein Teil der Zahlung wurde erfasst, Netopia hat die Zahlung einer stornierten Bestellung oder einer Bestellung mit einer anderen Zahlungsart bestätigt, oder eine Sandbox-(Test-)Zahlung wurde bestätigt, während der Shop im Live-Modus ist (es wurde kein echtes Geld empfangen, daher wird keine Zahlung erfasst). Die Notiz erklärt es. Prüfen Sie die Transaktion im Netopia-Admin und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung dort.

Payment error: Netopia hat für eine wartende Bestellung einen Fehler gemeldet, zum Beispiel eine abgelehnte Karte.

Canceled: Netopia hat die Zahlung einer wartenden Bestellung storniert.

Refunded: Die Zahlung wurde im Netopia-Admin vollständig erstattet.

Späte Benachrichtigungen stufen nie eine bezahlte oder abgeschlossene Bestellung herab. Bestätigt Netopia eine weitere Zahlung für eine bereits bezahlte Bestellung, erinnert eine Notiz Sie daran, das Duplikat im Netopia-Admin zu erstatten.

Netopia-Block

Die Bestellseite zeigt einen Block Netopia Payments mit der Netopia-Transaktion, der Umgebung (Sandbox oder Live), der Zahlungsanfrage, der letzten IPN-Aktion, der maskierten Karte, den Beträgen bezahlt, erstattet und verbleibend sowie der Erstattungshistorie. Der Block ist schreibgeschützt.

Erstattungen

Erstattungen werden nicht aus PrestaShop heraus vorgenommen: Das Kartenprotokoll Netopia v1 hat keinen Erstattungsaufruf. Erstatten Sie die Transaktion im Netopia-Admin. Netopia sendet dann eine Gutschrift-IPN, und das Modul erfasst die Erstattung automatisch in der Bestellung, mit der Notiz Netopia refund processed: und dem Betrag. Eine Teilerstattung behält den Bestellstatus bei; wenn nichts mehr zu erstatten ist, wird die Bestellung auf Refunded gesetzt. Bei EUR-, USD- und GBP-Bestellungen wird der erstattete Betrag, den Netopia in RON meldet, in die Bestellwährung zurückgerechnet. Eine Erstattung wird nie doppelt erfasst und nie für mehr als den verbleibenden Betrag. Meldet Netopia einen Fehler bei der Erstattung, wird nur eine Notiz hinzugefügt.

Das Modul erstellt keine Gutschriften und bucht keine Produkte zurück in den Bestand. Die Standard-Erstattungsbuttons von PrestaShop auf der Bestellseite senden kein Geld über Netopia zurück.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Netopia Gateway ist der erste Block auf Modules > Module Manager > VibeFox Netopia Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in das Feld 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 gültig ist, und Ihre Domain) sowie die Buttons 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: presta-payment-netopia und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Den Schlüssel können nur Mitarbeiter mit der Berechtigung Configure für das Modul ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, zeigt der Block den Grund an, 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 Domainplatz 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 bei einem Multistore-Setup. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Netopia Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der Storefront von PrestaShop erkennt nicht, dass Sie im Back Office angemeldet sind, daher ist die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und im Netopia-Admin vorgenommene Erstattungen werden weiterhin erfasst.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back Office arbeiten: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht erforderlich. Die Deinstallation oder das Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Netopia erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, die aktive Umgebung vollständig ist (Account signature plus Zertifikat und privater Schlüssel der Sandbox im Testmodus bzw. der Live-Umgebung im Live-Modus) und die Warenkorbwährung RON, EUR, USD oder GBP ist. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe zugelassen ist.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: Die IPN hat Ihren Shop nicht erreicht oder wurde abgelehnt. Prüfen Sie, ob die IPN-(Bestätigungs-)URL aus den Einstellungen aus dem Internet erreichbar ist (keine Basisauthentifizierung oder Firewall). Sehen Sie im Feld Log auf der Modulseite nach: Abgelehnte IPNs werden immer protokolliert. Aktivieren Sie Debug log, um jede IPN zu sehen. Die Rückkehr des Kunden allein legt nie eine Bestellung an.

Das Log zeigt failed decrypting data: Der private Schlüssel passt nicht zum Zertifikat, das Netopia verwendet hat. Die IPN wird mit dem gespeicherten privaten Schlüssel jeder Umgebung entschlüsselt. Behalten Sie deshalb den Schlüssel der anderen Umgebung gespeichert, solange deren Zahlungen noch offen sind. Netopia wiederholt die IPN.

Das Log zeigt signature mismatch: Die Account signature unterscheidet sich vom Verkaufspunkt, der die IPN gesendet hat. Kopieren Sie sie erneut aus dem Netopia-Admin.

Das Log zeigt unknown payment request: Die IPN beantwortet keine Zahlungsanfrage, die Ihr Shop für diesen Warenkorb in dieser Umgebung (Sandbox oder Live) gestellt hat. Es wird nichts geändert.

Das Log zeigt gateway not configured: Es ist kein privater Schlüssel oder keine Kontosignatur gespeichert. Netopia wiederholt die IPN, und die Zahlung wird erfasst, sobald die Einstellungen vollständig sind.

Das Log zeigt busy, retry later or processing failed: Der Warenkorb wurde im selben Moment von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Netopia wiederholt die IPN automatisch.

Fehler beim Speichern wegen des Zertifikats oder des privaten Schlüssels: Der eingefügte Text ist kein gültiges Zertifikat und kein gültiger Schlüssel. Fügen Sie den vollständigen Dateiinhalt einschließlich der BEGIN/END-Zeilen ein. Der bisherige Wert wurde beibehalten.

Bestellung ist nach der Zahlung Netopia payment on hold: Lesen Sie die private Notiz der Bestellung (siehe Bestellstatus). Der Betrag oder die Währung wich ab, nur ein Teil wurde erfasst, die Bestellung war storniert, oder eine Sandbox-Zahlung wurde bestätigt, während der Shop im Live-Modus war. Prüfen Sie die Transaktion im Netopia-Admin.

Eine im Netopia-Admin vorgenommene Erstattung erscheint nicht in der Bestellung: Die Gutschrift-IPN hat den Shop nicht erreicht oder wurde abgelehnt. Prüfen Sie das Log.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Netopia 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 Gateway-Einstellungen (einschließlich der gespeicherten Schlüssel), die Netopia-Zahlungsdatensätze des Moduls (im Netopia-Block der Bestellungen angezeigt) und das Protokoll entfernt. Ist die Option ausgeschaltet, bleibt alles für eine spätere Neuinstallation erhalten. Bestellungen und die Bestellstatus Awaiting Netopia payment und Netopia payment on hold werden nie gelöscht. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Netopia Payments und mobilPay sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist weder mit Netopia Payments verbunden noch wird es von Netopia Payments unterstützt.