VibeFox GoPay 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: GoPay akzeptiert CZK, EUR, PLN, USD, GBP, HUF, RON und BGN. Bei einer anderen Warenkorbwährung wird die Zahlungsmethode in der Kasse ausgeblendet.
GoPay-Konto: Sie benötigen die GoID, Client ID und Client Secret Ihres GoPay-Händlerkontos. Sie finden sie in den Integrationseinstellungen des Kontos. Das Sandbox-Konto (Testkonto) hat eigene Zugangsdaten. Für die Benachrichtigungen muss im GoPay-Konto nichts eingerichtet werden, Ihr Shop muss aber aus dem Internet erreichbar sein.
VibeFox-Lizenzschlüssel: Erwerb über vibefox.net. Ein Schlüssel gilt 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 aus.
2. Klicken Sie nach Abschluss des Uploads auf Configure oder suchen Sie VibeFox GoPay Gateway später in der Modulliste und klicken Sie dort auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel unter License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Geben Sie die GoID, Client ID und Client Secret der Sandbox ein, lassen Sie Test Mode aktiviert, schalten Sie Enable/Disable ein und klicken Sie auf Save.
5. Legen Sie eine Testbestellung an. Wenn alles funktioniert, geben Sie die Produktivzugangsdaten ein und deaktivieren Sie Test Mode.
Bei der Installation legt das Modul den Bestellstatus GoPay payment on hold an. PrestaShop stellt das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen bereit. Sie können dies unter Payment > Preferences einschränken.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox GoPay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Sandbox mode — test payments only bzw. Production mode — real payments an. Sie wird angezeigt, wenn die GoID, Client ID oder das Client Secret des aktuellen Modus fehlt, und wenn GoPay die Standardwährung des Shops nicht akzeptiert. In beiden Fällen wird GoPay in der Kasse nicht angeboten. Beim Speichern werden die zwischengespeicherten GoPay-Zugriffstoken gelöscht, sodass die neuen Zugangsdaten sofort verwendet werden.
GoPay
Enable/Disable: Enable GoPay payment gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.
Title: der Titel der Zahlungsmethode, der in der Kasse angezeigt wird. Er ist zugleich der Name der Zahlungsmethode, der in der Bestellung gespeichert wird. Standard: GoPay. Pflichtfeld: Ein leerer Titel wird nicht gespeichert.
Description: die Beschreibung der Zahlungsmethode, die in der Kasse angezeigt wird. Standard: Pay securely via GoPay - cards, wallets, bank transfers.
API-Zugangsdaten
GoID, Client ID und Client Secret werden in Ihrem GoPay-Händlerkonto angezeigt (Integrationseinstellungen). Das Sandbox-Konto (Testkonto) hat eigene Zugangsdaten. Die API-Dokumentation finden Sie unter doc.gopay.com.
Test Mode: sendet Zahlungen mit den Sandbox-Zugangsdaten an gw.sandbox.gopay.com. Es wird kein echtes Geld belastet. Schalten Sie den Modus aus, um echte Zahlungen mit den Produktivzugangsdaten anzunehmen. Standard: ein.
Sandbox GoID: die GoID Ihres GoPay-Sandbox-Kontos (Testkonto).
Sandbox Client ID: die OAuth-Client-ID des Sandbox-Kontos.
Sandbox Client Secret: das OAuth-Client-Secret des Sandbox-Kontos.
Production GoID: Ihre GoPay-Händler-ID (GoID).
Production Client ID: die OAuth-Client-ID von GoPay.
Production Client Secret: das OAuth-Client-Secret von GoPay.
Eine GoID besteht nur aus Ziffern, zum Beispiel 8123456789. Wenn Sie etwas anderes eingeben, zeigt die Seite einen Fehler an und der bisherige Wert bleibt erhalten.
Gespeicherte Client Secrets werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Clear saved client secrets: Aktivieren Sie die Option und klicken Sie auf Save, um beide gespeicherten Client Secrets zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.
Zahlung
Payment Page Language: die Sprache der GoPay-Zahlungsseite. Standard: Automatic (site language, then billing country). Die automatische Auswahl nutzt die Sprache des Warenkorbs des Kunden; wenn GoPay diese Sprache nicht hat, entscheidet das Rechnungsland, und andernfalls wird Englisch verwendet. Sie können auch eine von 19 Sprachen festlegen: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian oder Russian.
Order Status After Payment: der Bestellstatus, der gesetzt wird, sobald die Zahlung bestätigt ist.
Zahlungen, die nicht zur Bestellung passen, Zahlungen nach einer Stornierung und vorautorisierte Zahlungen gehen immer auf GoPay payment on hold.
Zahlungsbenachrichtigungen
Die Benachrichtigung teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Die Notification URL wird in diesem Abschnitt angezeigt und mit jeder Zahlung an GoPay übermittelt, daher muss im GoPay-Konto nichts eingerichtet werden. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_gopay_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Sie muss aus dem Internet erreichbar sein: kein Passwortschutz und keine Firewall davor. Sie funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.
GoPay-Benachrichtigungen enthalten nur die Zahlungs-ID und keine Signatur. Jede Benachrichtigung wird überprüft, indem der Zahlungsstatus über die GoPay-API mit den Zugangsdaten des Modus abgefragt wird, in dem die Zahlung getätigt wurde. Die Zahlung muss vom Modul für einen Warenkorb Ihres Shops erstellt worden sein. Kann der Status nicht von GoPay gelesen werden, antwortet Ihr Shop mit einem Fehler, und GoPay wiederholt die Benachrichtigung. Ohne Benachrichtigungen wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.
Erweitert
Logging: schreibt GoPay-Ereignisse in logs/gopay_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler und Warnungen werden immer protokolliert. Zugangsdaten, Token, Kartendaten sowie E-Mail-Adresse und Name des Kunden werden nie protokolliert. Standard: aus.
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 aktiviert, entfernt die Deinstallation des Moduls die Moduleinstellungen, die zwischengespeicherten GoPay-Zugriffstoken und das Protokoll. Bestellungen, ihre GoPay-Zahlungsdaten und der Bestellstatus GoPay payment on hold bleiben immer erhalten. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig GoPay) und bestätigt. Das Modul erstellt eine GoPay-Zahlung für die Warenkorbsumme in der Warenkorbwährung mit den Produkten, dem Versand und der Geschenkverpackung und leitet den Kunden zur GoPay-Zahlungsseite weiter. Dort bietet GoPay die in Ihrem GoPay-Konto aktivierten Zahlungsmethoden an, zum Beispiel Zahlungskarten, Banküberweisungen und digitale Geldbörsen. Rechnungsname, E-Mail-Adresse, Telefonnummer und Adresse des Kunden werden an GoPay übergeben; leere Felder werden nicht gesendet. Die Zahlung erscheint bei GoPay als Order PS- und der Warenkorbnummer. 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, nachdem GoPay die Zahlung bestätigt hat: durch die Benachrichtigung oder durch eine Anfrage an die GoPay-API, wenn der Kunde zurückkehrt. Benachrichtigung und Rückkehr, die zur selben Zeit eintreffen, werden nacheinander verarbeitet, sodass nur eine Bestellung entsteht. Der Kunde sieht danach die übliche Bestellbestätigungsseite. Wenn die Bestellung auf GoPay payment on hold gesetzt wurde, ergänzt die Seite den Hinweis Your payment is being reviewed. We will contact you if anything else is needed.
Wenn GoPay die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt hat (zum Beispiel, weil eine Banküberweisung unterwegs ist oder GoPay nicht erreichbar ist), zeigt eine Seite Payment confirmation den Hinweis GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. mit einer Schaltfläche Check again.
Wurde die Zahlung nicht abgeschlossen, abgebrochen oder ist sie abgelaufen, kehrt der Kunde zur Kasse zurück und sieht The GoPay payment was not completed. You can try again or choose another payment method. bzw. The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Der Warenkorb bleibt erhalten, und ein neuer Versuch erzeugt eine neue GoPay-Zahlung. Ein Warenkorb, der bereits eine Bestellung hat, wird nie erneut belastet.
Wenn GoPay die Zahlung nicht starten kann, bleibt der Kunde in der Kasse mit einer kurzen Meldung, zum Beispiel GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. oder GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. Der technische Grund wird im Protokoll festgehalten.
Der Kunde wählt die Zahlungsmethode auf der GoPay-Seite; in PrestaShop kann sie nicht gewählt werden. Das Modul unterstützt keine Abonnements oder wiederkehrenden Zahlungen, keine gespeicherten Karten, kein eingebettetes Zahlungsformular und kein Erfassen oder Aufheben von Vorautorisierungen aus PrestaShop heraus.
Bestellungen und Erstattungen
Bestellstatus
No order yet: Der Kunde wurde zu GoPay weitergeleitet und hat noch nicht bezahlt, oder GoPay hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.
Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status folgt Order Status After Payment. Die Zahlung wird mit der GoPay-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungs-ID und das Zahlungsinstrument.
GoPay payment on hold: GoPay hat die Zahlung bestätigt, aber Betrag, Währung oder Bestellnummer weichen vom Warenkorb ab (zum Beispiel wurde der Warenkorb nach Beginn der Zahlung geändert); oder die Zahlung kam, nachdem die Bestellung storniert worden war; oder die Zahlung ist nur vorautorisiert und das Geld noch nicht erfasst. Die Notiz erklärt es. Eine vorautorisierte Zahlung muss bei GoPay erfasst werden; danach wechselt die Bestellung in den bezahlten Status, sobald GoPay die Zahlung als bezahlt meldet.
Refunded: Die GoPay-Zahlung der Bestellung wurde vollständig erstattet, über das Modul oder im GoPay-Konto.
Wird eine weitere Zahlungsmethode einer bereits bezahlten Bestellung ebenfalls bezahlt, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, das Duplikat im GoPay-Konto zu erstatten. Eine ähnliche Notiz wird hinzugefügt, wenn eine GoPay-Zahlung für eine Bestellung eingeht, die bereits ohne GoPay als bezahlt markiert war, zum Beispiel manuell. Eine stornierte oder erstattete Bestellung wird durch eine spätere Benachrichtigung nie wieder geöffnet.
GoPay-Zahlungsblock
Die Bestellseite zeigt einen Block GoPay payment mit der GoPay-Zahlungs-ID, dem GoPay-Status und dem Zahlungsinstrument, dem Zahlungsbetrag, dem bezahlten und erstatteten Betrag, einem Kennzeichen Sandbox für Sandbox-Zahlungen, dem Grund für eine manuelle Prüfung, dem Erstattungsverlauf und den GoPay notes der Bestellung.
Erstattungen
Geben Sie im Block GoPay payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via GoPay. Bestätigen Sie die Abfrage Refund this amount through GoPay? 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 erforderlich. GoPay akzeptiert teilweise Erstattungen nur 24 Stunden nach der Zahlung. Erstattungen erfolgen in dem Betrag und in der Währung, die GoPay belastet hat. Nach einer Abweichung von Betrag oder Währung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat. Die Erstattung wird in dem Modus gesendet, in dem die Zahlung erfolgt ist (Sandbox oder Produktivbetrieb), daher müssen die Zugangsdaten dieses Modus eingerichtet sein. Lehnt GoPay die Erstattung ab, zeigt der Block die Meldung von GoPay an und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen hinzugefügt; eine Erstattung, die GoPay zur späteren Bearbeitung angenommen hat, wird als angenommen vermerkt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht.
Das Modul erstellt keine Gutschriften (Credit Slips). Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über GoPay zurück.
Im GoPay-Konto vorgenommene Erstattungen werden per Benachrichtigung übermittelt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung fügt eine Notiz hinzu. Sie werden nicht dem Erstattungsverlauf des Blocks hinzugefügt.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox GoPay Gateway ist der erste Block auf Modules > Module Manager > VibeFox GoPay Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel unter 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 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-gopay 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. Kann der Lizenzserver nicht erreicht werden, 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-Setup. 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 aktiven Schlüssel wird GoPay Kunden in der Kasse nicht angezeigt. Wird die Zahlung dennoch 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 Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte 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, aber Updates und Support erfordern eine Verlängerung. Der Status wird während Ihrer 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
GoPay erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, für den aktuellen Modus GoID, Client ID und Client Secret hinterlegt sind und die Warenkorbwährung eine von CZK, EUR, PLN, USD, GBP, HUF, RON oder BGN ist. Die Einstellungsseite zeigt eine Warnung an, wenn Zugangsdaten fehlen. 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: GoPay konnte die in den Einstellungen angezeigte Notification URL nicht erreichen, und der Kunde ist nicht in den Shop zurückgekehrt. Entfernen Sie Passwortschutz oder Firewall-Regeln, die die URL blockieren. Prüfen Sie, ob die Zugangsdaten des Modus, in dem die Zahlung erfolgt ist, eingerichtet sind, denn jede Benachrichtigung wird mit ihnen geprüft. Aktivieren Sie Logging und sehen Sie im Feld Log nach. GoPay wiederholt Benachrichtigungen, die keine erfolgreiche Antwort erhalten haben.
Notification answers Order not found: Die Zahlung wurde nicht von diesem Shop erstellt oder ihr Warenkorb wurde gelöscht.
Notification answers Payment state could not be verified: Die GoPay-API war nicht erreichbar oder die Zugangsdaten dieses Modus fehlen oder sind falsch. GoPay wiederholt die Benachrichtigung.
Notification answers Busy, retry later: 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). GoPay wiederholt die Benachrichtigung. Aktivieren Sie Logging, um den Grund zu sehen.
Der Kunde sieht einen Fehler bei der Auswahl von GoPay: Aktivieren Sie Logging und sehen Sie im Feld Log nach. Falsche Zugangsdaten oder Zugangsdaten des anderen Modus sind der übliche Grund. Eine Meldung zu den Rechnungsdaten bedeutet, dass GoPay E-Mail-Adresse, Telefonnummer oder Adresse nicht akzeptiert hat.
Testzahlungen bestätigen keine Live-Bestellung: Sandbox und Produktivbetrieb sind getrennt. Jede Zahlung wird in dem Modus geprüft, in dem sie erstellt wurde. Stellen Sie Test Mode auf den gewünschten Modus um und verwenden Sie dessen Zugangsdaten.
Bestellung ist nach der Zahlung GoPay payment on hold: Lesen Sie die Notizen im Block GoPay payment. Der bezahlte Betrag oder die Währung wich vom Warenkorb ab, die Zahlung kam nach der Stornierung der Bestellung, oder die Zahlung ist nur vorautorisiert.
Erstattung schlägt fehl: Lesen Sie die Meldung von GoPay im Block. Eine teilweise Erstattung ist nur 24 Stunden nach der Zahlung möglich. Eine Meldung zum Modus bedeutet, dass die Zahlung im Sandbox- oder Produktivmodus erfolgt ist und die Zugangsdaten dieses Modus nicht eingerichtet sind.
Für Entwickler: Der Hook actionGopayPaymentPayload verändert die Zahlungsanfrage, bevor sie an GoPay gesendet wird.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox GoPay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall aktiviert, werden die Moduleinstellungen, die zwischengespeicherten GoPay-Zugriffstoken und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die GoPay-Zahlungsdaten der Bestellungen und der Bestellstatus GoPay payment on hold bleiben immer erhalten, sodass bereits bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
GoPay ist eine Marke des jeweiligen Inhabers. Dieses Modul ist nicht mit GoPay verbunden und wird nicht von GoPay unterstützt.