VibeFox Pesapal 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: Der Warenkorb muss in KES, UGX, TZS, ZMW, RWF oder USD sein. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet. Der Warenkorb wird in seiner eigenen Währung berechnet; das Modul 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-Konto: Sie benötigen den Consumer Key und das Consumer Secret eines Pesapal-Händlerkontos. Sandbox- und Live-Schlüssel sind verschieden. Sandbox-Schlüssel stammen aus einem Demo-Händlerkonto auf cybqa.pesapal.com (Pesapal veröffentlicht außerdem Demo-Schlüssel in seinem Entwicklerportal). Live-Schlüssel stammen aus Ihrem Pesapal-Händler-Dashboard. Im Pesapal-Dashboard muss sonst nichts eingerichtet werden: Das Modul registriert seine Benachrichtigungs-URL selbst. Ihr Shop muss aus dem Internet erreichbar sein, weil Pesapal ihm Zahlungsbenachrichtigungen sendet.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer 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. Nach dem Hochladen klicken Sie auf Configure oder suchen später VibeFox Pesapal Pay Gateway in der Modulliste und klicken 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 den Sandbox-Consumer-Key und das Sandbox-Consumer-Secret ein, aktivieren Sie Enable/Disable, klicken Sie auf Save und führen Sie eine Testbestellung durch.

5. Geben Sie den Live-Consumer-Key und das Live-Consumer-Secret ein, deaktivieren Sie Sandbox mode und klicken Sie auf Save, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul den Bestellstatus Pesapal payment on hold an. PrestaShop aktiviert das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt ein Hinweis den Modus an: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. oder LIVE — 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. bzw. entsprechend für Live) und wenn Pesapal die Standardwährung Ihres Shops nicht unterstützt.

Pesapal

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

Title: Der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Pesapal (M-Pesa, Airtel Money, cards). Pflichtfeld: Ein leerer Titel wird nicht gespeichert, der bisherige bleibt erhalten.

Description: Der Text, der unter der Zahlungsart an der Kasse angezeigt wird. 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

Dieser Abschnitt erklärt, wo Sie die Schlüssel erhalten, und verlinkt auf cybqa.pesapal.com und pesapal.com. Geben Sie die Sandbox- und die Live-Schlüssel jeweils in ein eigenes Feld ein.

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

Sandbox consumer key: Der Consumer Key Ihres Sandbox-(Demo-)Händlerkontos. 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 verwendet, wenn der Sandbox-Modus deaktiviert ist.

Live consumer secret: Das Consumer Secret aus Ihrem Pesapal-Händler-Dashboard. Wird verwendet, wenn der Sandbox-Modus deaktiviert ist.

Gespeicherte Schlüssel und Secrets werden nie erneut angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved consumer keys and secrets: Setzen Sie das Häkchen und klicken Sie auf Save, um alle vier gespeicherten Schlüssel und Secrets zu entfernen.

Beim Speichern der Einstellungen werden die zwischengespeicherten Pesapal-Zugriffstoken verworfen. Ein Moduswechsel oder eine Schlüsseländerung verwendet nie ein Zugriffstoken oder eine Benachrichtigungs-ID des anderen Modus oder anderer Schlüssel. Eine im einen Modus gestartete Zahlung wird immer in diesem Modus geprüft, auch nach einem Wechsel.

Zahlungsbenachrichtigungen (IPN)

IPN URL: zeigt die Benachrichtigungs-URL Ihres Shops. Mit lesbaren URLs sieht sie so aus: https://your-shop/module/wcp_pesapal_pay/webhook, eventuell mit einem Sprachcode wie /en/. Die URL wird bei der ersten Zahlung automatisch bei Pesapal registriert, getrennt für Sandbox und Live und für jedes Schlüsselpaar, daher ist nichts zu konfigurieren. Nach der ersten Zahlung zeigt der Abschnitt Registered IPN ID: mit der ID, die Pesapal zurückgegeben hat; davor steht dort Not registered yet for the current mode and keys. Die URL muss aus dem Internet erreichbar sein: keine Firewall und kein Passwortschutz davor. Sie funktioniert auch im Wartungsmodus des Shops und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Erweitert

Debug log: Log Pesapal requests and notifications. Schreibt Details in logs/pesapal_p_debug.log.php im Modulordner. Die Datei ist aus dem Web nicht aufrufbar. Fehler und Warnungen werden immer protokolliert, auch wenn der Schalter aus ist. Schlüssel, Token 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: Delete the module settings and logs when the module is uninstalled. Pesapal-Daten, die bei Bestellungen gespeichert sind (Tracking-IDs, Notizen), gehören zur Zahlungshistorie und bleiben immer erhalten. Das Deaktivieren des Moduls löscht nichts. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Pesapal (M-Pesa, Airtel Money, cards)) und sieht deren Beschreibung. Nach der Bestätigung legt das Modul eine Pesapal-Zahlungsanforderung über die Warenkorbsumme in der Warenkorbwährung an, mit den Rechnungsdaten der Rechnungsadresse, und leitet den Kunden zur Pesapal-Zahlungsseite weiter. Die an Pesapal gesendete Zahlungsbeschreibung lautet Cart, die Warenkorbnummer und der Shopname. Dort bezahlt der Kunde mit einer der von Pesapal angebotenen Methoden, etwa M-Pesa, Airtel Money, MTN, Karte oder Bank. Zu diesem Zeitpunkt gibt es noch keine Bestellung.

Die Bestellung wird erst als bezahlt markiert, nachdem Pesapal die Zahlung bestätigt hat. Pesapal-Benachrichtigungen und die Rückkehr des Kunden enthalten keine Zahlungsdaten und keine Signatur, daher vertraut das Modul ihnen nicht: Bei jeder davon fragt es den Transaktionsstatus bei Pesapal mit einer authentifizierten Anfrage zwischen Servern ab, im Modus, in dem die Zahlung gestartet wurde. Außerdem prüft es, dass die Transaktion zu diesem Warenkorb gehört und dass der gezahlte Betrag und die Währung zum Warenkorb passen. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite.

Mobile-Money-Zahlungen können einen Moment dauern. Hat Pesapal die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt, zeigt eine Seite Payment confirmation die Meldung 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. mit den Schaltflächen Check again und Back to checkout. Die Benachrichtigung von Pesapal legt die Bestellung an, sobald die Zahlung bestätigt ist. Wurde die Bestellung auf Wartestellung gesetzt, zeigt die Bestätigungsseite 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 Kasse zurück und sieht 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 Warenkorb bleibt erhalten, und der Kunde kann erneut zahlen. Jeder Zahlungsversuch des Warenkorbs wird gespeichert, daher wird auch eine später auf einer älteren Pesapal-Seite des Warenkorbs getätigte Zahlung akzeptiert.

Kann Pesapal die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen 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 Grund von Pesapal. Der technische Grund wird ins Protokoll geschrieben. Die Bestellsumme muss größer als null sein.

Das Modul bietet kein Zahlungsformular auf Ihrer eigenen Website (der Kunde bezahlt immer auf der Pesapal-Seite), keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen und keine Währungsumrechnung.

Bestellungen und Erstattungen

Bestellstatus

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

Payment accepted: Pesapal meldet die Zahlung als „Completed“, und Betrag und Währung stimmen überein. Die Zahlung wird mit der Pesapal-Tracking-ID als Transaktions-ID erfasst; eine Notiz zeigt Betrag, Zahlungsart, den Pesapal-Bestätigungscode und die Tracking-ID. Jede Zahlung wird nur einmal verbucht.

Pesapal payment on hold: Der gezahlte Betrag oder die Währung weicht vom Warenkorb ab (Notiz Pesapal amount/currency mismatch — held for review), oder Geld ist für eine stornierte Bestellung eingegangen. Der tatsächlich gezahlte Betrag wird bei der Bestellung erfasst, wenn er in der Bestellwährung vorliegt. Prüfen Sie die Zahlung im Pesapal-Dashboard und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

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

Wird ein zweiter Zahlungsversuch eines bereits bezahlten Warenkorbs 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.

Pesapal-Zahlungsblock

Die Bestellseite zeigt einen Block Pesapal payment mit einem Hinweis Sandbox oder Live, der Tracking-ID, der Händlerreferenz, dem Pesapal-Status, der Zahlungsart, dem Bestätigungscode, dem angeforderten und dem gezahlten Betrag, dem Grund für eine Prüfung, allen Payment attempts des Warenkorbs und den Payment notes der Bestellung. Der Block ist nur lesbar.

Erstattungen

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

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Pesapal Pay Gateway ist der erste Block auf Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure, über den Einstellungen. Fügen 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung 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-pesapal 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. 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-Installation. 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 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. Der PrestaShop-Storefront weiß nicht, dass Sie im Back-Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Benachrichtigungen von Pesapal zu bestehenden Zahlungen, einschließlich Rückbuchungen, werden weiterhin angewendet.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back-Office arbeiten: 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

Pesapal erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der Consumer Key und das 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 Warenkorbwährung KES, UGX, TZS, ZMW, RWF oder USD ist. Die Warnungen oben in den Einstellungen nennen das Problem. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe zugelassen ist. Entwickler können die Währungsliste mit dem Hook actionPesapalSupportedCurrencies ändern.

Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: Die Benachrichtigung von Pesapal hat Ihren Shop nicht erreicht, und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob die unter IPN URL angezeigte URL aus dem Internet erreichbar ist (keine Firewall und kein Passwortschutz davor). Aktivieren Sie Debug log und sehen Sie im Feld Log auf der Modulseite nach.

Wie der Shop auf Benachrichtigungen antwortet: Eine verarbeitete Benachrichtigung wird mit HTTP 200 beantwortet. Kann das Modul sie nicht verarbeiten, antwortet es mit einem Fehler, und Pesapal sendet die Benachrichtigung später erneut: 400 (fehlende oder fehlerhafte Tracking-ID), 404 (kein Warenkorb dieses Shops hat diese Tracking-ID), 409 (die Transaktion gehört zu einer anderen Händlerreferenz; nichts wird geändert), 502 (die Pesapal-API war in diesem Moment nicht erreichbar, oder die Schlüssel des Modus, in dem die Zahlung gestartet wurde, fehlen) und 503 (der Warenkorb wurde gerade durch die Rückkehr des Kunden aktualisiert, oder die Bestellung konnte nicht angelegt werden, zum Beispiel weil das Modul deaktiviert ist).

Der Kunde sieht Pesapal is not available at the moment: Pesapal hat den Consumer Key oder das Consumer Secret des aktuellen Modus abgelehnt. Prüfen Sie, ob die Schlüssel zum Modus passen: Sandbox-Schlüssel funktionieren nur mit der Sandbox, Live-Schlüssel nur im Live-Modus. Das Protokoll zeigt den Fehler von Pesapal.

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

Zahlungen eines früheren Modus werden nach dem Wechsel nicht bestätigt: Eine Zahlung wird mit den Schlüsseln des Modus geprüft, in dem sie gestartet wurde. Lassen Sie die Schlüssel dieses Modus eingetragen, bis dessen Zahlungen bestätigt sind.

Bestellung ist nach der Zahlung auf Pesapal payment on hold: Lesen Sie die Notizen im Block Pesapal payment. Der gezahlte Betrag oder die Währung wich vom Warenkorb ab, oder die Zahlung kam an, nachdem die Bestellung storniert worden war. Prüfen Sie die Zahlung im Pesapal-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Pesapal Pay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Die zwischengespeicherten Pesapal-Zugriffstoken und die registrierten Benachrichtigungs-IDs werden immer entfernt. Ist Delete data aktiviert, werden auch die Moduleinstellungen und das Protokoll gelöscht. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Pesapal-Zahlungsversuche und der Bestellstatus Pesapal payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und Pesapal-Tracking-IDs.

Pesapal ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu Pesapal und wird von Pesapal nicht unterstützt.