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

Flutterwave-Konto: Sie benötigen die geheimen Schlüssel Ihres Flutterwave-Kontos aus dem Flutterwave-Dashboard unter Settings, API keys: FLWSECK_TEST-… für den Testmodus und FLWSECK-… für den Live-Modus. Verwendet werden nur die geheimen Schlüssel. Die öffentlichen Schlüssel und Verschlüsselungsschlüssel werden nicht benötigt. Außerdem richten Sie einen Webhook mit einem geheimen Hash Ihrer Wahl ein (siehe Konfiguration).

Währungen: Der Warenkorb wird immer in der Warenkorbwährung abgerechnet. Das Modul beschränkt Länder oder Währungen nicht selbst; Flutterwave zeigt einen Fehler an, wenn Ihr Konto die Währung nicht unterstützt. Sie können Währungen, Länder und Kundengruppen unter Payment > Preferences einschränken.

VibeFox-Lizenzschlüssel: Erwerb auf 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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Flutterwave Payment in der Modulliste und klicken Sie dort 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. Geben Sie Ihre geheimen Schlüssel ein, richten Sie den Webhook im Flutterwave-Dashboard ein und tragen Sie im Modul denselben geheimen Hash ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Testmodus und aktivieren Sie danach Live mode.

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

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern zeigt die Seite Live mode: real payments are accepted. oder Test mode: no real money is charged. an. Sie warnt, wenn der geheime Schlüssel des aktuellen Modus leer ist, wenn das Feld für den Live-Schlüssel im Live-Modus einen Testschlüssel (FLWSECK_TEST-…) enthält oder wenn das Feld für den Testschlüssel im Testmodus einen Live-Schlüssel (FLWSECK-…) enthält. In diesen Fällen wird die Zahlungsmethode an der Kasse so lange ausgeblendet, bis das behoben ist. Außerdem warnt sie, wenn kein geheimer Hash für den Webhook gesetzt ist: Webhooks werden dann abgelehnt, und Zahlungen werden nur bestätigt, wenn der Kunde zu Ihrem Shop zurückkehrt. Der Titel des ersten Abschnitts zeigt den aktuellen Modus an, TEST oder LIVE.

Flutterwave

Enable/Disable: Enable Flutterwave Payment schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Titel der Zahlungsmethode, den Kunden an der Kasse sehen. Er ist zugleich der Name der Zahlungsmethode, der in der Bestellung gespeichert wird. Standard: Flutterwave. Pflichtfeld.

Description: der Text, den Kunden während der Kasse unter der Zahlungsmethode sehen. Standard: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus dem Flutterwave-Dashboard unter Settings, API keys (der Abschnitt enthält einen Link). Testmodus und Live-Modus haben unterschiedliche Schlüssel.

Live mode: Akzeptiert echte Zahlungen. Für den Testmodus ausschalten. Der Testmodus verwendet den geheimen Testschlüssel, und es wird kein echtes Geld belastet. Der Live-Modus verwendet den geheimen Live-Schlüssel. Standard: aus (Testmodus). Solange der Testmodus aktiv ist, sehen Kunden unter der Zahlungsmethode TEST MODE - no real payments will be processed.

Test Secret Key: Ihr geheimer Testschlüssel von Flutterwave (FLWSECK_TEST-...).

Live Secret Key: Ihr geheimer Live-Schlüssel von Flutterwave (FLWSECK-...).

Gespeicherte Schlüssel und der geheime Hash 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.

Webhook

Der Webhook bestätigt Zahlungen auch dann, wenn der Kunde nicht zu Ihrem Shop zurückkehrt. Tragen Sie im Flutterwave-Dashboard unter Settings, Webhooks die URL ein, die in diesem Abschnitt unter Webhook URL angezeigt wird, sowie einen geheimen Hash Ihrer Wahl, sowohl für den Testmodus als auch für den Live-Modus. Mit freundlichen URLs sieht die URL so aus: https://your-shop/module/wcp_flutterwave_payment/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Das Modul reagiert auf dieses Ereignis:

Andere Ereignisse werden ignoriert.

Secret Hash: der geheime Hash des Webhooks. Er muss mit dem Wert in den Webhook-Einstellungen Ihres Flutterwave-Dashboards übereinstimmen. Flutterwave sendet ihn mit jedem Webhook, und derselbe Wert wird für den Testmodus und den Live-Modus verwendet. Webhooks ohne gültigen geheimen Hash werden abgelehnt. Ohne den Webhook wird eine Zahlung nur bestätigt, wenn der Kunde zu Ihrem Shop zurückkehrt.

Clear saved secrets: Setzen Sie ein Häkchen bei Test Secret Key, Live Secret Key oder Secret Hash und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlung

Payment Options: durch Kommas getrennte Zahlungsmethoden, die auf der Flutterwave-Seite angezeigt werden, zum Beispiel card, banktransfer, ussd, mobilemoney. Leer lassen, um alle in Ihrem Konto aktivierten Methoden anzuzeigen. Die Liste wird beim Speichern bereinigt (Kleinbuchstaben, keine Duplikate).

Autocomplete Orders: Bezahlte Bestellungen erhalten den Status Delivered statt Payment accepted, mit nur einem Statuswechsel. Standard: aus.

Erweitert

Debug log: protokolliert Flutterwave-API-Ereignisse zur Fehlersuche in logs/flwv_debug.log.php im Modulordner. Die Datei kann nicht im Webbrowser geöffnet werden. Fehler und Warnungen werden immer protokolliert. Schlüssel, der geheime Hash und Kundendaten 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: entfernt beim Deinstallieren des Moduls die Moduleinstellungen und Protokolle. Zahlungsdaten, die in Bestellungen gespeichert sind, bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Flutterwave) und bestätigt. Eine gültige E-Mail-Adresse ist erforderlich. Das Modul erstellt eine Flutterwave-Zahlung für den Warenkorbbetrag in der Warenkorbwährung, mit der E-Mail-Adresse des Kunden, der Telefonnummer und dem Namen der Rechnungsadresse, dem Namen und Logo Ihres Shops, und leitet den Kunden auf die Flutterwave-Zahlungsseite weiter. Dort bezahlt der Kunde mit einer der in Ihrem Konto aktivierten Methoden (oder einer unter Payment Options aufgeführten). 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 Flutterwave die Zahlung bestätigt hat: entweder über den Webhook oder über eine serverseitige Prüfung, wenn der Kunde zurückkehrt. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite. Ist die Zahlung noch ausstehend, etwa bei einer Banküberweisung, USSD- oder Mobile-Money-Zahlung, wird die Bestellung in Awaiting Flutterwave payment angelegt, und die Seite zeigt Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. an. Wurde die Bestellung zur Prüfung zurückgehalten, weil der bezahlte Betrag nicht zum Warenkorb passt, zeigt die Seite Your payment was received and your order is being reviewed. We will contact you if anything is needed. an. Schlägt eine ausstehende Zahlung später fehl und der Kunde öffnet die Bestätigungsseite erneut, zeigt sie Your Flutterwave payment was not completed. Please contact us about this order. an.

Kann Flutterwave bei der Rückkehr des Kunden nicht erreicht werden, zeigt eine Seite Payment confirmation den Text Your payment is being confirmed by Flutterwave. 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. Der Webhook legt die Bestellung an, sobald er eintrifft.

Wird die Zahlung abgelehnt, kehrt der Kunde zur Kasse zurück, wo Your payment was declined. You can try again or choose another payment method. angezeigt wird. Bricht der Kunde auf der Flutterwave-Seite ab, lautet die Meldung Payment was cancelled. You can try again or choose another payment method. Wurde die Zahlung nicht abgeschlossen, lautet die Meldung The payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten, und der Kunde kann erneut bezahlen. Jeder Versuch hat eine eigene Referenz, und ein älterer Zahlungslink, der später bezahlt wird, wird weiterhin akzeptiert.

Kann Flutterwave die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, etwa Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. Der technische Grund wird im Protokoll festgehalten.

Ändert sich der Warenkorb zwischen der Zahlung und ihrer Bestätigung, etwa in einem anderen Browser-Tab, stimmen die Beträge nicht mehr überein, und die Bestellung wird mit einer Notiz in Flutterwave payment on hold verschoben.

Der Webhook 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 bietet keine eingebettete oder modale Kasse auf Ihrer Website, keine gespeicherten Karten, Abonnements, Teilzahlungen oder Zahlungspläne. Gehostete Zahlungslinks können über die Flutterwave-API nicht storniert werden, daher kann ein alter Link eines Warenkorbs weiterhin bezahlt werden.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu Flutterwave weitergeleitet und hat noch nicht bezahlt, oder Flutterwave hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Delivered wird verwendet, wenn Autocomplete Orders aktiviert ist. Die Zahlung wird mit der Flutterwave-Referenz (flw_ref) als Transaktions-ID erfasst, und eine Notiz zeigt den Betrag, die Zahlungsmethode, die Referenz, die Transaktion und den Modus.

Awaiting Flutterwave payment: Der Kunde ist zurückgekehrt, während die Zahlung bei Flutterwave noch ausstehend war. Die Bestellung wechselt in den Status „bezahlt“, sobald Flutterwave die Zahlung bestätigt.

Flutterwave payment on hold: Der geprüfte Betrag oder die Währung stimmte nicht mit dem Warenkorb überein, oder die Zahlung ging ein, nachdem die Bestellung storniert worden war. Die Zahlung wird mit dem tatsächlich gezahlten Betrag erfasst (nicht mit dem Betrag, den Flutterwave in einer anderen Währung belastet hat). Die Notiz erklärt es. Bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung. Eine erstattete oder stornierte Bestellung wird durch einen wiederholten Webhook nie wieder geöffnet.

Payment error: Flutterwave hat den letzten Zahlungsversuch einer ausstehenden Bestellung als fehlgeschlagen oder abgebrochen gemeldet. Die Notiz zeigt den Grund.

Canceled: Wird von Ihnen gesetzt. Meldet Flutterwave später eine Zahlung für eine stornierte Bestellung, wechselt die Bestellung in Flutterwave payment on hold (siehe oben).

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

Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, das Duplikat im Flutterwave-Dashboard zu erstatten.

Flutterwave-Zahlungsblock

Die Bestellseite zeigt einen Block Flutterwave payment mit der Referenz (tx_ref), der Transaktions-ID und der Flutterwave-Referenz, dem Modus, dem Status und der Zahlungsmethode, dem bezahlten und erstatteten Betrag, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Flutterwave notes der Bestellung.

Erstattungen

Geben Sie im Block Flutterwave payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Flutterwave. Bestätigen Sie die Abfrage Refund this amount through Flutterwave? 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. Erstattungen erfolgen in dem Betrag und der Währung, die Flutterwave 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, und nicht den Bestellgesamtbetrag. Die Erstattung wird mit dem geheimen Schlüssel des Modus gesendet, in dem die Zahlung erfolgte (Test oder Live), daher muss dieser Schlüssel hinterlegt sein. Lehnt Flutterwave 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 Erstattungs-ID und dem Status hinzugefügt (completed oder initiated mit dem von Flutterwave gemeldeten Status). Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Flutterwave die Zahlung bestätigt hat.

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

Im Flutterwave-Dashboard vorgenommene Erstattungen werden nicht mit PrestaShop synchronisiert. Aktualisieren Sie den Bestellstatus bei Bedarf manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Flutterwave Payment ist der erste Block auf Modules > Module Manager > VibeFox Flutterwave Payment > 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-flutterwave 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 Shopadresse 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 gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Einrichtung. 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 Flutterwave 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 einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht 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. Es ist kein Cron-Job nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Flutterwave erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der geheime Schlüssel des aktuellen Modus ausgefüllt ist und zum Modus passt: ein Testschlüssel (FLWSECK_TEST-…) im Testmodus, ein Live-Schlüssel (FLWSECK-…) im Live-Modus. Die Einstellungsseite zeigt andernfalls eine Warnung an. 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 war erfolgreich, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht. Prüfen Sie im Flutterwave-Dashboard, ob die Webhook-URL genau der unter Webhook URL angezeigten entspricht, und zwar im Modus, den Sie verwenden (Test oder Live), und ob ihr geheimer Hash mit Secret Hash im Modul übereinstimmt. Ausstehende Banküberweisungen, USSD- und Mobile-Money-Zahlungen bleiben ausstehend, bis Flutterwave sie bestätigt. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt. Aktivieren Sie Debug log und sehen Sie sich das Feld Log auf der Modulseite an.

Der Webhook antwortet Invalid hash oder Secret hash not configured: Der geheime Hash im Flutterwave-Dashboard unterscheidet sich von dem im Modul oder im Modul ist keiner hinterlegt. Tragen Sie an beiden Stellen denselben Wert ein.

Der Webhook antwortet Verification failed, Busy, retry later oder Order could not be created, retry later: Flutterwave konnte zur Prüfung der Zahlung nicht erreicht werden, die Transaktion ist noch nicht sichtbar, der Warenkorb wurde gerade von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Flutterwave wiederholt den Webhook. Das Protokoll zeigt den Grund.

Die Webhook-URL zeigt im Browser Empty body an: Das ist normal. Die URL akzeptiert nur Webhooks von Flutterwave.

Der Kunde sieht Payment gateway is not properly configured: Der geheime Schlüssel des aktuellen Modus fehlt oder gehört zum anderen Modus.

Der Kunde sieht We could not match this payment to an order: Der Rücksprunglink enthält eine Referenz, die nicht zum Warenkorb des Kunden gehört. Wenn der Kunde belastet wurde, suchen Sie die Zahlung im Flutterwave-Dashboard.

Flutterwave zeigt auf seiner Seite einen Fehler an, oder der Kunde sieht Flutterwave could not start the payment: Ihr Flutterwave-Konto unterstützt möglicherweise die Warenkorbwährung oder die gewählten Zahlungsoptionen nicht.

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

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

Erstattung antwortet Another operation on this payment is running: Gerade wurde eine andere Erstattung derselben Bestellung gesendet. Warten Sie einen Moment, prüfen Sie den Erstattungsverlauf und versuchen Sie es bei Bedarf erneut.

Für Entwickler: Die README-Datei des Moduls listet die Hooks actionWcpFlutterwavePaymentRequest (an Flutterwave gesendete Daten) und actionWcpFlutterwaveCurrencyDecimals (Währungsgenauigkeit) auf.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Flutterwave Payment 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 und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Flutterwave-Zahlungsdaten und Erstattungen von Bestellungen sowie die Bestellstatus Awaiting Flutterwave payment und Flutterwave 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.

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