VibeFox Flutterwave for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer. Unter älteren PHP-Versionen lässt sich das Plugin nicht aktivieren.

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. Nur die geheimen Schlüssel werden verwendet. Öffentliche Schlüssel und Verschlüsselungsschlüssel sind nicht erforderlich. Richten Sie außerdem einen Webhook mit einem geheimen Hash Ihrer Wahl ein (siehe Konfiguration).

Währungen: Die Bestellung wird immer in der Bestellwährung abgerechnet. Das Plugin beschränkt weder Länder noch Währungen; Flutterwave zeigt einen Fehler, wenn Ihr Konto die Währung nicht unterstützt.

VibeFox-Lizenzschlüssel: auf vibefox.net gekauft. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können den Ordner wcp_flutterwave_payment auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Flutterwave > Manage, oder klicken Sie auf der Plugin-Seite unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzbereich oben auf der Seite ein und klicken Sie auf Activate.

5. Geben Sie Ihre geheimen Schlüssel ein, richten Sie den Webhook im Flutterwave-Dashboard ein und tragen Sie denselben geheimen Hash im Plugin ein (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable, testen Sie eine Zahlung im Testmodus und aktivieren Sie dann Live mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Flutterwave. Oberhalb der Felder steht Live mode: real payments are accepted. oder Test mode: no real money is charged. Eine Warnung erscheint, wenn der geheime Schlüssel des aktuellen Modus leer ist, wenn das Live-Schlüsselfeld im Live-Modus einen Testschlüssel (FLWSECK_TEST-…) enthält oder das Testschlüsselfeld im Testmodus einen Live-Schlüssel (FLWSECK-…) enthält. Die Zahlungsmethode bleibt an der Kasse ausgeblendet, bis dies behoben ist. Eine weitere Warnung erscheint, wenn kein geheimer Webhook-Hash festgelegt ist: Webhooks werden dann abgewiesen und Zahlungen nur bestätigt, wenn der Kunde zum Shop zurückkehrt. In der Liste der Zahlungsmethoden wird Flutterwave als einrichtungsbedürftig markiert, bis für den aktuellen Modus ein geheimer Schlüssel vorliegt; im Testmodus erscheint ein Testmodus-Abzeichen.

Allgemein

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

Title: der Titel der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Flutterwave.

Description: der Text, den Kunden an der Kasse 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. Testmodus und Live-Modus haben unterschiedliche Schlüssel.

Live mode: Accept real payments (uncheck for test mode). Der Testmodus verwendet den geheimen Testschlüssel und belastet kein echtes Geld. Der Live-Modus verwendet den geheimen Live-Schlüssel. Standard: off (Testmodus).

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

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

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 in diesem Abschnitt angezeigte Webhook URL und einen geheimen Hash Ihrer Wahl ein, sowohl im Testmodus als auch im Live-Modus. Die URL hat die Form https://your-site/wc-api/flw_p_webhook/. Das Plugin reagiert auf dieses Ereignis:

Andere Ereignisse werden ignoriert.

Secret Hash: der geheime Webhook-Hash. Er muss dem Wert in den Webhook-Einstellungen Ihres Flutterwave-Dashboards entsprechen. Flutterwave sendet ihn mit jedem Webhook. Webhooks ohne gültigen geheimen Hash werden abgewiesen. Ohne Webhook wird eine Zahlung nur bestätigt, wenn der Kunde zu Ihrem Shop zurückkehrt.

Zahlung

Payment Options: durch Kommas getrennte Zahlungsmethoden, die auf der Flutterwave-Seite angezeigt werden sollen, etwa card, banktransfer, ussd, mobilemoney. Lassen Sie das Feld leer, um alle in Ihrem Konto aktivierten Methoden anzuzeigen. Die Liste wird beim Speichern bereinigt.

Autocomplete Orders: Automatically mark orders as completed after successful payment. Bei Aktivierung werden Bestellungen nach der Zahlung mit einem einzigen Statuswechsel auf Abgeschlossen statt In Bearbeitung gesetzt. Standard: off.

Erweitert

Debug log: Log Flutterwave API events for debugging unter WooCommerce > Status > Logs, Quelle wcp_flutterwave_payment. Fehler werden immer protokolliert. Schlüssel und Kundendaten werden nie protokolliert. Standard: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Das Deaktivieren des Plugins löscht nie etwas. In Bestellungen gespeicherte Zahlungsdaten bleiben immer erhalten. Standard: off.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Flutterwave) und gibt die Bestellung auf. Im Testmodus zeigt die Kasse TEST MODE - no real payments will be processed. Eine gültige Rechnungs-E-Mail-Adresse ist erforderlich. Das Plugin erstellt eine Flutterwave-Zahlung über den Bestellgesamtbetrag in der Bestellwährung, mit E-Mail-Adresse, Telefonnummer und Name des Kunden sowie Name und Logo Ihrer Website, und leitet den Kunden zur Flutterwave-Kassenseite weiter. Dort bezahlt er mit einer in Ihrem Konto aktivierten Methode (oder einer in Payment Options aufgeführten).

Nach der Zahlung kehrt der Kunde zu Ihrem Shop zurück. Die Bestellung wird erst nach Bestätigung durch Flutterwave als bezahlt markiert: durch den Webhook oder eine serverseitige Prüfung bei der Rückkehr. Ist die Zahlung noch nicht bestätigt, etwa eine ausstehende Banküberweisung, USSD- oder Mobile-Money-Zahlung, zeigt die Bestelleingangsseite Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Ist das Geld eingegangen, das Plugin hat die Bestellung aber zur Prüfung auf In Wartestellung gesetzt, etwa weil der bezahlte Betrag nicht zur Bestellung passt, zeigt die Seite Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Wird die Zahlung abgelehnt, kehrt der Kunde zur Kasse (oder zur Seite Pay for order) zurück und sieht Your payment was declined. You can try again or choose another payment method. Bricht er auf der Flutterwave-Seite ab, wird eine an der Kasse aufgegebene Bestellung storniert, eine manuell erstellte Bestellung bleibt unbezahlt und die Meldung lautet 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.

Ein Kunde kann eine unbezahlte Bestellung erneut bezahlen. Jeder Versuch hat eine eigene Referenz. Auch ein älterer Zahlungslink, der später bezahlt wird, wird akzeptiert. Kann Flutterwave die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

Die Zahlungsmethode funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel. Die an Kunden gerichteten Texte sind ins Französische übersetzt.

Das Plugin akzeptiert nur Einmalzahlungen. Es bietet keine eingebettete oder modale Kasse auf Ihrer Website, keine gespeicherten Karten, Abonnements, aufgeteilten Zahlungen oder Zahlungspläne. Gehostete Zahlungslinks können nicht über die Flutterwave-API storniert werden, daher kann auch ein alter Link einer Bestellung noch bezahlt werden.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Kunde wurde zu Flutterwave weitergeleitet und hat noch nicht bezahlt, oder die Zahlung steht bei Flutterwave noch aus.

Processing or Completed: die Zahlung wurde bestätigt. Abgeschlossen wird verwendet, wenn Autocomplete Orders aktiviert ist (Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden ebenfalls auf Abgeschlossen gesetzt, wie in WooCommerce standardmäßig vorgesehen). Die Bestellnotiz zeigt Betrag, Zahlungsmethode, Flutterwave-Referenz, Transaktion und Modus. Die Transaktions-ID der Bestellung ist die Flutterwave-Referenz.

On hold after payment: der geprüfte Betrag oder die Währung passte nicht zur Bestellung, oder die Zahlung ging nach deren Stornierung ein. Die Notiz erklärt den Grund. Führen Sie die Bestellung aus oder erstatten Sie die Zahlung. Eine erstattete oder stornierte Bestellung wird durch einen erneut gesendeten Webhook nie wieder geöffnet.

Failed: Flutterwave meldete den letzten Zahlungsversuch einer ausstehenden Bestellung als fehlgeschlagen oder abgebrochen. Die Notiz zeigt den Grund.

Cancelled: der Kunde brach auf der Flutterwave-Seite ab, nachdem er die Bestellung an der Kasse aufgegeben hatte, oder die Bestellung wurde durch Sie oder den Ablauf der WooCommerce-Bestandsreservierung storniert.

Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, wird die Bestellung nicht geändert. Eine Notiz fordert Sie auf, die doppelte Zahlung im Flutterwave-Dashboard zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Flutterwave. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird mit dem geheimen Schlüssel des Modus gesendet, in dem die Zahlung erfolgte (Test oder Live); dieser Schlüssel muss daher hinterlegt sein. Lehnt Flutterwave die Erstattung ab, zeigt WooCommerce den Fehler und erfasst keine Erstattung. Eine erfolgreiche Erstattung wird mit Erstattungs-ID und Status in den Bestellnotizen vermerkt (abgeschlossen oder eingeleitet mit dem von Flutterwave gemeldeten Status).

Erstattungen im Flutterwave-Dashboard werden nicht mit WooCommerce synchronisiert. Erstellen Sie bei Bedarf eine manuelle Erstattung in WooCommerce ohne Refund via Flutterwave.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich steht oben unter WooCommerce > Settings > Payments > Flutterwave. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Bereich zeigt den Status, etwa das Ablaufdatum der Lizenz und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren 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 dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin mit der Kennzeichnung (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Plugin-Seite und den WooCommerce-Seiten erscheint eine Erinnerung. Bestehende Bestellungen bleiben unberührt: Bereits gestartete Zahlungen werden weiterhin bestätigt und Erstattungen funktionieren.

Nach Ablauf einer Lizenz funktioniert das Plugin weiter, für Updates und Support ist jedoch eine Verlängerung erforderlich. Der Status wird automatisch im Hintergrund erneut geprüft.

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 eingetragen ist und zum Modus passt: ein Testschlüssel (FLWSECK_TEST-…) im Testmodus, ein Live-Schlüssel (FLWSECK-…) im Live-Modus. Andernfalls zeigt die Einstellungsseite eine Warnung.

Die Zahlung erfolgte, aber die Bestellung bleibt auf Pending payment: Der Webhook funktioniert nicht. Prüfen Sie im Flutterwave-Dashboard, ob die Webhook-URL exakt der in den Einstellungen angezeigten entspricht, im verwendeten Modus (Test oder Live), und ob der geheime Hash mit Secret Hash im Plugin übereinstimmt. Ausstehende Banküberweisungen, USSD- und Mobile-Money-Zahlungen bleiben ausstehend, bis Flutterwave sie bestätigt. Aktivieren Sie Debug log und öffnen Sie WooCommerce > Status > Logs, Quelle wcp_flutterwave_payment.

Der Webhook antwortet mit Invalid hash oder Secret hash not configured: Der geheime Hash im Flutterwave-Dashboard weicht vom Plugin ab, oder im Plugin fehlt er. Tragen Sie an beiden Stellen denselben Wert ein.

Der Webhook antwortet mit Verification failed oder Busy, retry later: Flutterwave konnte zur Zahlungsprüfung nicht erreicht werden, die Transaktion ist noch nicht sichtbar oder eine andere Anfrage aktualisierte gerade die Bestellung. Flutterwave wiederholt den Webhook.

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ückkehrlink enthält eine Referenz, die dieser Shop nicht erstellt hat. Wurde der Kunde belastet, suchen Sie die Zahlung im Flutterwave-Dashboard.

Flutterwave zeigt auf seiner Seite einen Fehler: Ihr Flutterwave-Konto unterstützt möglicherweise die Bestellwährung oder die gewählten Zahlungsoptionen nicht.

Die Bestellung steht nach der Zahlung auf On hold: Lesen Sie die Bestellnotiz. Der geprüfte Betrag oder die Währung passte nicht zur Bestellung, oder die Zahlung ging nach deren Stornierung ein. Führen Sie die Bestellung aus oder erstatten Sie die Zahlung.

Die Erstattung scheitert mit einer Meldung zum Modus: Die Zahlung erfolgte im Test- oder Live-Modus, dessen geheimer Schlüssel nicht konfiguriert ist. Tragen Sie ihn ein und versuchen Sie es erneut.

Der Lizenzbereich zeigt einen Fehler: Folgen Sie der Meldung im Bereich. Wird der Schlüssel etwa bereits auf einer anderen Domain verwendet, geben Sie einen Platz in Ihrem vibefox.net-Konto frei und klicken Sie auf Check now. Hat sich die Website-Adresse geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Für Entwickler führt die Plugin-Dokumentation die Filter flw_p_payment_request (an Flutterwave gesendete Daten), flw_p_currency_decimals (Währungsgenauigkeit) und flw_p_icon (Kassensymbol) auf.

Deinstallation

Beim Deaktivieren des Plugins bleiben alle Daten erhalten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen und Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. In Bestellungen gespeicherte Flutterwave-Daten bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Flutterwave ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist weder mit Flutterwave verbunden noch von Flutterwave empfohlen.