VibeFox PayPlug 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 und Beträge: Euro (EUR), von 0,99 bis 20.000,00 pro Zahlung, die PayPlug-Standardwerte. Bei einer anderen Warenkorbwährung oder außerhalb dieser Grenzen wird die Zahlungsart ausgeblendet.

PayPlug-Konto: Sie benötigen die geheimen Schlüssel Ihres PayPlug-Kontos: den Testschlüssel (sk_test_...) und/oder den Live-Schlüssel (sk_live_...). Weitere Schlüssel sind nicht nötig, und in PayPlug muss keine Benachrichtigung eingerichtet werden. Ihr Shop muss aus dem Internet erreichbar sein, um Benachrichtigungen zu empfangen; andernfalls werden Bestellungen angelegt, wenn der Kunde von PayPlug zurückkehrt.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox PayPlug Gateway später in der Modulliste und klicken Sie auf Configure.

3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Fügen Sie Ihre geheimen Schlüssel aus dem PayPlug-Portal ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung mit eingeschaltetem Test Mode und schalten Sie ihn danach aus, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul den Bestellstatus PayPlug payment on hold an. PrestaShop aktiviert das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können sie unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox PayPlug Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn die Zahlungsart aktiviert ist, der geheime Schlüssel des aktuellen Modus aber leer ist, sowie wenn die Standardwährung des Shops nicht EUR ist. In beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet.

Kasse

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: PayPlug. Pflichtfeld.

Description: der Text unter der Zahlungsart an der Kasse. Standard: Pay securely by card via PayPlug.

API-Schlüssel

Ihre geheimen Schlüssel finden Sie im PayPlug-Portal unter Developers > API keys. Der Abschnitt enthält einen Link zum Portal.

Test Mode: verwendet den geheimen Testschlüssel für neue Zahlungen. Es werden keine echten Zahlungen verarbeitet. Zahlungen, die im anderen Modus getätigt wurden, verwenden für Statusprüfungen und Erstattungen weiterhin den Schlüssel ihres eigenen Modus. Standard: on. Solange er eingeschaltet ist, sehen Kunden unter der Zahlungsart Test mode: no real payment will be made.

Test Secret Key: Ihr geheimer PayPlug-Testschlüssel. Er beginnt mit sk_test_.

Live Secret Key: Ihr geheimer PayPlug-Live-Schlüssel. Er beginnt mit sk_live_.

Ein Schlüssel mit falschem Präfix wird nicht gespeichert. Die Seite zeigt zum Beispiel Test Secret Key must start with "sk_test_". The previous value was kept. 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 keys: markieren Sie einen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Notification URL: die Adresse, die das Modul mit jeder Zahlung an PayPlug sendet. Mit SEO-URLs sieht sie so aus: https://your-shop/module/wcp_payplug_gateway/webhook. Im PayPlug-Portal muss nichts eingetragen werden. Die URL muss aus dem Internet erreichbar sein; andernfalls werden Bestellungen angelegt, wenn der Kunde von PayPlug zurückkehrt.

Bestellungen

Order Status After Payment: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird. Der Status wird sofort gesetzt, ohne einen zweiten Statuswechsel.

Erweitert

Logging: protokolliert API-Aufrufe und Benachrichtigungen in logs/ppg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler und Warnungen werden immer protokolliert. Geheime Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. 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: ist die Option eingeschaltet, werden die Moduleinstellungen und das Protokoll bei der Deinstallation des Moduls gelöscht. Die bei Bestellungen gespeicherten PayPlug-Zahlungs-IDs und der Bestellstatus PayPlug payment on hold bleiben erhalten. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig PayPlug, mit dem PayPlug-Logo). Im Testmodus zeigt die Option Test mode: no real payment will be made. Nach der Bestätigung legt das Modul eine PayPlug-Zahlung für die Warenkorbsumme in Cent an und leitet den Kunden zur PayPlug-Zahlungsseite weiter. Rechnungs- und Lieferadresse, E-Mail-Adresse und Sprache des Warenkorbs werden an PayPlug übergeben. Dort bezahlt der Kunde mit Karte. 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 PayPlug die Zahlung bestätigt: Das Modul liest die Zahlung über die PayPlug-API aus, wenn die Benachrichtigung eingeht und wenn der Kunde zurückkehrt. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Your payment with PayPlug has been received. Ist die Bestellung in der Schwebe, lautet der Text auf der Seite We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Befindet sich die Bestellung in Payment error oder wurde sie ohne Zahlung storniert, lautet der Text Your PayPlug payment was not completed. Please contact us about this order. Konnte PayPlug bei der Rückkehr des Kunden nicht abgefragt werden, zeigt eine Seite Payment confirmation denselben Text „we are confirming“ und eine Schaltfläche Check again; die Benachrichtigung legt die Bestellung an, sobald sie eingeht.

Bricht der Kunde auf der PayPlug-Seite ab, wird die Zahlungsseite bei PayPlug geschlossen, sodass sie später nicht versehentlich bezahlt werden kann. Der Kunde kehrt zur Kasse zurück und sieht eine Meldung: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. oder, falls die Zahlung offen geblieben ist, Your PayPlug payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten.

Bezahlt der Kunde denselben Warenkorb erneut, prüft das Modul zuerst den vorherigen Versuch. Wurde er inzwischen bezahlt, wird die Bestellung ohne neue Zahlung angelegt. Ist er noch offen für denselben Betrag, wird dieselbe Zahlungsseite erneut verwendet. Andernfalls wird die alte Seite bei PayPlug geschlossen und eine neue Zahlung angelegt.

Kann PayPlug die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel PayPlug could not accept your billing details (postcode). Please check them and try again. oder The payment provider could not be reached. Please try again in a moment. Der technische Grund wird im Protokoll festgehalten.

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

Zahlungen werden sofort erfasst. Das Modul bietet keine Oney-Ratenzahlungen, keine Ein-Klick-Kartenspeicherung, kein eingebettetes Zahlungsformular, keine Abonnements und keine verzögerte Erfassung.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde wurde zu PayPlug weitergeleitet und hat nicht bezahlt, oder PayPlug hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status richtet sich nach Order Status After Payment. Die Zahlung wird mit der PayPlug-Zahlungs-ID (pay_...) als Transaktions-ID erfasst, und ein Hinweis zeigt die PayPlug-Zahlung und ihren Modus an.

PayPlug payment on hold: Der bezahlte Betrag oder die Währung weicht vom Warenkorb ab (Hinweis amount/currency mismatch, zum Beispiel wurde der Warenkorb nach Beginn der Zahlung geändert); oder es wurde eine Testzahlung getätigt, während der Shop im Live-Modus war, sodass kein Geld eingegangen ist und keine Zahlung erfasst wird; oder die Zahlung ist für eine stornierte Bestellung eingegangen; oder eine Zahlung ist autorisiert, aber nicht erfasst (erfassen Sie sie im PayPlug-Portal; die Bestellung wird als bezahlt markiert, sobald PayPlug sie als bezahlt meldet). Der Hinweis erklärt, was zu prüfen ist.

Payment error: Eine autorisierte Zahlung einer Bestellung in der Schwebe ist fehlgeschlagen oder wurde storniert.

Refunded: Die Zahlung wurde über das Modul vollständig erstattet.

Wird ein zweiter Versuch für einen bereits bezahlten Warenkorb ebenfalls bezahlt, bleibt die Bestellung unverändert. Ein Hinweis bittet Sie, die doppelte Zahlung im PayPlug-Portal zu erstatten. Eine bezahlte, stornierte oder erstattete Bestellung wird durch eine spätere Benachrichtigung nie wieder geöffnet.

PayPlug-Zahlungsblock

Die Bestellseite zeigt einen Block PayPlug payment mit der PayPlug-Zahlungs-ID, dem Zahlungsstatus, dem bezahlten und erstatteten Betrag, einem Kennzeichen Test mode bei Testzahlungen, dem Erstattungsverlauf und den PayPlug notes der Bestellung.

Erstattungen

Geben Sie im Block PayPlug payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via PayPlug. Bestätigen Sie die Frage Refund this amount through PayPlug? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Erstattungen erfolgen bis zu dem Betrag, den PayPlug tatsächlich eingezogen hat. Nach einer Betragsabweichung können Sie also den vom Kunden bezahlten Betrag erstatten, nicht die Bestellsumme. Die Erstattung geht an die Zahlung, mit der die Bestellung tatsächlich bezahlt wurde, und wird mit dem geheimen Schlüssel des Modus (Test oder Live) ausgeführt, in dem sie getätigt wurde; dieser Schlüssel muss daher konfiguriert sein. Lehnt PayPlug die Erstattung ab, zeigt der Block den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der PayPlug-Erstattungs-ID und dem Grund hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind erst möglich, wenn PayPlug die Zahlung als bezahlt gemeldet hat.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite schicken kein Geld über PayPlug zurück.

Im PayPlug-Portal vorgenommene Erstattungen kommen per Benachrichtigung an und werden einmal in den Notizen vermerkt. Sie werden im Block nicht mitgezählt und ändern weder den Bestellstatus noch die Gutschriften. Erfassen Sie sie bei Bedarf manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox PayPlug Gateway ist der erste Block auf Modules > Module Manager > VibeFox PayPlug 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 Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen 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-payplug 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 auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne einen aktiven Schlüssel wird PayPlug 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 PrestaShop-Storefront 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. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter 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 während 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 wöchentlich. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

PayPlug erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktuelle Modus einen geheimen Schlüssel hat (Test Secret Key im Testmodus, Live Secret Key im Live-Modus), die Währung des Warenkorbs EUR ist und die Warenkorbsumme zwischen 0,99 und 20.000,00 EUR liegt. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist. Entwickler können die Währungen und Grenzen mit den Hooks actionWcpPayplugSupportedCurrencies und actionWcpPayplugAmountLimits ändern (Werte in Cent).

Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: Die Benachrichtigung hat Ihren Shop nicht erreicht, und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob Ihr Shop unter der in den Einstellungen angezeigten Notification URL aus dem Internet erreichbar ist, zum Beispiel ob keine Firewall oder kein Passwortschutz sie blockiert. Aktivieren Sie Logging und sehen Sie im Feld Log nach abgelehnten Benachrichtigungen.

Die Benachrichtigung antwortet Verification failed.: Die Zahlung konnte nicht über die PayPlug-API gelesen werden, zum Beispiel weil PayPlug nicht geantwortet hat oder der geheime Schlüssel des Modus der Zahlung nicht gesetzt ist. Die Bestellung wird nicht verändert, und PayPlug sendet die Benachrichtigung erneut.

Die Benachrichtigung antwortet Temporarily unavailable.: Der Warenkorb wurde im selben Moment von einer anderen Anfrage aktualisiert, zum Beispiel der Rückkehr des Kunden, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). PayPlug sendet die Benachrichtigung erneut. Das Protokoll zeigt den Grund.

Die Benachrichtigung antwortet Unknown payment. oder Payment does not belong to the order.: Die Zahlung wurde nicht von diesem Shop oder nicht für diesen Warenkorb erstellt, zum Beispiel eine Zahlung eines anderen Shops auf demselben PayPlug-Konto. Sie wird ignoriert.

Die Benachrichtigungs-URL zeigt im Browser Method not allowed.: Das ist normal. Die URL akzeptiert nur Anfragen von PayPlug.

Der Kunde sieht bei der Wahl von PayPlug einen Fehler: Aktivieren Sie Logging und sehen Sie im Feld Log nach. Ein falscher Schlüssel führt zu This payment method is temporarily unavailable. Please choose another payment method.; andere Meldungen nennen das Rechnungsfeld, das PayPlug abgelehnt hat.

Bestellung ist nach der Zahlung PayPlug payment on hold: Lesen Sie die Notizen im Block PayPlug payment (siehe Bestellstatus) und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung wurde im Test- oder Live-Modus getätigt, und der geheime Schlüssel dieses Modus ist nicht konfiguriert. Tragen Sie ihn ein und versuchen Sie es erneut.

Erstattung schlägt mit Unexpected response from PayPlug. fehl: PayPlug hat ohne gültige Erstattung geantwortet. Es wurde nichts erfasst. Prüfen Sie die Erstattung im PayPlug-Portal, bevor Sie es erneut versuchen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox PayPlug 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 die Option ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Zahlungs- und Erstattungsdaten von PayPlug sowie der Bestellstatus PayPlug payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

PayPlug ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit PayPlug verbunden und wird von PayPlug nicht unterstützt.