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

Razorpay-Konto: Sie benötigen Key ID und Key Secret Ihres Razorpay-Kontos für den Testmodus und für den Live-Modus, sobald Ihr Konto freigeschaltet ist. Ein Webhook mit einem Secret Ihrer Wahl wird dringend empfohlen (siehe Konfiguration). Zahlungen in Währungen außer INR setzen voraus, dass International Payments in Ihrem Razorpay-Konto aktiviert ist.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. 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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Razorpay 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. Geben Sie Ihre Test Key ID und Ihren Test Key Secret ein, richten Sie den Webhook im Razorpay-Dashboard ein und tragen Sie dessen Secret ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Führen Sie eine Testzahlung mit eingeschaltetem Test mode durch. Wenn Sie bereit sind, tragen Sie die Live-Schlüssel ein und schalten Sie Test mode aus.

Bei der Installation legt das Modul zwei Bestellstatus an, Razorpay payment authorized und Razorpay payment on hold. 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 Razorpay Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Hinweise an: Die Schlüssel des aktuellen Modus fehlen (Razorpay wird dann nicht an der Kasse angezeigt), die Key ID beginnt im Testmodus nicht mit rzp_test_ bzw. im Live-Modus nicht mit rzp_live_, der Testmodus ist eingeschaltet, das Webhook-Secret ist leer oder die Standardwährung des Shops ist nicht INR und erfordert International Payments in Ihrem Razorpay-Konto. Leerzeichen, die bei den Key IDs eingefügt wurden, werden beim Speichern entfernt.

Razorpay

Enable/Disable: Enable Razorpay Payment Gateway schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: UPI, Cards, NetBanking. Pflichtfeld: Ein leerer Titel führt zur Fehlermeldung Enter a title for the payment method.

Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

API-Schlüssel

Ihre Schlüssel erhalten Sie im Razorpay-Dashboard unter Account & Settings > API Keys. Schalten Sie das Dashboard in den Testmodus, um Testschlüssel (rzp_test_...) zu erzeugen. Live-Schlüssel (rzp_live_...) stehen zur Verfügung, sobald Ihr Konto freigeschaltet ist.

Test mode: verwendet die Schlüssel des Testmodus, daher wird kein echtes Geld belastet. Standard: ein. Schalten Sie es aus, um echte Zahlungen anzunehmen. Zahlungen, Erfassungen und Erstattungen einer Bestellung verwenden immer die Schlüssel des Modus, in dem die Bestellung bezahlt wurde. Ein späterer Moduswechsel wirkt sich daher nicht auf bestehende Bestellungen aus.

Test Key ID: die Key ID aus dem Razorpay-Dashboard im Testmodus. Sie beginnt mit rzp_test_.

Test Key Secret: der Key Secret aus dem Razorpay-Dashboard im Testmodus.

Live Key ID: die Key ID aus dem Razorpay-Dashboard im Live-Modus. Sie beginnt mit rzp_live_.

Live Key Secret: der Key Secret aus dem Razorpay-Dashboard im Live-Modus.

Gespeicherte Secrets 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.

Gespeicherte Secrets löschen: Markieren Sie Test Key Secret, Live Key Secret oder Webhook Secret und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

Zahlung

Payment Action: der Zeitpunkt, zu dem das Geld eingezogen wird. Standard: Authorize & Capture.

Authorize & Capture: der Kunde wird sofort belastet. Meldet Razorpay eine autorisierte Zahlung, erfasst das Modul sie.

Authorize Only: der Betrag wird reserviert. Die Bestellung wird im Status Razorpay payment authorized angelegt, und Sie erfassen die Zahlung später mit Capture Razorpay payment im Razorpay-Block der Bestellseite oder im Razorpay-Dashboard. Razorpay erstattet autorisierte Zahlungen automatisch, wenn sie nicht rechtzeitig erfasst werden.

Webhook

Der Webhook bestätigt Zahlungen auch dann, wenn der Kunde den Browser direkt nach der Zahlung schließt, und erfasst Erstattungen, die im Razorpay-Dashboard vorgenommen wurden. Gehen Sie im Razorpay-Dashboard zu Account & Settings > Webhooks und legen Sie einen Webhook im Testmodus und einen weiteren im Live-Modus an. Verwenden Sie die URL, die in diesem Abschnitt unter Webhook URL angezeigt wird. Mit aktivierten freundlichen URLs sieht sie etwa so aus: https://your-shop/module/wcp_razorpay_payment/webhook, möglicherweise mit einem Sprachcode wie /en/. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Geben Sie in Razorpay ein Secret Ihrer Wahl ein und wählen Sie diese Ereignisse aus (sie sind auch in diesem Abschnitt aufgelistet):

payment.authorized: eine Zahlung wurde autorisiert.

payment.captured: eine Zahlung wurde erfasst, auch wenn Sie sie im Razorpay-Dashboard erfassen.

payment.failed: ein Zahlungsversuch ist fehlgeschlagen.

order.paid: die Razorpay-Bestellung der Zahlung wurde bezahlt.

refund.created: eine Zahlung wurde erstattet, zum Beispiel im Razorpay-Dashboard.

Webhook Secret: das Secret, das Sie beim Anlegen des Webhooks eingegeben haben. Verwenden Sie dasselbe Secret für den Test- und den Live-Webhook, weil das Modul für beide ein einziges Feld hat. Webhooks ohne gültige Signatur werden abgelehnt. Ohne Webhook wird eine Zahlung nur bestätigt, wenn der Kunde aus dem Popup zurückkehrt oder die Zahlung für denselben Warenkorb später erneut startet.

Erweitert

Enable Logging: Das Protokoll wird in logs/razorpay_p_debug.log.php im Modulordner geschrieben. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert; diese Option fügt die Debug-Details hinzu. Schlüssel, Signaturen und Kundenkontaktdaten 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: Ist die Option eingeschaltet, entfernt die Deinstallation des Moduls die Modulseinstellungen und das Protokoll. Bestellungen, Razorpay-Transaktionen und -Erstattungen sowie die Bestellstatus des Moduls bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig UPI, Cards, NetBanking) und bestätigt. Das Modul legt eine Razorpay-Bestellung für den genauen Warenkorbbetrag und die Währung an und öffnet die Seite Razorpay payment Ihres Shops. Dort öffnet sich das Razorpay-Checkout-Popup automatisch, mit Name, E-Mail-Adresse und Telefonnummer des Kunden bereits ausgefüllt. Die Zahlung erscheint bei Razorpay als Cart und mit der Warenkorbnummer. Zu diesem Zeitpunkt existiert noch keine PrestaShop-Bestellung. Wird das Popup geschlossen, kann der Kunde auf Pay Now klicken, um es erneut zu öffnen, oder auf Choose another payment method, um zur Kasse zurückzukehren. Der Warenkorb bleibt erhalten. Im Testmodus zeigt die Seite Razorpay Test mode: no real money will be charged.

Nach einer erfolgreichen Zahlung sieht der Kunde Please wait while we process your payment... Das Modul prüft die Razorpay-Signatur, ruft die Zahlung über die Razorpay-API ab und vergleicht Betrag und Währung mit dem Warenkorb. Die Bestellung wird erst als bezahlt markiert, nachdem Razorpay die Zahlung bestätigt hat. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite. Ist die Signatur gültig, die Zahlung in diesem Moment aber nicht abrufbar, wird die Bestellung in Razorpay payment on hold angelegt, und der Webhook bestätigt sie später.

Startet der Kunde die Zahlung für denselben Warenkorb erneut, verwendet das Modul seine Razorpay-Bestellung wieder, sofern Betrag, Währung und Modus unverändert sind. War diese Razorpay-Bestellung bereits bezahlt, etwa weil der Kunde den Browser geschlossen hat und kein Webhook vorhanden ist, legt das Modul die Bestellung aus dieser Zahlung an, statt eine zweite zu verlangen. Hat sich die Warenkorbsumme geändert, wird eine neue Razorpay-Bestellung angelegt.

Meldungen, die der Kunde sehen kann:

Your session has expired. Please click "Pay Now" to try again.

We could not verify your payment. Die Meldung ergänzt, dass die Bestellung automatisch aktualisiert wird, sobald Razorpay die Zahlung bestätigt, falls Geld abgebucht wurde.

This payment method is not available right now. Please choose another payment method. Die Schlüssel fehlen oder sind falsch.

Razorpay is temporarily unavailable. Please try again in a few minutes.

Razorpay could not accept this payment: gefolgt vom Grund, den Razorpay angibt.

The order amount is too small to be paid with Razorpay.

Razorpay Checkout could not be loaded. Das Popup-Skript ist blockiert; die Meldung bittet, die Verbindung zu prüfen, Content-Blocker zu deaktivieren und die Seite neu zu laden.

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

Das Modul unterstützt nur einmalige Zahlungen. Es gibt keine Abonnements oder wiederkehrenden Zahlungen, keine gespeicherten Karten, kein Razorpay Magic Checkout, keine Payment Links oder Route (geteilte Zahlungen) und keine Angebots- oder Finanzierbarkeits-Widgets.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde hat nicht bezahlt, oder Razorpay hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb. Ein fehlgeschlagener Zahlungsversuch legt keine Bestellung an; der Kunde kann erneut bezahlen.

Payment accepted: Die Zahlung wurde erfasst und bestätigt. Die Zahlung wird mit der Razorpay-Zahlungs-ID (pay_...) als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungs-ID, den Betrag und wie sie bestätigt wurde (callback, webhook, sync oder admin).

Razorpay payment authorized: Die Zahlung wurde nur autorisiert (Authorize Only). Erfassen Sie sie, um die Bestellung abzuschließen.

Razorpay payment on hold: wird in diesen Fällen gesetzt, jeweils mit einer Notiz: Der gezahlte Betrag oder die Währung stimmt nicht mit dem Warenkorb überein (zum Beispiel wurde der Warenkorb nach Beginn der Zahlung geändert), die Zahlung wurde für eine stornierte Bestellung erfasst, oder die Zahlung konnte in diesem Moment nicht über die Razorpay-API verifiziert werden. Ein gezahlter Betrag in der Bestellwährung wird in der Bestellung erfasst. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung.

Cancelled: Eine Zahlung, die später für eine stornierte Bestellung eingeht, öffnet diese nicht automatisch erneut: Eine autorisierte Zahlung wird nicht erfasst und erhält nur eine Notiz, und eine erfasste Zahlung setzt die Bestellung auf Razorpay payment on hold. Eine wiederholte Benachrichtigung über die Zahlung, mit der die Bestellung bereits bezahlt wurde, ändert nichts, auch wenn Sie die Bestellung danach storniert haben.

Refunded: Die Zahlung wurde vollständig erstattet.

Geht eine zusätzliche Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, sie im Razorpay-Dashboard zu erstatten, falls dies nicht beabsichtigt war. Ein verspätetes payment.failed für eine bezahlte Bestellung fügt nur eine Notiz hinzu.

Razorpay-Zahlungsblock

Die Bestellseite zeigt einen Block Razorpay payment mit der Razorpay-Zahlungs-ID, der Razorpay-Bestellung, dem Zahlungsstatus, Paid / refunded (der Betrag, den Razorpay belastet hat, und der erstattete Betrag), einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Razorpay notes der Bestellung. Erfassung und Erstattungen erfordern das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulkonfiguration ist nicht nötig.

Erfassung (Authorize Only)

Öffnen Sie die Bestellung im Status Razorpay payment authorized, klicken Sie im Razorpay-Block auf Capture Razorpay payment und bestätigen Sie. Die Zahlung wird im Modus erfasst, in dem sie autorisiert wurde, und die Bestellung wechselt zu Payment accepted. Lehnt Razorpay ab, zeigen der Block und die Notizen Razorpay capture failed: mit dem Grund. Eine Erfassung im Razorpay-Dashboard schließt die Bestellung über den Webhook ab.

Erstattungen

Geben Sie im Razorpay-Block den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Razorpay. Bestätigen Sie die Abfrage Refund this amount through Razorpay? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Erstattungen erfolgen in dem Betrag und in der Währung, die Razorpay belastet hat. Nach einer Betragsabweichung können Sie daher bis zu dem erstatten, was der Kunde tatsächlich bezahlt hat, nicht bis zur Bestellsumme. Ein höherer Betrag führt zu Invalid refund amount: at most, gefolgt vom Betrag. Die Erstattung wird mit den Schlüsseln des Modus gesendet, in dem die Zahlung erfolgt ist. Akzeptiert Razorpay die Erstattung nicht, zeigt der Block Razorpay refund failed: mit dem Grund, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der Razorpay-Erstattungs-ID, dem Betrag und dem Status dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald die Zahlung erfasst wurde.

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

Im Razorpay-Dashboard vorgenommene Erstattungen treffen per Webhook ein und werden einmal im Erstattungsverlauf und in den Notizen erfasst. Ist die Bestellung vollständig erstattet, wechselt ihr Status zu Refunded. Eine Dashboard-Erstattung in einer anderen Währung oder über dem erstattungsfähigen Betrag wird nicht automatisch erfasst; eine Notiz bittet darum, sie manuell zu erfassen.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Razorpay Payment steht als erster Block auf Modules > Module Manager > VibeFox Razorpay Payment > Configure, oberhalb der 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, 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-razorpay 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 für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Wird der Schlüssel aus dem Shop entfernt, wird sein Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Razorpay 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. Eine Erinnerung erscheint in Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erfassungen und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen 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 Eingabe des Schlüssels, danach einmal pro Woche. Ein Cronjob ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Razorpay erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus beide Schlüssel hat: Test Key ID und Test Key Secret im Testmodus, Live Key ID und Live Key Secret im Live-Modus. Die Einstellungsseite zeigt einen Hinweis, wenn sie fehlen. 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 war erfolgreich, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht. Prüfen Sie im Razorpay-Dashboard, ob der Webhook im verwendeten Modus (Test oder Live) existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht und ob alle fünf Ereignisse ausgewählt sind. Prüfen Sie, ob Webhook Secret dasselbe Secret wie in Razorpay ist. Die Bestellung wird auch angelegt, wenn der Kunde aus dem Popup zurückkehrt oder die Zahlung für denselben Warenkorb erneut startet.

Der Webhook antwortet Webhook secret not configured: Webhook Secret ist leer. Geben Sie das Secret des Razorpay-Webhooks ein. Razorpay sendet das Ereignis später erneut.

Der Webhook antwortet Invalid signature oder Missing signature: Das Secret in den Einstellungen unterscheidet sich vom Secret des Razorpay-Webhooks. Geben Sie dasselbe Secret an beiden Stellen ein, für den Test- und den Live-Webhook.

Der Webhook antwortet Retry later: Das Modul konnte eine Erfassung nicht über die Razorpay-API bestätigen, die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist), oder der Warenkorb wurde im selben Moment von einer anderen Anfrage aktualisiert. Razorpay sendet das Ereignis automatisch erneut. Der Grund steht im Log.

Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur Anfragen von Razorpay.

Eine Bestellung ist Razorpay payment on hold: Lesen Sie die Notizen im Razorpay-Block. Der Betrag oder die Währung stimmte nicht mit dem Warenkorb überein, die Zahlung ist für eine stornierte Bestellung eingegangen, oder sie konnte in diesem Moment nicht über die Razorpay-API verifiziert werden und wartet auf den Webhook.

Der Kunde sieht beim Bezahlen einen Fehler: Sehen Sie im Feld Log auf der Modulseite nach. Fehler werden auch bei ausgeschaltetem Enable Logging protokolliert. Falsche Schlüssel führen zur Meldung, dass die Zahlungsart gerade nicht verfügbar ist. Andere Gründe von Razorpay werden nach Razorpay could not accept this payment: angezeigt.

Das Popup öffnet sich nicht: Das Razorpay-Checkout-Skript wurde durch einen Content-Blocker oder die Verbindung blockiert. Der Kunde sieht eine Meldung und kann die Seite neu laden.

Erfassung oder Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung wurde im Testmodus oder im Live-Modus getätigt, und die Schlüssel dieses Modus sind nicht eingetragen. Geben Sie sie ein und versuchen Sie es erneut.

Deinstallation

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

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