VibeFox Paystack 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 einer Währung sein, die Paystack akzeptiert: NGN, USD, GHS, ZAR, KES, XOF, EGP oder RWF, wie in Ihrem Paystack-Konto aktiviert. In anderen Währungen wird die Zahlungsmethode ausgeblendet. In XOF und RWF akzeptiert Paystack nur ganze Beträge.

Paystack-Konto: Sie benötigen die geheimen Schlüssel Ihres Paystack-Kontos: den geheimen Testschlüssel (sk_test_...) und/oder den geheimen Live-Schlüssel (sk_live_...). Die öffentlichen Schlüssel (pk_...) werden nicht benötigt, da die Zahlung auf der gehosteten Seite von Paystack erfolgt. Im Paystack-Dashboard richten Sie außerdem die Webhook-URL Ihres Shops ein (siehe Konfiguration). Ihr Shop muss aus dem Internet erreichbar sein, um Webhooks zu empfangen.

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 aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Paystack Payment in der Modulliste und klicken Sie dort auf Configure.

3. Geben 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. Fügen Sie Ihre geheimen Schlüssel aus dem Paystack-Dashboard ein und richten Sie die Webhook-URL im Paystack-Dashboard ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Lassen Sie Test Mode eingeschaltet, bis Sie eine Testzahlung durchgeführt haben, und schalten Sie es dann aus, um echte Zahlungen anzunehmen.

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

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Paystack Payment > Configure. Jeder Abschnitt mit Feldern hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt ein Statusfeld den Modus an: Testmodus: Es wird kein echtes Geld abgebucht. oder Live-Modus: Echte Zahlungen werden angenommen. Es warnt außerdem, wenn der geheime Schlüssel des aktuellen Modus leer ist, wenn ein öffentlicher Schlüssel (pk_...) in ein Feld für den geheimen Schlüssel eingetragen wurde, wenn der Live-Modus einen Testschlüssel (sk_test_...) hat oder der Testmodus einen Live-Schlüssel (sk_live_...) hat und wenn Paystack die Standardwährung Ihres Shops nicht akzeptiert. Solange ein Schlüsselproblem besteht, wird die Zahlungsmethode in der Kasse ausgeblendet.

Paystack

Der erste Abschnitt trägt die Überschrift Paystack mit einem Kennzeichen TEST oder LIVE für den aktuellen Modus.

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

Title: der Name der Zahlungsmethode, den Kunden in der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Paystack. Pflichtfeld.

Description: der Text, der in der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely using your debit card, credit card, or bank account via Paystack.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus dem Paystack-Dashboard, Seite Settings > API Keys & Webhooks. Der Abschnitt enthält einen Link dorthin.

Test Mode: verwendet den geheimen Testschlüssel für neue Zahlungen, und es wird kein echtes Geld abgebucht. Schalten Sie es aus, um echte Zahlungen mit dem geheimen Live-Schlüssel anzunehmen. Zahlungen, die im anderen Modus erfolgten, verwenden für Prüfung und Erstattungen weiterhin den Schlüssel ihres eigenen Modus. Standard: an. Solange es aktiviert ist, sehen Kunden unter der Zahlungsmethode TESTMODUS AKTIVIERT. Es werden keine echten Abbuchungen vorgenommen.

Test Secret Key: Ihr geheimer Paystack-Testschlüssel. Er beginnt mit sk_test_.

Live Secret Key: Ihr geheimer Paystack-Live-Schlüssel. Er beginnt mit sk_live_.

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.

Clear saved secrets: Setzen Sie den Haken bei einem Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Webhook

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist, auch wenn der Kunde nicht in den Shop zurückkehrt. Tragen Sie im Paystack-Dashboard auf der Seite Settings > API Keys & Webhooks die URL aus Webhook URL in diesem Abschnitt sowohl als Test Webhook URL als auch als Live Webhook URL ein. Mit SEO-freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_paystack_payment/webhook, eventuell mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen.

Paystack signiert jeden Webhook mit Ihrem geheimen Schlüssel, daher muss nichts anderes eingerichtet werden. Webhooks ohne gültige Signatur werden abgelehnt. Das Modul verwendet das Ereignis charge.success:

Andere Ereignisse werden mit OK beantwortet und ignoriert. Ohne Webhook wird eine Bestellung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt. Banküberweisungen und USSD-Zahlungen, die später abgeschlossen werden, werden nur durch den Webhook bestätigt.

Bestellungen

Autocomplete Order: Wenn aktiviert, erhalten bezahlte Bestellungen den Status Delivered statt Payment accepted, mit einer einzigen Statusänderung. Standard: aus.

Erweitert

Debug log: protokolliert Paystack-Ereignisse und API-Aufrufe in logs/paystack_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web aufgerufen werden. Fehler und Warnungen werden immer protokolliert. Schlüssel 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: Wenn aktiviert, entfernt die Deinstallation des Moduls die Moduleinstellungen und das Protokoll. Zahlungsdaten, die bei Bestellungen gespeichert wurden, bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Paystack) und bestätigt die Bestellung. Das Modul startet eine Paystack-Transaktion über die Warenkorbsumme in der Warenkorbwährung mit der E-Mail-Adresse des Kunden und leitet den Kunden zur gehosteten Zahlungsseite von Paystack weiter. Dort bezahlt der Kunde mit einem der Kanäle, die in Ihrem Paystack-Konto aktiviert sind. Die Zahlung zeigt die Warenkorbnummer und den Namen des Kunden. 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, wenn Paystack die Zahlung bestätigt: Wenn der Kunde zurückkehrt und wenn der Webhook eintrifft, liest das Modul die Transaktion über die Paystack-API aus und prüft Referenz, Status, Betrag und Währung. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite.

Wenn die Zahlung noch verarbeitet wird, zum Beispiel eine Banküberweisung, wird die Bestellung bei der Rückkehr des Kunden in Awaiting Paystack payment angelegt, und die Bestätigungsseite zeigt Ihre Zahlung wird von Paystack bestätigt. Sie erhalten eine E-Mail, sobald sie bestätigt ist. Der Webhook schließt die Bestellung später ab. Wenn Paystack bei der Rückkehr des Kunden nicht erreichbar ist, bittet eine Seite Payment confirmation den Kunden, nicht erneut zu zahlen, und bietet Check again und Back to checkout an; der Webhook legt die Bestellung an, sobald er eintrifft. Bei einer Bestellung in der Prüfung zeigt die Bestätigungsseite Ihre Zahlung ist eingegangen, und Ihre Bestellung wird geprüft. Wir melden uns, falls etwas benötigt wird.

Wenn der Kunde auf der Paystack-Seite abbricht oder sie ohne Zahlung verlässt, wird keine Bestellung angelegt und der Warenkorb bleibt erhalten. Der Kunde kehrt mit einer Meldung zur Kasse zurück, zum Beispiel Die Zahlung wurde abgebrochen. Sie können es erneut versuchen oder eine andere Zahlungsmethode wählen., Die Zahlung wurde nicht abgeschlossen. Sie können es erneut versuchen oder eine andere Zahlungsmethode wählen. oder Ihre Zahlung wurde abgelehnt. Sie können es erneut versuchen oder eine andere Zahlungsmethode wählen. Jeder neue Versuch startet eine neue Paystack-Transaktion. Eine ältere Zahlungsseite des Warenkorbs bleibt gültig: Wird sie später bezahlt, wird die Zahlung trotzdem angenommen.

Die Bestellbestätigungsseite wird nur im eigenen Browser des Kunden geöffnet. Wird der Rücksprunglink anderswo geöffnet, wird die Zahlung trotzdem geprüft, die Bestellung aber nicht angezeigt: Der Besucher sieht an der Kasse einen neutralen Hinweis.

Wenn Paystack die Zahlung nicht starten kann, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel Paystack konnte die Zahlung nicht starten: gefolgt vom Grund, den Paystack nennt, oder Paystack ist vorübergehend nicht verfügbar. Bitte versuchen Sie es in Kürze erneut oder wählen Sie eine andere Zahlungsmethode. Die Warenkorbsumme muss größer als null sein, und der Kunde braucht eine gültige E-Mail-Adresse.

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

Das Modul hat in PrestaShop kein eingebettetes oder Pop-up-Zahlungsformular, keine gespeicherten Karten, keine Abonnements, keine geteilten Zahlungen oder Subaccounts und keine Auswahl von Zahlungskanälen.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu Paystack geschickt und hat nicht bezahlt, die Paystack-Seite verlassen oder Paystack hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Awaiting Paystack payment: Der Kunde ist zurückgekehrt, während Paystack die Zahlung noch verarbeitete, zum Beispiel eine Banküberweisung oder USSD. Die Bestellung wechselt in den Status „bezahlt“, sobald Paystack die Zahlung bestätigt. Wird eine solche Zahlung nie abgeschlossen, bleibt die Bestellung in diesem Status, bis Sie ihn ändern.

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status ist Zugestellt, wenn Autocomplete Order aktiviert ist. Die Zahlung wird mit der Paystack-Referenz (pscart_...) als Transaktions-ID erfasst. Eine Notiz zeigt den Betrag, die Referenz, die Transaktionsnummer, den Modus (Test oder Live), den Zahlungskanal, den Kartentyp und die letzten Ziffern bei Kartenzahlungen sowie alle Paystack-Gebühren, die der Kunde getragen hat.

Paystack payment on hold: Der bezahlte Betrag oder die Währung weicht von der Bestellung ab (Notiz Paystack-Betrag oder Währung stimmt nicht überein), zum Beispiel weil der Warenkorb geändert wurde, nachdem die Zahlung gestartet wurde, oder weil die Zahlung eintraf, nachdem die Bestellung storniert worden war. Die Notiz erklärt, was zu prüfen ist. Bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

Zahlungsfehler: Paystack meldet den letzten Zahlungsversuch einer Bestellung im Status Awaiting Paystack payment als fehlgeschlagen oder rückgängig gemacht. Der Fehler eines älteren Versuchs ändert die Bestellung nicht.

Wenn eine zweite Zahlung für einen Warenkorb eingeht, dessen Bestellung bereits bezahlt ist, wird die Bestellung nicht geändert. Eine Notiz bittet Sie, die doppelte Zahlung im Paystack-Dashboard zu erstatten. Eine Zahlung, die für eine Bestellung in einem anderen Status eingeht, zum Beispiel Versandt, wird nur in der Bestellung vermerkt.

Paystack-Zahlungsblock

Die Bestellseite zeigt einen Block Paystack payment mit der Referenz, der Transaktions-ID, dem Modus mit dem Kennzeichen Test mode für Testzahlungen, dem Zahlungsstatus, Kanal und Karte, dem Zahlungsdatum, den bezahlten und erstatteten Beträgen, dem Erstattungsverlauf und den Payment notes der Bestellung.

Erstattungen

Geben Sie im Block Paystack payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Paystack. Bestätigen Sie die Frage Diesen Betrag über Paystack erstatten? Dies kann nicht rückgängig gemacht werden. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht erforderlich. Die Erstattung geht an die Transaktion, die die Bestellung bezahlt hat, mit dem geheimen Schlüssel des Modus (Test oder Live), in dem sie erfolgte; dieser Schlüssel muss daher eingerichtet sein. Erstattungen erfolgen in dem Betrag und der Währung, die Paystack abgebucht hat. Bei einer Bestellung in der Prüfung 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 die Bestellsumme. In XOF und RWF müssen Erstattungen ganze Beträge sein. Paystack stellt Erstattungen in die Warteschlange: Die Notiz und der Erstattungsverlauf zeigen den Status, den Paystack zurückgibt, zum Beispiel pending, sowie die Erstattungs-ID. Wenn Paystack die Erstattung nicht annimmt, zeigt der Block Paystack-Erstattung fehlgeschlagen: mit dem Grund, und es wird keine Erstattung erfasst. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Paystack die Zahlung bestätigt hat.

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

Erstattungen, die im Paystack-Dashboard vorgenommen werden, und der endgültige Status von Erstattungen, die Paystack in die Warteschlange stellt, werden nicht zurück nach PrestaShop synchronisiert. Falls nötig, erfassen Sie sie manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Paystack Payment ist der erste Block auf Modules > Module Manager > VibeFox Paystack Payment > Configure, oberhalb der Einstellungen. Geben 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, 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-paystack 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 für eine Domain: die Domain des Hauptshops, auch in 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 Paystack 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 ist 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 gestartete 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 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

Paystack erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktuelle Modus einen korrekten geheimen Schlüssel hat (Test Secret Key mit sk_test_... im Testmodus, Live Secret Key mit sk_live_... im Live-Modus) und die Warenkorbwährung eine ist, die Paystack akzeptiert. Das Statusfeld oben in den Einstellungen nennt 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.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: Der Webhook hat Ihren Shop nicht erreicht, und der Kunde ist nicht zurückgekehrt. Prüfen Sie im Paystack-Dashboard, ob die Test Webhook URL und die Live Webhook URL genau der URL unter Webhook URL entsprechen und ob keine Firewall oder Passwortschutz sie blockiert. Aktivieren Sie Debug log und sehen Sie im Feld Log nach abgelehnten Webhooks.

Der Webhook antwortet Invalid signature: Der Webhook wurde nicht mit dem geheimen Test- oder Live-Schlüssel signiert, der in den Einstellungen eingetragen ist, zum Beispiel weil die Schlüssel zu einem anderen Paystack-Konto gehören. Geben Sie die Schlüssel des Kontos ein, das den Webhook sendet.

Der Webhook antwortet Secret key not configured: Es ist kein geheimer Schlüssel gesetzt. Geben Sie die geheimen Schlüssel in den Einstellungen ein.

Der Webhook antwortet Verification failed, Busy, retry later oder Order could not be created, retry later: Die Transaktion konnte in diesem Moment nicht über die Paystack-API gelesen werden, der Warenkorb wurde gleichzeitig durch die Rückkehr des Kunden verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Paystack sendet den Webhook erneut. Das Protokoll zeigt den Grund.

Der Webhook antwortet OK - unknown reference: Die Zahlung wurde nicht für einen Warenkorb dieses Shops getätigt, zum Beispiel über eine Paystack-Zahlungsseite oder eine andere Integration auf demselben Konto. Sie wird ignoriert.

Die Webhook-URL zeigt im Browser Empty body: Das ist normal. Die URL akzeptiert nur Anfragen von Paystack.

Der Kunde sieht die Meldung „Zahlungsgateway ist nicht richtig konfiguriert“: Der geheime Schlüssel des aktuellen Modus fehlt oder ist falsch. Beheben Sie das gemäß dem Statusfeld oben in den Einstellungen.

Die Bestellung ist nach der Zahlung Paystack payment on hold: Lesen Sie die Zahlungsnotizen im Block Paystack payment (siehe Bestellstatus) und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Die Bestellung bleibt in Awaiting Paystack payment: Paystack hat die Zahlung noch nicht bestätigt. Prüfen Sie die Transaktion im Paystack-Dashboard und die Webhook-Einstellungen. Hat der Kunde die Zahlung nie abgeschlossen, ändern Sie den Status manuell.

Die 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 eingerichtet. Geben Sie ihn ein und versuchen Sie es erneut.

Entwickler können die Transaktionsanfrage und die Liste der Währungen mit den Modul-Hooks actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies und actionWcpPaystackCurrencyDecimals anpassen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Paystack 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 Paystack-Zahlungsdaten der Bestellungen, die Erstattungen und die Bestellstatus Awaiting Paystack payment und Paystack payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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