VibeFox Quickpay 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.

Quickpay-Konto: Sie benötigen zwei Werte aus dem Quickpay-Manager: den API-Schlüssel eines API-Benutzers (zum Erstellen von Zahlungen, Erfassen und Erstatten) und den privaten Schlüssel des Kontos (zum Prüfen der Signatur von Quickpay-Callbacks). In Quickpay muss sonst nichts eingerichtet werden. Ihr Shop muss aus dem Internet erreichbar sein, nicht hinter einem Passwortschutz, damit Quickpay-Callbacks ankommen können.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 suchen Sie später VibeFox Quickpay Gateway in der Modulliste und klicken Sie 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. Fügen Sie den API-Schlüssel und den privaten Schlüssel aus dem Quickpay-Manager ein und klicken Sie auf Test API key (siehe Konfiguration).

5. Wählen Sie den Erfassungsmodus und den Bestellstatus nach der Zahlung, aktivieren Sie Enable/Disable und klicken Sie auf Save. Solange Ihr Quickpay-Konto im Testmodus ist, aktivieren Sie Test payments und führen Sie eine Zahlung mit einer Quickpay-Testkarte durch.

Bei der Installation legt das Modul einen Bestellstatus an: Quickpay payment on hold. PrestaShop aktiviert das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Das Modul wird mit den Ländern verknüpft, die bei der Installation aktiv sind. Sie können alle in Payment > Preferences ändern.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Solange API-Schlüssel und privater Schlüssel nicht gespeichert sind, zeigt die Seite Quickpay benötigt Einrichtung: API-Schlüssel und privaten Schlüssel eingeben. Solange beide nicht gespeichert sind, wird die Zahlungsmethode an der Kasse ausgeblendet. Solange Test payments aktiv ist, erinnert die Seite daran, es auszuschalten, wenn Ihr Quickpay-Konto live geht.

Quickpay

Enable/Disable: Enable Quickpay schaltet die Zahlungsmethode ein oder aus. Standard: ausgeschaltet.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Quickpay. Pflichtfeld: Ein leerer Titel wird nicht gespeichert.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely by card or MobilePay on the Quickpay payment page.

Quickpay-API-Zugangsdaten

Öffnen Sie im Quickpay-Manager (manage.quickpay.net) Settings > Integration. Kopieren Sie den API-Schlüssel eines API-Benutzers (Settings > Users) und den privaten Schlüssel des Kontos.

Callback URL: zeigt die Callback-URL Ihres Shops. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay ruft sie nach jedem Zahlungsvorgang auf (Autorisierung, Erfassung, Erstattung, Stornierung). Sie wird automatisch mit jeder Zahlung übermittelt, sodass in Quickpay nichts konfiguriert werden muss.

API key: der API-Schlüssel eines Quickpay-API-Benutzers. Er wird zum Erstellen von Zahlungen, Erfassen und Erstatten verwendet.

Private key: der private Schlüssel des Kontos. Er wird zum Prüfen der Signatur (HMAC-SHA256) von Quickpay-Callbacks verwendet. Ohne ihn kann keine Zahlung bestätigt werden, und Callbacks werden abgelehnt.

Gespeicherte Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Gespeichert: leer lassen, um ihn zu behalten. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Gespeicherte Geheimnisse löschen: markieren Sie API key oder Private key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Test payments: akzeptiert Zahlungen mit Quickpay-Testkarten. Quickpay hat kein separates Sandbox: Solange Ihr Quickpay-Konto im Testmodus ist, werden Zahlungen mit Testkarten durchgeführt und als Test gekennzeichnet. Aktivieren Sie dies nur während der Tests. Ist es ausgeschaltet, markiert eine Testzahlung eine Bestellung nie als bezahlt. Ist es eingeschaltet, zeigt die Kasse unter der Zahlungsmethode Testmodus: Es werden Quickpay-Testkarten akzeptiert. an. Standard: ausgeschaltet.

Test API key: Diese Schaltfläche prüft den im Feld API key eingegebenen Schlüssel (oder den gespeicherten, falls das Feld leer ist) mit einer authentifizierten Anfrage an Quickpay, ohne ihn zu speichern. Sie antwortet mit Verbindung erfolgreich — der API-Schlüssel ist gültig., Quickpay hat den API-Schlüssel abgelehnt., API-Schlüssel ist nicht konfiguriert. oder Verbindung fehlgeschlagen: gefolgt vom Grund.

Zahlung

Capture: wann das Geld von der Karte abgebucht wird.

Order status after payment: der Bestellstatus, sobald Quickpay die erfasste Zahlung bestätigt hat.

Erweitert

Debug log: schreibt in logs/qpg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler und Warnungen, etwa abgelehnte Callbacks und Quickpay-API-Fehler, werden immer protokolliert. Aktivieren Sie dies, um auch die Details jeder Anfrage und jedes Callbacks zu protokollieren. API-Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: ausgeschaltet.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Delete data: Wenn eingeschaltet, entfernt das Deinstallieren des Moduls die Gateway-Einstellungen und das Protokoll. Bestelldaten (Quickpay-Zahlungen, Erstattungen, Notizen) und der Bestellstatus Quickpay payment on hold bleiben immer erhalten. Standard: ausgeschaltet.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Quickpay, mit einem Kartensymbol) und bestätigt. Das Modul erstellt eine Quickpay-Zahlung für den Warenkorb in der Warenkorbwährung und einen Zahlungslink für den Warenkorbbetrag und leitet den Kunden zum Quickpay-Zahlungsfenster weiter. Zu diesem Zeitpunkt existiert noch keine Bestellung. Der Kunde zahlt dort mit einer der Methoden, die in Ihrem Quickpay-Zahlungsfenster aktiviert sind. Die E-Mail-Adresse des Kunden wird an Quickpay übergeben. Das Zahlungsfenster öffnet sich in der Sprache des Kunden, wenn Quickpay sie anbietet (Dänisch, Deutsch, Englisch, Spanisch, Finnisch, Französisch, Italienisch, Niederländisch, Norwegisch, Polnisch, Schwedisch), andernfalls auf Englisch.

Nach der Zahlung kehrt der Kunde zu Ihrem Shop zurück. Die Rückkehr selbst markiert nichts als bezahlt. Die Bestellung wird erst als bezahlt markiert, nachdem Quickpay bestätigt hat: Der signierte Callback legt die Bestellung an, sobald der erfasste Betrag und die Währung mit dem Warenkorb übereinstimmen. Danach sieht der Kunde die übliche Bestellbestätigungsseite. Bei Authorize only wird die Bestellung stattdessen in Quickpay payment on hold angelegt, und Sie erfassen die Zahlung später. Ist der Callback noch nicht eingetroffen, wenn der Kunde zurückkehrt, zeigt eine Seite Payment confirmation die Meldung Ihre Zahlung wird von Quickpay bestätigt. Sie erhalten eine E-Mail, sobald die Bestellung bestätigt ist. mit den Schaltflächen Check again und Back to checkout.

Bricht der Kunde im Zahlungsfenster ab, wird der Zahlungslink in Quickpay gelöscht, und der Kunde ist wieder an der Kasse mit der Meldung Die Zahlung wurde abgebrochen. Sie können es erneut versuchen oder eine andere Zahlungsmethode wählen. Wurde die Karte abgelehnt, lautet die Meldung Die Zahlung wurde nicht abgeschlossen. Sie können es erneut versuchen oder eine andere Zahlungsmethode wählen. Der Warenkorb bleibt erhalten. Ein neuer Versuch verwendet die Quickpay-Zahlung des Warenkorbs mit einem neuen Link erneut, sodass ein alter Link niemals parallel bezahlt werden kann. Solange eine Zahlung des Warenkorbs autorisiert ist und auf ihre Erfassung wartet, wird keine zweite Zahlung gestartet; der Kunde sieht die Seite Payment confirmation.

Kann die Zahlung nicht gestartet werden, bleibt der Kunde an der Kasse mit der Meldung Die Quickpay-Zahlung konnte nicht gestartet werden. Bitte versuchen Sie es erneut oder wählen Sie eine andere Zahlungsmethode. Der technische Grund wird ins Protokoll geschrieben. Fehlen die Schlüssel, lautet die Meldung Quickpay ist momentan nicht verfügbar. Bitte wählen Sie eine andere Zahlungsmethode.

Der Callback funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Das Modul unterstützt nur Einmalzahlungen. Es gibt keine Abonnements oder wiederkehrenden Zahlungen, keine gespeicherten Karten und keine Teilerfassung, es werden keine Warenkorb- oder Rechnungspositionen an Quickpay übermittelt, und es gibt keine eigenen Methoden MobilePay, Apple Pay oder Klarna: Der Kunde wählt unter den Methoden Ihres Quickpay-Zahlungsfensters.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde wurde zu Quickpay weitergeleitet und hat nicht bezahlt, die Karte wurde abgelehnt, oder die Zahlung ist autorisiert und wartet auf die automatische Erfassung. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Quickpay hat die erfasste Zahlung mit dem richtigen Betrag und der richtigen Währung bestätigt. Der Status folgt Order status after payment. Die Zahlung wird mit der Quickpay-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlung (bei Testzahlungen als TEST gekennzeichnet).

Quickpay payment on hold: Die Zahlung ist nur autorisiert und wartet auf Capture Quickpay payment; oder Quickpay hat einen anderen Betrag oder eine andere Währung gemeldet als den Bestellbetrag (z. B. wurde der Warenkorb nach Beginn der Zahlung geändert oder im Quickpay-Manager wurde ein anderer Betrag erfasst); oder die automatische Erfassung ist fehlgeschlagen, und der Betrag ist nur reserviert. Die Notiz erklärt es. Wurde Geld mit einem abweichenden Betrag erfasst, wird die Zahlung in der Bestellung mit dem von Quickpay erfassten Betrag gespeichert.

Canceled: Sie haben die Bestellung storniert, oder die Zahlung einer wartenden Bestellung wurde im Quickpay-Manager storniert.

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

Eine Zahlung, die für eine bereits bezahlte, stornierte oder erstattete Bestellung eingeht, ändert die Bestellung nicht. Eine Notiz bittet Sie, die Zahlung im Quickpay-Manager zu prüfen, zum Beispiel um eine doppelte Zahlung zu erstatten.

Wenn Sie eine unbezahlte Bestellung stornieren, wird ihr Zahlungslink in Quickpay gelöscht. Das Stornieren einer autorisierten Bestellung gibt den reservierten Betrag nicht automatisch frei: Eine Notiz erinnert Sie daran, die Zahlung im Quickpay-Manager zu stornieren; andernfalls endet die Reservierung, wenn die Autorisierung abläuft.

Quickpay-Block

Die Bestellseite zeigt einen Block Quickpay payment mit der Zahlungs-ID, dem Zahlungsstatus, dem Betrag und dem erstatteten Betrag, einem Kennzeichen Test payment bei Testzahlungen, der Liste aller Quickpay-Zahlungen des Warenkorbs (wenn es mehr als eine gibt), dem Erstattungsverlauf und den Quickpay notes der Bestellung. Erfassung und Erstattungen erfordern das Recht, Bestellungen zu bearbeiten; Zugriff auf die Modulseiten ist nicht nötig.

Erfassung

Bei Authorize only klicken Sie im Quickpay-Block auf Capture Quickpay payment und bestätigen Sie Den Bestellbetrag über Quickpay erfassen? Der Bestellbetrag wird erfasst; eine Teilerfassung ist nicht verfügbar. Bestätigt Quickpay sofort, wird die Bestellung auf den Status von Order status after payment gesetzt. Andernfalls zeigt eine Notiz, dass die Erfassung angefordert wurde, und die Bestellung wird als bezahlt markiert, sobald der Quickpay-Callback sie bestätigt. Eine abgelehnte Erfassung wird im Block angezeigt und in der Bestellung notiert.

Erstattungen

Geben Sie im Quickpay-Block den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Quickpay. Bestätigen Sie die Frage Diesen Betrag über Quickpay erstatten? Dies kann nicht rückgängig gemacht werden. Vollständige und teilweise Erstattungen werden für erfasste Zahlungen unterstützt. Erstattungen erfolgen in dem Betrag und in der Währung, die Quickpay erfasst 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, nicht den Bestellbetrag. Quickpay verarbeitet Erstattungen asynchron: Der Erstattungsverlauf zeigt requested, und der Callback setzt den Status auf confirmed oder failed und fügt das Ergebnis den Notizen hinzu. Lehnt Quickpay die Erstattung sofort ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Eine autorisierte Zahlung, die nie erfasst wurde, kann nicht erstattet werden; stornieren Sie sie im Quickpay-Manager.

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

Erstattungen, die direkt im Quickpay-Manager vorgenommen werden, werden nur den Notizen hinzugefügt. Bestellstatus und Gutschriften werden nicht automatisch geändert. Aktualisieren Sie sie bei Bedarf manuell.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Quickpay Gateway ist der erste Block unter Modules > Module Manager > VibeFox Quickpay Gateway > Configure, oberhalb der Einstellungen. Geben 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, 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-quickpay 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. Nachdem sich die Shop-Adresse geändert hat 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 aktiven Schlüssel wird Quickpay 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 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 gestartete Zahlungen werden weiterhin bestätigt, und Erfassung und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber 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 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

Quickpay erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und sowohl API key als auch Private key gespeichert sind. Ohne beide Schlüssel wird die Methode ausgeblendet. 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 durchgegangen, aber es wurde keine Bestellung angelegt: Der Quickpay-Callback hat Ihren Shop nicht erreicht oder wurde abgelehnt. Prüfen Sie, ob Ihr Shop aus dem Internet erreichbar ist (kein Passwortschutz) und ob Private key der private Schlüssel desselben Quickpay-Kontos ist. Abgelehnte Callbacks werden immer im Protokoll der Modulseite geschrieben. Aktivieren Sie Debug log, um jeden Callback zu sehen.

Protokoll zeigt Callback rejected: invalid checksum.: Der private Schlüssel in den Einstellungen gehört nicht zu dem Konto, das den Callback gesendet hat. Kopieren Sie ihn erneut aus Settings > Integration im Quickpay-Manager.

Protokoll zeigt Callback rejected: the private key is not configured.: Geben Sie den privaten Schlüssel ein. Callbacks werden ohne ihn nie akzeptiert.

Protokoll zeigt Callback: no cart found for payment …: Der Callback gehört zu einer Quickpay-Zahlung, die dieser Shop nicht erstellt hat, zum Beispiel eine Zahlung außerhalb von PrestaShop.

Protokoll zeigt Could not lock the cart oder Cannot create the order: Ein anderer Callback desselben Warenkorbs wurde gerade verarbeitet, oder die Bestellung konnte nicht angelegt werden (z. B. weil das Modul deaktiviert ist). Der Callback wird mit einem Fehler beantwortet, sodass Quickpay ihn erneut sendet.

Eine Testzahlung hat die Bestellung nicht als bezahlt markiert: Test payments ist ausgeschaltet. Das Protokoll (und die Notiz, falls die Bestellung existiert) meldet, dass die Testzahlung nicht akzeptiert wurde. Schalten Sie die Einstellung während Tests ein und aus, wenn Ihr Konto live geht.

Bestellung ist nach der Zahlung in Quickpay payment on hold: Lesen Sie die Notizen im Quickpay-Block. Die Zahlung ist möglicherweise nur autorisiert und wartet auf Capture Quickpay payment, der bezahlte Betrag oder die Währung weicht von der Bestellung ab, oder die Erfassung ist fehlgeschlagen. Erfassen Sie die Zahlung, bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

Test API key meldet: „Quickpay hat den API-Schlüssel abgelehnt.“ Der Schlüssel ist falsch oder gehört zu einem Benutzer ohne API-Zugriff. Kopieren Sie den API-Schlüssel eines API-Benutzers aus dem Quickpay-Manager.

Der Kunde sieht „Die Quickpay-Zahlung konnte nicht gestartet werden.“: Sehen Sie im Feld Log auf der Modulseite nach. Dort steht der Quickpay-Fehler, zum Beispiel eine Währung, die Ihr Quickpay-Konto nicht akzeptiert.

Erstattung schlägt fehl: Die Bestellung muss eine erfasste Quickpay-Zahlung haben. Die Meldung Die Quickpay-Zahlung dieser Bestellung wurde nicht erfasst — es gibt nichts zu erstatten. bedeutet, dass die Zahlung nur autorisiert ist; erfassen oder stornieren Sie sie im Quickpay-Manager. Ungültiger Erstattungsbetrag: höchstens … bedeutet, dass der Betrag über dem liegt, was von der erfassten Zahlung noch übrig ist.

Entwickler können die Parameter des Quickpay-Zahlungslinks mit dem Hook actionQpgQuickpayLinkData ändern.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Quickpay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data eingeschaltet, werden die Gateway-Einstellungen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Quickpay-Zahlungen, Erstattungen und der Bestellstatus Quickpay payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen auch nach einer Neuinstallation erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Quickpay ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Quickpay verbunden noch wird es von Quickpay unterstützt.