VibeFox Pesapal for WooCommerce — Hilfe

Anforderungen

WordPress: 6.2 oder neuer.

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

PHP: 8.0 oder neuer.

Currency: Die Bestellung muss in KES, UGX, TZS, ZMW, RWF oder USD vorliegen. Bei anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet. Die Bestellung wird in ihrer eigenen Währung belastet; das Plugin rechnet keine Währungen um. Beträge werden in Hauptwährungseinheiten gesendet, auf die Genauigkeit der Währung gerundet (UGX und RWF ohne Dezimalstellen).

Pesapal account: Sie benötigen Consumer Key und Consumer Secret eines Pesapal-Händlerkontos. Sandbox- und Live-Schlüssel sind unterschiedlich. Sandbox-Schlüssel stammen aus einem Demo-Händlerkonto auf cybqa.pesapal.com (Pesapal veröffentlicht auch Demo-Schlüssel im Entwicklerportal). Live-Schlüssel stammen aus Ihrem Pesapal-Händler-Dashboard. Im Pesapal-Dashboard ist keine weitere Einrichtung nötig: Das Plugin registriert seine Benachrichtigungs-URL selbst. Ihre Website muss aus dem Internet erreichbar sein, weil Pesapal Zahlungsbenachrichtigungen dorthin sendet.

VibeFox license key: auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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_pesapal_pay auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

5. Geben Sie Consumer Key und Consumer Secret für die Sandbox ein, schalten Sie Enable/Disable ein, speichern Sie und führen Sie eine Testbestellung durch.

6. Geben Sie Consumer Key und Consumer Secret für Live ein, deaktivieren Sie Sandbox mode und speichern Sie, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Pesapal. Über den Feldern zeigt ein Kennzeichen den Modus: SANDBOX mit Test payments on cybqa.pesapal.com — no real money is charged. oder LIVE mit Real payments on pay.pesapal.com. Eine Warnung erscheint, wenn die Schlüssel des aktuellen Modus fehlen (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., entsprechend für Live) und wenn Pesapal Ihre Shop-Währung nicht unterstützt. In der Liste der Zahlungsmethoden wird Pesapal bei eingeschalteter Sandbox als Testmodus gekennzeichnet.

Zahlungsbenachrichtigungen (IPN)

Dieser Block zeigt die Benachrichtigungs-URL Ihres Shops. Sie sieht so aus: https://your-site/wc-api/pesapal_pay/. Die URL wird bei der ersten Zahlung automatisch bei Pesapal registriert, getrennt für Sandbox und Live sowie für jedes Schlüsselpaar; Sie müssen nichts konfigurieren. Nach der ersten Zahlung zeigt der Block Registered IPN ID: mit der von Pesapal zurückgegebenen ID; zuvor steht dort Not registered yet for the current mode and keys. Die URL muss aus dem Internet erreichbar sein: kein vorgeschalteter Wartungsmodus, keine Firewall und kein Passwortschutz.

Kasse

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

Title: Der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Pesapal (M-Pesa, Airtel Money, cards).

Description: Der Text unter der Zahlungsmethode an der Kasse. Standard: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

API-Zugangsdaten

Der Abschnitt erklärt, woher Sie die Schlüssel erhalten, und verlinkt auf cybqa.pesapal.com und pesapal.com. Geben Sie Sandbox- und Live-Schlüssel jeweils in ihre eigenen Felder ein. Alle Schlüsselfelder sind Passwortfelder.

Sandbox mode: Use the Pesapal sandbox (no real money). Bei aktivierter Option verwenden neue Zahlungen cybqa.pesapal.com mit den Sandbox-Schlüsseln. Deaktivieren Sie die Option, um echte Zahlungen auf pay.pesapal.com mit den Live-Schlüsseln anzunehmen. Standard: ein.

Sandbox consumer key: Der Consumer Key Ihres Sandbox-Händlerkontos (Demo). Wird nur im Sandbox-Modus verwendet.

Sandbox consumer secret: Das Consumer Secret Ihres Sandbox-Händlerkontos. Wird nur im Sandbox-Modus verwendet.

Live consumer key: Der Consumer Key aus Ihrem Pesapal-Händler-Dashboard. Wird bei deaktiviertem Sandbox-Modus verwendet.

Live consumer secret: Das Consumer Secret aus Ihrem Pesapal-Händler-Dashboard. Wird bei deaktiviertem Sandbox-Modus verwendet.

Beim Wechsel des Modus oder der Schlüssel werden nie Zugriffstoken oder Benachrichtigungs-IDs des anderen Modus oder anderer Schlüssel wiederverwendet. Eine in einem Modus gestartete Zahlung wird immer dort geprüft, auch nach einem Wechsel.

Erweitert

Debug log: Log Pesapal requests and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_pesapal_pay. Fehler und Warnungen werden immer protokolliert. Schlüssel, Token und Kundendaten werden nie protokolliert. Standard: aus.

Delete data: Delete the plugin settings and logs when the plugin is deleted. An Bestellungen gespeicherte Pesapal-Daten (Tracking-IDs, Notizen) sind Zahlungshistorie und bleiben immer erhalten. Das Deaktivieren des Plugins löscht nie etwas. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Pesapal (M-Pesa, Airtel Money, cards)) und gibt die Bestellung auf. Im Sandbox-Modus zeigt der Kassen-Block Sandbox mode: no real money will be charged. Das Plugin erstellt eine Pesapal-Zahlungsanforderung über die Bestellsumme in der Bestellwährung mit den Rechnungsdaten der Bestellung und fügt eine Bestellnotiz mit Modus, Betrag und Pesapal-Tracking-ID hinzu. Der Kunde wird zur Pesapal-Zahlungsseite weitergeleitet und bezahlt mit einer von Pesapal angebotenen Methode, etwa M-Pesa, Airtel Money, MTN, Karte oder Bank.

Die Bestellung wird erst nach Bestätigung durch Pesapal als bezahlt markiert. Pesapal-Benachrichtigungen und die Kundenrückkehr enthalten weder Zahlungsdaten noch eine Signatur; das Plugin vertraut ihnen daher nicht: Für jedes Ereignis fragt es den Transaktionsstatus bei Pesapal mit einer authentifizierten Anfrage zwischen Servern ab, im Modus, in dem die Zahlung gestartet wurde. Es prüft auch, ob die Transaktion zu dieser Bestellung gehört und gezahlter Betrag und Währung zur Bestellung passen.

Nach der Zahlung kehrt der Kunde zur Bestelleingangsseite zurück. Mobile-Money-Zahlungen können einen Moment dauern. Ist die Zahlung noch nicht bestätigt, zeigt die Seite Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Die Pesapal-Benachrichtigung schließt die Bestellung später ab. Wurde die Bestellung auf Wartestellung gesetzt, zeigt die Seite Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Bricht der Kunde auf der Pesapal-Seite ab, kehrt er zur Seite Pay for order zurück, mit The Pesapal payment was cancelled. You can try again or choose another payment method. Ist die Zahlung fehlgeschlagen, lautet die Meldung The Pesapal payment was not successful. Please try again or choose another payment method. Der Kunde kann dieselbe Bestellung erneut bezahlen. Jeder Zahlungsversuch der Bestellung wird gespeichert, sodass eine spätere Zahlung auf einer älteren Pesapal-Seite der Bestellung ebenfalls angenommen wird.

Kann Pesapal die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (falsche Schlüssel) oder Pesapal could not start the payment:, gefolgt vom Pesapal-Grund. Technische Details stehen in den Bestellnotizen und im Protokoll. Die Bestellsumme muss größer als null sein.

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.

Das Plugin bietet kein Zahlungsformular auf der Kassenseite selbst (der Kunde bezahlt immer auf der Pesapal-Seite), keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen und keine Währungsumrechnung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Pesapal weitergeleitet und hat noch nicht bezahlt, oder Pesapal hat die Zahlung noch nicht bestätigt.

Processing: Pesapal meldet die Zahlung als abgeschlossen und Betrag und Währung stimmen überein. Die Bestellnotiz zeigt Betrag, Zahlungsmethode, Pesapal-Bestätigungscode und Tracking-ID. Die Transaktions-ID der Bestellung ist die Pesapal-Tracking-ID. Jede Zahlung wird einmal angewendet.

On hold: Gezahlter Betrag oder Währung weichen von der Bestellung ab (Notiz Pesapal amount/currency mismatch — held for review), oder Geld ist für eine vor der Zahlung stornierte Bestellung eingegangen. Prüfen Sie die Zahlung im Pesapal-Dashboard und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

Failed: Pesapal meldet den neuesten Zahlungsversuch als fehlgeschlagen. Die Notiz nennt den Pesapal-Grund. Versucht der Kunde es auf der Seite Pay for order erneut und schlägt auch dieser Versuch fehl, wird eine weitere Notiz mit dem Grund hinzugefügt. Ein fehlgeschlagener älterer Versuch ändert die Bestellung nicht. Der Kunde kann erneut bezahlen.

Refunded: Pesapal meldet die Zahlung, mit der die Bestellung bezahlt wurde, als rückabgewickelt. Die Rückabwicklung eines anderen Versuchs wird nur an der Bestellung vermerkt.

Wird ein zweiter Zahlungsversuch einer bereits bezahlten Bestellung ebenfalls abgeschlossen, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die zweite Zahlung im Pesapal-Dashboard zu erstatten. Stornierte und erstattete Bestellungen werden nie automatisch wieder geöffnet.

Erstattungen

Das Plugin sendet keine Erstattungen an Pesapal. Erstatten Sie die Zahlung im Pesapal-Dashboard und erfassen Sie die Erstattung anschließend manuell in WooCommerce.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock steht oben auf WooCommerce > Settings > Payments > Pesapal. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, etwa das Ablaufdatum der aktiven 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 funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt den Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Pesapal Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, mit (unlicensed — visible to admins only) gekennzeichnet, damit Sie das Plugin vor dem Schlüsselkauf einrichten und testen können. Auf der Plugins-Seite und den WooCommerce-Seiten erscheint eine Erinnerung. Bestehende Bestellungen bleiben unberührt: Bereits gestartete Zahlungen werden weiterhin durch Pesapal-Benachrichtigung und Kundenrückkehr bestätigt.

Nach Ablauf einer Lizenz funktioniert das Plugin weiter, doch Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Pesapal erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv und Enable/Disable eingeschaltet ist, Consumer Key und Consumer Secret des aktuellen Modus eingegeben sind (Sandbox consumer key und Sandbox consumer secret im Sandbox-Modus, Live consumer key und Live consumer secret im Live-Modus) und die Bestellwährung KES, UGX, TZS, ZMW, RWF oder USD ist. Die Warnungen oben in den Einstellungen benennen das Problem. Entwickler können die Währungsliste mit dem Filter pesapal_p_supported_currencies ändern.

Die Zahlung war erfolgreich, aber die Bestellung bleibt auf Zahlung ausstehend: Die Pesapal-Benachrichtigung hat Ihren Shop nicht erreicht und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob die in Payment notifications (IPN) gezeigte URL aus dem Internet erreichbar ist (kein Wartungsmodus, keine Firewall und kein Passwortschutz vor /wc-api/pesapal_pay/). Sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_pesapal_pay, nach.

So beantwortet der Shop Benachrichtigungen: Eine verarbeitete Benachrichtigung wird mit HTTP 200 beantwortet. Kann das Plugin sie nicht verarbeiten, antwortet es mit einem Fehler und Pesapal sendet sie später erneut: 400 (Tracking-ID fehlt oder ist ungültig formatiert), 404 (keine Bestellung dieses Shops hat diese Tracking-ID), 409 (die Transaktion gehört zu einer anderen Händlerreferenz; die Bestellung bleibt unverändert), 502 (die Pesapal API war gerade nicht erreichbar) und 503 (die Bestellung wurde gleichzeitig durch die Kundenrückkehr aktualisiert).

Der Kunde sieht Pesapal is not available at the moment: Pesapal hat Consumer Key oder Consumer Secret des aktuellen Modus abgelehnt. Prüfen Sie, ob die Schlüssel zum Modus gehören: Sandbox-Schlüssel funktionieren nur in der Sandbox, Live-Schlüssel nur im Live-Modus. Die Bestellnotiz zeigt den Pesapal-Fehler.

Der Kunde sieht Pesapal is temporarily unavailable: Pesapal war nicht erreichbar oder die Benachrichtigungs-URL konnte nicht registriert werden. Lesen Sie die Bestellnotiz und das Protokoll und versuchen Sie es erneut.

Die Bestellung steht nach der Zahlung auf Wartestellung: Lesen Sie die Bestellnotiz. Gezahlter Betrag oder Währung wichen von der Bestellung ab, oder die Zahlung ging nach der Stornierung ein. Prüfen Sie die Zahlung im Pesapal-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wird der Schlüssel beispielsweise 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.

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, zwischengespeicherte Pesapal-Zugriffstoken und registrierte Benachrichtigungs-IDs werden immer entfernt. Die Plugin-Einstellungen und Protokolle (Protokolldateien einschließlich rotierter Dateien und Datenbank-Protokolleinträge der Quelle wcp_pesapal_pay) werden nur entfernt, wenn Delete data eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten Zahlungsnotizen, Transaktions-IDs und Pesapal-Tracking-IDs.

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