VibeFox Cashfree for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 6.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

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

Cashfree-Konto: Sie benötigen App ID und Secret Key Ihres Cashfree-Kontos, 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 von Webhooks verwendet, daher gibt es kein separates Webhook-Geheimnis. Die Bestellwährung muss für Ihr Cashfree-Konto aktiviert sein.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine 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. Alternativ können Sie den Ordner wcp_cashfree_payment per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Cashfree Payments > 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. Tragen Sie die Sandbox App ID und den Sandbox Secret Key ein, legen Sie den Webhook im Cashfree Merchant Dashboard an (siehe Konfiguration), schalten Sie Enable/Disable ein und testen Sie eine Zahlung.

6. Wenn Sie so weit sind, tragen Sie die Live-App ID und den Secret Key ein und entfernen Sie das Häkchen bei Sandbox Mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Cashfree Payments. 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). Solange der Sandbox-Modus eingeschaltet ist, zeigt sie außerdem Sandbox mode is on: customers see a test checkout and no real money is charged. Wenn Sie ein aktiviertes Gateway ohne die Schlüssel des gewählten Modus speichern, zeigt eine Fehlermeldung an, dass die Zahlungsmethode an der Kasse ausgeblendet bleibt, bis die Schlüssel eingetragen sind.

Allgemein

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Cashfree Payments.

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

Modus und API-Schlüssel

App ID und Secret Key finden Sie im Cashfree Merchant Dashboard unter Developers > API Keys. Test- und Produktivschlüssel sind verschieden; tragen Sie jeden in seinem eigenen Abschnitt ein.

Sandbox Mode: Enable Sandbox (test) mode nutzt die Cashfree-Sandbox zum Testen. Es wird kein echtes Geld belastet, und die Kasse zeigt SANDBOX MODE - no real payments will be processed. Standard: ein. Entfernen Sie das Häkchen für Live-Zahlungen.

Sandbox-Zugangsdaten

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

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

Live-Zugangsdaten

App ID: die App ID Ihrer Cashfree-Produktivumgebung.

Secret Key: der Secret Key Ihrer Cashfree-Produktivumgebung.

Bestellungen behalten die Umgebung, in der sie angelegt wurden. Ihre Webhooks werden mit den Schlüsseln dieser Umgebung geprüft und ihre Erstattungen mit diesen Schlüsseln gesendet. Lassen Sie daher die Sandbox-Schlüssel eingetragen, bis die Sandbox-Bestellungen nach dem Wechsel in den Live-Modus abgeschlossen sind.

Webhook

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung eingegangen, fehlgeschlagen oder erstattet wurde. Gehen Sie im Cashfree Merchant Dashboard zu Developers > Webhooks und fügen Sie die in diesem Abschnitt angezeigte URL mit den Ereignissen Payment und Refund hinzu. Sie sieht so aus: https://your-site/wc-api/cashfree_p/?action=webhook. Auf einer HTTPS-Website übergibt das Plugin diese URL bei jeder Bestellung zusätzlich an Cashfree. Nutzt Ihre Website kein HTTPS, zeigt dieser Abschnitt eine Warnung.

Das Plugin verarbeitet diese Ereignisse:

Cashfree signiert jeden Webhook mit Ihrem Secret Key. Webhooks ohne gültige Signatur werden abgelehnt. Signierte Webhooks für Bestellungen, die nicht von diesem Shop angelegt wurden (zum Beispiel ein anderer Shop auf demselben Cashfree-Konto), werden bestätigt und ignoriert. Ohne den Webhook wird eine Bestellung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt. Schließt der Kunde nach der Zahlung den Browser, kann nur der Webhook die Bestellung bestätigen.

Erweitert

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

Order ID prefix: Cashfree-Bestellnummern werden aus Präfix + WooCommerce-Bestellnummer gebildet; ein wiederholter Versuch erhält am Ende eine Zahl. Lassen Sie das Feld leer, um das automatische Präfix dieser Website zu verwenden, das in der Feldbeschreibung angezeigt wird. Verwenden Sie für jeden Shop, der mit demselben Cashfree-Konto verbunden ist, ein anderes Präfix. Erlaubt sind nur Buchstaben, Ziffern, „_“ und „-“, bis zu 20 Zeichen. Andere Zeichen werden beim Speichern entfernt, und es erscheint eine Meldung.

Debug log: Log Cashfree API events for debugging. Fehler werden immer protokolliert. Ist die Option eingeschaltet, werden API-Aufrufe und Webhooks außerdem in WooCommerce > Status > Logs, Quelle wcp_cashfree_payment, geschrieben. Schlüssel und Kundendaten werden nie protokolliert. Standard: aus.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Ist die Option eingeschaltet, entfernt das Löschen des Plugins die Cashfree-Einstellungen, die Plugin-Protokolle und die an den Bestellungen gespeicherten Cashfree-Referenzen. Die Bestellungen selbst bleiben erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Cashfree Payments) und gibt die Bestellung auf. Das Plugin erstellt für den Bestellbetrag in der Bestellwährung eine Cashfree-Bestellung und öffnet die Seite Pay for order, auf der Redirecting to Cashfree for payment... angezeigt wird und die Cashfree-Zahlungsseite geladen wird. Ö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.

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, sobald der Kunde zurückkehrt. Hat die Bank die Zahlung noch nicht bestätigt, zeigt die Bestellbestätigungsseite Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.

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

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

Die Zahlungsmethode funktioniert auf der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel. Die Kundentexte sind ins Hindi übersetzt.

Das Plugin akzeptiert einmalige Zahlungen nur über die Cashfree-Zahlungsseite. Es bietet keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, keine getrennte Autorisierung und Erfassung, kein Cashfree-Angebots-Widget, kein COD (Nachnahme) über Cashfree und keine Zahlungslinks sowie keine Währungsumrechnung: Die Bestellung wird in der Bestellwährung belastet.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Cashfree weitergeleitet und hat noch nicht bezahlt, oder die Zahlung ist bei der Bank noch ausstehend. Kehrt der Kunde mit einer ausstehenden Zahlung zurück, zeigt eine Notiz, dass das Plugin auf den Cashfree-Webhook wartet.

Processing: Die Zahlung wurde bestätigt (Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden, wie in WooCommerce voreingestellt, auf Abgeschlossen gesetzt). Die Bestellnotiz zeigt die Cashfree-Transaktions-ID und die Zahlungsmethodengruppe. Die Transaktions-ID der Bestellung ist die Cashfree-Zahlungs-ID. Eine Zahlung, die nach der Stornierung der Bestellung eingeht, wird trotzdem verbucht, weil das Geld abgebucht wurde.

On hold: Cashfree hat einen bezahlten Betrag oder eine Währung gemeldet, die vom Bestellbetrag abweicht. Die Bestellnotiz zeigt den erwarteten und den erhaltenen Betrag sowie die Transaktions-ID. Prüfen Sie die Zahlung im Cashfree-Dashboard und schließen Sie die Bestellung manuell ab oder erstatten Sie sie.

Failed: Die Zahlung ist bei Cashfree fehlgeschlagen oder wurde abgebrochen. Die Notiz zeigt den Cashfree-Status und den Grund. Jeder weitere fehlgeschlagene Versuch fügt eine Notiz hinzu.

Eine bezahlte Bestellung wird durch einen späteren Webhook oder eine Rückkehr des Kunden nie zurückgesetzt.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Cashfree Payments (die Schaltfläche zeigt den Titel der Zahlungsmethode an). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird an die bezahlte Cashfree-Bestellung gesendet, in der Umgebung (Sandbox oder Live), in der sie bezahlt wurde; daher müssen die Schlüssel dieser Umgebung eingetragen sein. Akzeptiert Cashfree die Erstattung nicht oder meldet es sie als storniert oder abgelehnt, zeigt WooCommerce den Fehler an, und es wird keine Erstattung verbucht. Eine begonnene Erstattung wird mit Erstattungs-ID, Betrag und Status den Bestellnotizen hinzugefügt. Den endgültigen Status liefert der Erstattungs-Webhook als weitere Bestellnotiz.

Webhooks zum Erstattungsstatus werden nur als Notizen hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Cashfree Payments. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, 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 gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren 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. Versucht trotzdem jemand, eine Zahlung zu starten, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen bleiben unberührt: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, doch Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.

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 Zahlungsmethode wird auch ausgeblendet, wenn der Bestellbetrag unter dem Cashfree-Mindestbetrag liegt. Die Einstellungsseite zeigt eine Warnung, wenn Schlüssel fehlen.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt bei Pending payment: der Webhook funktioniert nicht. Prüfen Sie, ob Ihre Website HTTPS verwendet, ob die URL unter Developers > Webhooks genau der in den Einstellungen angezeigten entspricht und ob die Payment-Ereignisse ausgewählt sind. Prüfen Sie außerdem, ob der Secret Key in den Einstellungen zu der Umgebung gehört, in der die Bestellung bezahlt wurde. Die Bestellung wird auch bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt und bei der nächsten Zahlungsanfrage.

Der Webhook antwortet mit 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 die Bestellung angelegt wurde. Cashfree wiederholt den Webhook.

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

Der Webhook antwortet mit Busy, retry later: Die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet. Cashfree wiederholt den Webhook.

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 klicken oder Choose another payment method wählen.

Der Kunde sieht We could not start the Cashfree payment: Schalten Sie das Debug log ein und prüfen Sie WooCommerce > Status > Logs, Quelle wcp_cashfree_payment. Typische Ursachen 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 The minimum amount for a Cashfree payment is …: Der Bestellbetrag liegt unter dem Cashfree-Mindestbetrag für die Währung.

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

Die Bestellung ist nach der Zahlung auf On hold: Lesen Sie die Bestellnotiz. Der bezahlte Betrag oder die Währung wich von der Bestellung ab. Schließen Sie die Bestellung ab oder erstatten Sie die Zahlung.

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

Der Lizenzblock zeigt einen Fehler: folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website 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. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen, die an den Bestellungen gespeicherten Cashfree-Daten und die Protokolle werden nur entfernt, wenn Delete Data on Uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Cashfree ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Cashfree verbunden noch von Cashfree empfohlen.