VibeFox Cashfree 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.

HTTPS: Cashfree liefert Webhooks nur an https://-URLs aus. Ohne HTTPS werden Zahlungen trotzdem bestätigt, wenn der Kunde in den Shop zurückkehrt, aber aktivieren Sie HTTPS vor dem Livebetrieb.

Cashfree-Konto: Sie benötigen App ID und Secret Key Ihres Cashfree-Kontos, jeweils getrennt für die Testumgebung (Sandbox) und die Produktivumgebung, sowie einen Webhook im Cashfree Merchant Dashboard (siehe Konfiguration). Der Secret Key wird auch zur Prüfung der Webhooks verwendet, daher gibt es kein separates Webhook-Geheimnis. Die Warenkorbwährung muss für Ihr Cashfree-Konto aktiviert sein.

VibeFox-Lizenzschlüssel: Erwerb 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 aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Cashfree Payments in der Modulliste und klicken Sie 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 die Sandbox App ID und den Sandbox Secret Key ein, legen Sie den Webhook im Cashfree Merchant Dashboard an (siehe Konfiguration), aktivieren Sie Enable/Disable, klicken Sie auf Save und testen Sie eine Zahlung.

5. Wenn alles bereit ist, geben Sie die Live-App ID und den Secret Key ein, deaktivieren Sie Sandbox Mode und klicken Sie auf Save.

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

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Cashfree Payments > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder erklärt die Seite, dass die Bestellung erst nach der Bestätigung der Zahlung durch Cashfree angelegt wird. Ist die Zahlungsmethode aktiviert, warnt die Seite, wenn die API-Schlüssel des gewählten Modus fehlen (die Zahlungsmethode wird dann an der Kasse ausgeblendet), und zeigt bei aktiviertem Sandbox-Modus Sandbox mode is on: customers see a test checkout and no real money is charged. an. Speichern Sie eine aktivierte Zahlungsmethode ohne die Schlüssel des gewählten Modus, weist eine Warnung darauf hin, dass sie an der Kasse ausgeblendet bleibt, bis die Schlüssel eingetragen sind.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments schaltet die Zahlungsmethode ein oder aus. Standard: off.

Title: der Name der Zahlungsmethode, den der Kunde an der Kasse sieht. Er wird auch als Zahlungsmethode in der Bestellung gespeichert. Standard: Cashfree Payments. Pflichtfeld.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

App ID und Secret Key finden Sie im Cashfree Merchant Dashboard unter Developers > API Keys. Test- und Produktionsschlüssel sind verschieden.

Sandbox Mode: nutzt die Cashfree-Sandbox zum Testen. Es wird kein echtes Geld belastet, und an der Kasse erscheint unter der Zahlungsmethode SANDBOX MODE - no real payments will be processed. Standard: on. Deaktivieren Sie den Modus für echte Zahlungen.

Sandbox App ID: die App ID Ihrer Cashfree-Testumgebung.

Sandbox Secret Key: der Secret Key Ihrer Cashfree-Testumgebung.

App ID: die App ID Ihrer Cashfree-Produktivumgebung.

Secret Key: der Secret Key Ihrer Cashfree-Produktivumgebung.

Gespeicherte Secret Keys werden nie wieder 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 secrets: Aktivieren Sie das Kästchen bei einem Secret Key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungen behalten die Umgebung, in der sie angelegt wurden. Ihre Webhooks werden geprüft, ihr Status wird abgefragt und ihre Erstattungen werden mit den Schlüsseln dieser Umgebung gesendet. Lassen Sie die Sandbox-Schlüssel deshalb ausgefüllt, bis Sandbox-Zahlungen nach dem Wechsel auf den Livebetrieb abgeschlossen sind.

Webhook

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt, fehlgeschlagen oder erstattet wurde. Gehen Sie im Cashfree Merchant Dashboard zu Developers > Webhooks und fügen Sie die URL hinzu, die in diesem Abschnitt unter Webhook URL angezeigt wird, mit den Ereignissen Payment und Refund. Mit suchmaschinenfreundlichen URLs sieht sie etwa so aus: https://your-shop/module/wcp_cashfree_payment/webhook. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Auf einem HTTPS-Shop übergibt das Modul diese URL bei jeder Zahlung ebenfalls an Cashfree. Wenn Ihr Shop kein HTTPS verwendet, zeigt dieser Abschnitt eine Warnung.

Das Modul verarbeitet diese Ereignisse (sie sind auch in diesem Abschnitt aufgeführt):

Cashfree signiert jeden Webhook mit Ihrem Secret Key. Webhooks ohne gültige Signatur werden abgelehnt. Ein Webhook muss mit dem Secret Key der Umgebung signiert sein, in der die Zahlung erfolgt ist, daher bestätigt ein Sandbox-Schlüssel nie eine Live-Zahlung. Signierte Webhooks für Zahlungen, die nicht von diesem Shop gestartet wurden (zum Beispiel von einem anderen Shop auf demselben Cashfree-Konto), werden quittiert und ignoriert. Ohne Webhook wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt. Schließt der Kunde nach der Zahlung den Browser, kann nur der Webhook (oder der nächste Zahlungsversuch für denselben Warenkorb) die Bestellung anlegen.

Advanced

API Version: die zu verwendende Version der Cashfree-API.

Order ID prefix: Cashfree-Bestellnummern werden aus Präfix + PrestaShop-Warenkorb-ID gebildet; ein neuer Versuch für denselben Warenkorb erhält eine Nummer am Ende (zum Beispiel 123-2). Lassen Sie das Feld leer, um das automatische Präfix dieses Shops zu verwenden, das in der Feldbeschreibung angezeigt wird. Verwenden Sie für jeden Shop, der mit demselben Cashfree-Konto verbunden ist, ein eigenes Präfix. Erlaubt sind nur Buchstaben, Ziffern, „_“ und „-“, bis zu 20 Zeichen. Andere Zeichen werden beim Speichern mit einer Warnung entfernt.

Debug log: Fehler werden immer protokolliert. Ist die Option aktiviert, werden Cashfree-API-Aufrufe und Webhooks zusätzlich in logs/cashfree_p_debug.log.php im Modulordner geschrieben. Die Datei lässt sich nicht über das Web öffnen. Schlüssel und Kundendaten werden nie protokolliert. Standard: off.

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: Ist die Option aktiviert, entfernt das Deinstallieren des Moduls die Cashfree-Einstellungen und das Modulprotokoll. Bestellungen, ihre Cashfree-Transaktionen und Erstattungen sowie der Bestellstatus Cashfree payment on hold bleiben immer erhalten, damit bestehende Bestellungen weiter funktionieren. Standard: off.

Kasse

Auf der Zahlungsseite wählt der Kunde die Zahlungsmethode (standardmäßig Cashfree Payments) und bestätigt. Das Modul legt eine Cashfree-Bestellung für den Warenkorbbetrag in der Warenkorbwährung an und öffnet eine Zahlungsseite, die Redirecting to Cashfree for payment... anzeigt und die Cashfree-Zahlungsseite lädt. Öffnet sie sich nicht von selbst, kann der Kunde auf Pay Now klicken. Auf der Cashfree-Zahlungsseite bezahlt der Kunde mit jeder Methode, die in Ihrem Cashfree-Konto aktiviert ist, zum Beispiel Karte, UPI, Netbanking oder E-Wallet. Die E-Mail-Adresse und die Rechnungstelefonnummer des Kunden werden an Cashfree übermittelt. 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 Cashfree die Zahlung bestätigt: durch den signierten Webhook oder durch eine serverseitige Anfrage an Cashfree, wenn der Kunde zurückkehrt. Dann wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite. Die Rückkehr funktioniert auch in einem anderen Browser, zum Beispiel wenn der Kunde aus einer UPI-App zurückkommt. Hat die Bank die Zahlung noch nicht bestätigt, zeigt eine Seite Payment confirmation den Hinweis Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. und eine Schaltfläche Check again; der Webhook legt die Bestellung an, sobald die Bank die Zahlung bestätigt.

Schlägt die Zahlung fehl oder verlässt der Kunde die Cashfree-Seite ohne zu bezahlen, kehrt er zur Kasse zurück und sieht The Cashfree payment was not completed. Please try again or choose another payment method. Der Warenkorb bleibt erhalten. Eine offene Cashfree-Zahlung wird wiederverwendet, wenn der Kunde es erneut versucht. Hat sich der Warenkorbbetrag geändert oder läuft die Sitzung bald ab, wird die alte Cashfree-Bestellung geschlossen und eine neue angelegt, damit der Warenkorb nicht doppelt bezahlt werden kann. Wurde der Warenkorb bei Cashfree bereits bezahlt, aber nicht verbucht, legt der nächste Versuch die Bestellung an, statt erneut zu belasten.

Kann Cashfree die Zahlung nicht starten, bleibt der Kunde an der Kasse und sieht We could not start the Cashfree payment. Please try again or choose another payment method. Der technische Grund wird im Protokoll festgehalten. Ein Warenkorbbetrag unter dem Cashfree-Mindestbetrag (1 Einheit der Währung; 0,01 für BHD, JOD, KWD, OMR und 0,1 für TND) kann nicht mit Cashfree bezahlt werden, und die Zahlungsmethode wird dafür nicht angezeigt.

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

Das Modul unterstützt nur einmalige Zahlungen auf der Cashfree-Zahlungsseite. Es gibt keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, keine getrennte Autorisierung und Erfassung, kein Cashfree-Angebots-Widget, kein COD über Cashfree und keine Zahlungslinks sowie keine Währungsumrechnung: Der Warenkorb wird in der Warenkorbwährung belastet.

Bestellungen und Erstattungen

Order statuses

No order yet: Der Kunde wurde zu Cashfree weitergeleitet und hat nicht bezahlt, die Zahlung ist fehlgeschlagen oder die Zahlung ist bei der Bank noch ausstehend. Es existiert nur der Warenkorb.

Payment accepted: Die Zahlung wurde bestätigt. Die Zahlung wird mit der Cashfree-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Transaktions-ID und die Zahlungsmethodengruppe (zum Beispiel upi oder credit_card).

Cashfree payment on hold: Cashfree hat einen bezahlten Betrag oder eine Währung gemeldet, die vom Warenkorbbetrag abweicht (zum Beispiel wurde der Warenkorb in einem anderen Tab geändert, nachdem die Zahlung begonnen hatte). Die Notiz zeigt den erwarteten und den erhaltenen Betrag sowie die Transaktions-ID. Prüfen Sie die Zahlung im Cashfree Dashboard und schließen Sie danach die Bestellung ab oder erstatten Sie die Zahlung.

Refunded: Die Zahlung wurde über das Modul vollständig erstattet.

Eine Zahlung, die nach dem Stornieren der Bestellung eingeht, wird trotzdem erfasst, und die Bestellung wird wieder als bezahlt markiert, weil das Geld eingezogen wurde. Eine bezahlte Bestellung wird durch eine spätere fehlgeschlagene Zahlung nie zurückgesetzt.

Cashfree payment block

Die Bestellseite zeigt einen Block Cashfree payment mit der Transaktions-ID, der Cashfree-Bestellung, dem Zahlungsstatus, dem bezahlten und erstatteten Betrag, einem Hinweis Sandbox bei Sandbox-Zahlungen, dem Erstattungsverlauf und den Cashfree notes der Bestellung.

Refunds

Geben Sie im Block Cashfree payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Cashfree. Bestätigen Sie die Abfrage Refund this amount through Cashfree? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht erforderlich. Erstattungen erfolgen in dem Betrag und der Währung, die Cashfree belastet hat. Nach einer Betragsabweichung können Sie daher bis zu dem erstatten, was der Kunde tatsächlich bezahlt hat, nicht den Bestellbetrag. Die Erstattung wird an die bezahlte Cashfree-Bestellung gesendet, und zwar in der Umgebung (Sandbox oder Live), in der bezahlt wurde; die Schlüssel dieser Umgebung müssen daher eingetragen sein. Akzeptiert Cashfree die Erstattung nicht oder meldet sie als storniert oder abgelehnt, zeigt der Block den Fehler an, und es wird keine Erstattung erfasst. Eine gestartete Erstattung wird mit Erstattungs-ID, Betrag und Status im Erstattungsverlauf und in den Notizen ergänzt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Cashfree die Zahlung bestätigt hat.

Den endgültigen Erstattungsstatus liefert der Erstattungs-Webhook, und er wird in den Notizen ergänzt. Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Cashfree zurück.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Cashfree Payments ist der erste Block auf Modules > Module Manager > VibeFox Cashfree Payments > 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen 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-cashfree 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 einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul weiter mit dem zuletzt bekannten Status.

Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Einrichtung. 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 Cashfree Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Die PrestaShop-Storefront weiß nicht, dass Sie im Back-Office angemeldet sind, daher ist 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 Reiter 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 der 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. Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Cashfree erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus seine Schlüssel hat: Sandbox App ID und Sandbox Secret Key im Sandbox-Modus, App ID und Secret Key im Live-Modus. Die Einstellungsseite zeigt eine Warnung, wenn Schlüssel fehlen. Die Zahlungsmethode wird außerdem ausgeblendet, wenn der Warenkorbbetrag unter dem Cashfree-Mindestbetrag liegt. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht. Prüfen Sie, ob Ihr Shop HTTPS verwendet, ob die URL unter Developers > Webhooks genau der unter Webhook URL angezeigten entspricht und ob die Payment-Ereignisse ausgewählt sind. Prüfen Sie, ob der Secret Key in den Einstellungen zu der Umgebung gehört, in der bezahlt wurde. Das Cashfree Dashboard zeigt für jeden Webhook die Antwort Ihres Shops. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt, und beim nächsten Zahlungsversuch für denselben Warenkorb.

Der Webhook antwortet Missing signature oder Invalid signature: Der Aufruf enthielt keine gültige Cashfree-Signatur, oder der Secret Key in den Einstellungen passt nicht zu der Umgebung, in der bezahlt wurde. Prüfen Sie, ob Sandbox- und Live-Schlüssel nicht vertauscht sind.

Der Webhook antwortet Ignored: Der Webhook ist korrekt signiert, gehört aber zu einer Zahlung, die nicht von diesem Shop gestartet wurde, zum Beispiel von einem anderen Shop auf demselben Cashfree-Konto. Geben Sie jedem Shop ein eigenes Order ID prefix.

Der Webhook antwortet Busy, retry later: Die Bestellung wurde gerade von einer anderen Anfrage angelegt, oder sie konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Cashfree wiederholt den Webhook. Aktivieren Sie Debug log, um den Grund zu sehen.

Der Kunde sieht The Cashfree payment page could not be loaded: Das Cashfree-Skript konnte im Browser nicht geladen werden, zum Beispiel wegen eines Blockers. Der Kunde kann erneut auf Pay Now oder auf Choose another payment method klicken.

Der Kunde sieht We could not start the Cashfree payment: Schauen Sie im Feld Log auf der Modulseite nach. Typische Gründe sind falsche Schlüssel für den gewählten Modus oder eine Währung, die für Ihr Cashfree-Konto nicht aktiviert ist.

Der Kunde sieht We could not verify the payment: Der Rücksprung-Link passte nicht zum Warenkorb. Wurde Geld belastet, legt der Webhook die Bestellung trotzdem an. Prüfen Sie die Zahlung im Cashfree Dashboard, bevor der Kunde erneut bezahlt.

Die Bestellung ist nach der Zahlung Cashfree payment on hold: Lesen Sie die Notizen im Block Cashfree payment (siehe Bestellstatus) und schließen Sie danach die Bestellung ab oder erstatten Sie die Zahlung.

Die Erstattung schlägt mit einer Meldung zu Sandbox- oder Live-Modus fehl: Die Zahlung wurde in dieser Umgebung getätigt, und ihre API-Schlüssel sind nicht eingetragen. Tragen Sie sie ein und versuchen Sie es erneut.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Cashfree Payments und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall aktiviert, werden die Cashfree-Einstellungen und das Protokoll entfernt. Ist die Option deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Cashfree-Transaktionen und Erstattungen sowie der Bestellstatus Cashfree payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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