VibeFox PayFast 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: Südafrikanischer Rand (ZAR). PayFast rechnet nur in Rand ab, daher muss der Warenkorb in ZAR sein. Fügen Sie die Währung unter International > Localization > Currencies hinzu, falls Ihr Shop sie noch nicht hat. Der Mindestbestellwert beträgt R5,00.

PayFast-Konto: Merchant ID und Merchant Key Ihres PayFast-Kontos, zu finden unter Settings > Developer Settings im PayFast-Dashboard. Eine Passphrase wird dringend empfohlen; wenn in PayFast eine festgelegt ist, muss dieselbe Passphrase im Modul eingetragen werden. Für Tests benötigen Sie die Zugangsdaten der PayFast-Sandbox.

Erreichbarer Shop: Die URL für Zahlungsbenachrichtigungen muss aus dem Internet erreichbar sein, ohne Basic Auth oder Firewall-Sperre.

VibeFox-Lizenzschlüssel: erhältlich 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 PayFast 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 Merchant ID, Merchant Key und Passphrase ein. Lassen Sie zum Testen Test mode eingeschaltet und tragen Sie Ihre Sandbox-Zugangsdaten ein.

5. Schalten Sie Enable/Disable ein und klicken Sie auf Save. Führen Sie eine Testzahlung durch und schalten Sie dann Test mode aus, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting PayFast payment und PayFast payment on hold. PrestaShop aktiviert ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können das unter Payment > Preferences einschränken; achten Sie darauf, dass das Modul für den Rand erlaubt bleibt.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn die Zugangsdaten des aktuellen Modus leer sind (PayFast wird dann an der Kasse ausgeblendet), wenn die Standard-Shopwährung nicht ZAR ist, wenn der Live-Modus die öffentliche Sandbox-Merchant-ID 10000100 verwendet und wenn keine Passphrase gesetzt ist. Solange der Testmodus eingeschaltet und das Modul aktiviert ist, wird angezeigt: Der Testmodus ist eingeschaltet: Bestellungen werden in der PayFast-Sandbox bezahlt, es wird kein echtes Geld abgebucht. Ein leeres Feld Title wird mit Bitte geben Sie einen Titel für die Zahlungsart ein. abgelehnt.

PayFast

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

Title: Der Name der Zahlungsart, den der Kunde an der Kasse sieht. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: PayFast. Pflichtfeld.

Description: Der Text unter der Zahlungsart an der Kasse. Standard: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

PayFast-Konto (Live)

Merchant ID und Merchant Key finden Sie im PayFast-Dashboard unter Settings > Developer Settings. Wenn Sie dort eine Passphrase festgelegt haben, geben Sie hier genau dieselbe Passphrase ein.

Merchant ID: Ihre Live-Merchant-ID bei PayFast.

Merchant Key: Ihr Live-Merchant-Key bei PayFast. Er wird mit jedem Zahlungsformular an PayFast gesendet, daher ist es ein normales Textfeld.

Passphrase: Die Salt-Passphrase von PayFast unter Settings > Developer Settings. Dringend empfohlen: Sie signiert Zahlungen und Benachrichtigungen.

Sandbox (Testmodus)

Im Testmodus gehen Zahlungen an die PayFast-Sandbox, und es wird kein echtes Geld abgebucht. Die Sandbox-Zugangsdaten werden angezeigt, nachdem Sie sich in der PayFast-Sandbox angemeldet haben (der öffentliche Test-Händler ist 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Solange er eingeschaltet ist, sieht der Kunde unter der Zahlungsart: TESTMODUS: Zahlungen gehen an die PayFast-Sandbox, es wird kein echtes Geld abgebucht. Standard: ein.

Sandbox Merchant ID: die Merchant ID Ihres Sandbox-Kontos.

Sandbox Merchant Key: der Merchant Key Ihres Sandbox-Kontos.

Sandbox Passphrase: nur, wenn in Ihrem Sandbox-Konto eine Passphrase gesetzt ist.

Gespeicherte Passphrasen 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 passphrases: Markieren Sie Passphrase oder Sandbox Passphrase und klicken Sie auf Save, um sie zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsbenachrichtigungen (ITN)

Notification URL: PayFast bestätigt jede Zahlung mit einer Server-zu-Server-Benachrichtigung an die hier angezeigte URL. Mit schönen URLs sieht sie so aus: https://your-shop/module/wcp_payfast_pay/itn, gegebenenfalls mit dem Sprachcode der Standardsprache. Die Adresse wird bei jeder Zahlung mitgesendet, bei PayFast muss also nichts eingerichtet werden; sie muss aber aus dem Internet erreichbar sein. Bestellungen werden nur durch diese geprüften Benachrichtigungen angelegt; kehrt der Kunde in den Shop zurück, entsteht oder bezahlt er dadurch keine Bestellung.

Source check: Live-Benachrichtigungen werden nur von PayFast-Servern akzeptiert. Die Adressen stammen aus den DNS-Einträgen von PayFast (6 Stunden zwischengespeichert) und den dokumentierten Adressbereichen von PayFast. Schalten Sie die Prüfung nur aus, wenn Ihr Shop hinter einem Proxy oder einer CDN liegt, der die Besucheradresse verbirgt. Signatur und Serverbestätigung werden immer geprüft. Sandbox-Benachrichtigungen werden nicht anhand der Adresse geprüft. Standard: ein.

Erweitert

Debug log: protokolliert die Schritte der Zahlung in logs/payfast_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über den Webbrowser öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn der Schalter aus ist. Es werden keine Passphrasen oder Kundendaten geschrieben. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Uninstall: Delete the gateway settings when the module is uninstalled (Einstellungen, zwischengespeicherte PayFast-Adressen und Protokoll). PayFast-Zahlungsdatensätze, Bestellungen und Bestellstatus bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig PayFast) und bestätigt. Eine Seite mit Vielen Dank für Ihre Bestellung. Sie werden zu PayFast weitergeleitet, um die Zahlung abzuschließen. sendet das signierte Zahlungsformular automatisch an PayFast. Geht der Browser nicht von selbst weiter, klickt der Kunde auf Pay with PayFast; Cancel führt zurück zur Kasse. Das Formular enthält den Warenkorbbetrag in ZAR, Cart # mit der Warenkorbnummer, Name und E-Mail-Adresse des Kunden, die Zahlungsreferenz (Warenkorbnummer und Versuch) sowie ein zufälliges Token des Versuchs. Zu diesem Zeitpunkt existiert noch keine Bestellung. Jeder neue Versuch erhält eine neue Referenz und ein neues Token.

Auf der PayFast-Seite bezahlt der Kunde per Karte, Instant EFT oder einer anderen Methode Ihres PayFast-Kontos. PayFast sendet danach die Zahlungsbenachrichtigung (ITN) an Ihren Shop. Die Bestellung wird erst als bezahlt markiert, wenn PayFast die Zahlung mit einer Benachrichtigung bestätigt, die alle Prüfungen besteht:

Benachrichtigungen für denselben Warenkorb werden nacheinander verarbeitet. Wird gerade eine andere Benachrichtigung für denselben Warenkorb verarbeitet, erhält PayFast eine Fehlerantwort und sendet die Benachrichtigung erneut. Die Benachrichtigungs-URL funktioniert auch im Wartungsmodus des Shops und wird nicht von der Länderbeschränkung Ihres Shops blockiert.

Kehrt der Kunde zurück und existiert die Bestellung, wird die übliche Bestellbestätigungsseite angezeigt. Hat PayFast die Zahlung als ausstehend gemeldet, steht dort: PayFast bestätigt Ihre Zahlung. Sie erhalten eine E-Mail, sobald sie bestätigt ist – eine erneute Zahlung ist nicht nötig. Ist die Bestellung in der Prüfung, steht dort: Ihre Zahlung wird geprüft. Wir melden uns, falls noch etwas benötigt wird. Ist eine ausstehende Zahlung später fehlgeschlagen, steht dort: Ihre PayFast-Zahlung wurde nicht abgeschlossen. Bitte kontaktieren Sie uns zu dieser Bestellung. Ist die Benachrichtigung noch nicht eingegangen, zeigt eine Seite Payment confirmation, dass PayFast die Zahlung bestätigt und die Bestellung angelegt wird, sobald PayFast sie bestätigt, mit den Schaltflächen Check again und Back to checkout.

Bricht der Kunde auf der PayFast-Seite ab, gelangt er zurück zur Kasse mit Die PayFast-Zahlung wurde abgebrochen. Sie können es erneut versuchen oder eine andere Zahlungsart wählen. Hat PayFast die Zahlung als fehlgeschlagen gemeldet, lautet die Meldung Die Zahlung wurde nicht abgeschlossen. Sie können es erneut versuchen oder eine andere Zahlungsart wählen. Der Warenkorb bleibt erhalten und kann erneut bezahlt werden.

Die Zahlungsart wird ausgeblendet, wenn die Zugangsdaten des aktuellen Modus fehlen, wenn die Warenkorbwährung nicht ZAR oder für das Modul nicht erlaubt ist oder wenn der Gesamtbetrag unter R5,00 liegt. Erreicht der Kunde die Zahlung trotzdem, erscheint eine kurze Meldung, zum Beispiel PayFast akzeptiert Zahlungen ab R5,00. Bitte wählen Sie eine andere Zahlungsart.

Das Modul nimmt nur einmalige Zahlungen in ZAR an. Es bietet keine Erstattungen über die Bestellseite, keine Abonnements, keine gespeicherten (tokenisierten) Karten und keine Split-Zahlungen.

Bestellungen

Bestellstatus

No order yet: Der Kunde wurde zu PayFast weitergeleitet und die Zahlungsbenachrichtigung ist noch nicht eingegangen, oder PayFast hat die Zahlung als fehlgeschlagen gemeldet. Es existiert nur der Warenkorb.

Payment accepted: PayFast hat die Zahlung bestätigt. Die Zahlung wird mit der PayFast-Zahlungs-ID als Transaktions-ID verbucht, und eine Notiz zeigt die Zahlungs-ID. Eine Sandbox-Zahlung erhält die Notiz, dass kein echtes Geld abgebucht wurde.

Awaiting PayFast payment: PayFast hat die Zahlung als ausstehend gemeldet. Die Bestellung wechselt zu Payment accepted, sobald PayFast sie abschließt.

Payment error: Eine ausstehende Zahlung ist fehlgeschlagen. Schließt PayFast sie später ab, wird die Bestellung zu Payment accepted.

PayFast payment on hold: Der bezahlte Betrag weicht von der Warenkorbsumme ab oder der Warenkorb ist nicht in ZAR; eine Zahlung ging für eine Bestellung ein, die storniert wurde oder deren Zahlungsart nicht mehr PayFast ist; oder eine Sandbox-Zahlung ging ein, während die Schnittstelle im Live-Modus ist. Der von PayFast erhaltene Betrag wird in der Bestellung festgehalten (nicht bei einer Sandbox-Zahlung), und die Notiz erklärt den Fall. Prüfen Sie die Bestellung und Ihr PayFast-Dashboard und setzen Sie die Bestellung dann auf Payment accepted oder stornieren Sie sie und erstatten Sie die Zahlung in PayFast.

Eine wiederholte Benachrichtigung zur selben Zahlung ändert nichts. Verspätete Benachrichtigungen über Fehlschlag oder Ausstehen ändern eine bezahlte Bestellung nie. Geht eine weitere abgeschlossene Zahlung für eine bereits bezahlte Bestellung ein, bittet eine Notiz darum, das Duplikat in PayFast zu erstatten. Eine Zahlung zu einer erstatteten Bestellung fügt nur eine Notiz hinzu.

PayFast-Zahlungsblock

Die Bestellseite zeigt einen Block PayFast payment mit der Zahlungsreferenz (m_payment_id), der PayFast-Zahlungs-ID, der Umgebung (live oder sandbox), dem Status, den Beträgen brutto, Gebühr und netto in ZAR sowie den Hinweisen des Moduls. Bei einer Bestellung in der Prüfung erscheint eine Erinnerung, die Zahlung zu prüfen.

Erstattungen

Erstattungen über die Bestellseite werden nicht unterstützt. Erstatten Sie die Zahlung in Ihrem PayFast-Dashboard und aktualisieren Sie danach die Bestellung in PrestaShop manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox PayFast Pay Gateway ist der erste Block auf Modules > Module Manager > VibeFox PayFast Pay Gateway > 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 gültig 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-payfast und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeitende 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 gilt für eine Domain: die Domain des Hauptshops, auch bei 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 PayFast 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 an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird während der 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. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

PayFast wird an der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, Merchant ID und Merchant Key des aktuellen Modus ausgefüllt sind, der Warenkorb in ZAR ist und der Bestellbetrag mindestens R5,00 beträgt. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt. Prüfen Sie unter Payment > Preferences, ob das Modul für den Rand, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: PayFast konnte die Zahlungsbenachrichtigung nicht zustellen oder sie wurde abgelehnt. Sehen Sie im Feld Log auf der Modulseite nach; Fehler und abgelehnte Benachrichtigungen werden immer protokolliert, und Debug log ergänzt jeden Schritt. Typische Ursachen: Der Shop ist aus dem Internet nicht erreichbar (Basic Auth, Firewall), eine andere Passphrase in PayFast und im Modul oder, im Live-Modus hinter einem Proxy oder einer CDN, die Herkunftsprüfung. Schalten Sie dann Source check aus.

Die Benachrichtigung antwortet Invalid signature: Die Passphrase im Modul ist nicht die, die in PayFast für den Modus gesetzt ist, in dem die Zahlung erfolgte.

Die Benachrichtigung antwortet Invalid source: Die Benachrichtigung stammt nicht von einer PayFast-Adresse, oder ein Proxy bzw. eine CDN verbirgt die echte Adresse. Schalten Sie Source check aus, wenn Ihr Shop hinter einem Proxy oder einer CDN liegt.

Die Benachrichtigung antwortet Merchant mismatch oder Order mismatch: Die Zahlung wurde an ein anderes PayFast-Konto gerichtet oder gehört nicht zu diesem Zahlungsversuch. Es wird nichts geändert.

Die Benachrichtigung antwortet Order not found: Die Zahlungsreferenz ist diesem Shop unbekannt. Es wird nichts geändert.

Die Benachrichtigung antwortet Confirmation unavailable, Busy oder Temporary error: PayFast war für die Serverbestätigung nicht erreichbar, eine andere Benachrichtigung für denselben Warenkorb wurde gerade verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). PayFast wiederholt die Benachrichtigung. Das Protokoll zeigt den Grund.

Die Benachrichtigung antwortet Not configured: Die Zugangsdaten des Modus, in dem die Zahlung gestartet wurde, fehlen. Tragen Sie sie erneut ein, zum Beispiel die Sandbox-Zugangsdaten für eine Testzahlung.

Der Kunde sieht die Meldung PayFast akzeptiert nur Zahlungen in südafrikanischen Rand (ZAR): Der Warenkorb ist in einer anderen Währung. Lassen Sie den Kunden in Rand zahlen oder eine andere Zahlungsart wählen.

Bestellung ist PayFast payment on hold: Lesen Sie die Notizen im Block PayFast payment (siehe Bestellstatus) und Ihr PayFast-Dashboard und nehmen Sie die Bestellung dann an oder erstatten Sie die Zahlung.

Eine Sandbox-Zahlung hat die Bestellung nicht bezahlt: Die Schnittstelle ist im Live-Modus. Sandbox-Zahlungen bezahlen im Live-Modus nie eine Bestellung; eine Notiz an der Bestellung weist darauf hin.

Für Entwickler: Der Hook actionPayfastPPaymentData kann die Felder des Zahlungsformulars ändern, bevor sie signiert werden. Händlerzugangsdaten, URLs, Zahlungsreferenz, Betrag und Token können damit nicht geändert werden.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox PayFast Pay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete the gateway settings when the module is uninstalled eingeschaltet, werden die Einstellungen der Schnittstelle, die zwischengespeicherten PayFast-Adressen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die PayFast-Zahlungsdatensätze, die Bestellungen und die Bestellstatus Awaiting PayFast payment und PayFast payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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