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

Stripe-Konto: Sie benötigen die geheimen API-Schlüssel Ihres Stripe-Kontos und einen Webhook-Endpunkt im Stripe Dashboard (siehe Konfiguration). Verwendet werden nur die geheimen Schlüssel und die Signaturgeheimnisse der Webhooks. Die veröffentlichbaren Schlüssel (pk_...) werden nicht benötigt, da Stripe Checkout eine von Stripe gehostete Seite 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 aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Stripe Gateway später 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 Stripe-Schlüssel ein, richten Sie den Webhook im Stripe Dashboard ein und fügen Sie seine Signaturgeheimnisse ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Testmodus mit der Karte 4242 4242 4242 4242 und schalten Sie danach Test Mode aus.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Stripe payment und Stripe payment on hold. PrestaShop aktiviert das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Stripe Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist (dann wird die Zahlungsart an der Kasse ausgeblendet) oder kein Webhook-Signaturgeheimnis (dann werden Bestellungen nur bestätigt, wenn der Kunde in den Shop zurückkehrt). Solange der Testmodus aktiv ist, zeigt sie außerdem Der Testmodus ist aktiviert: Es werden keine echten Zahlungen abgebucht. an.

Stripe Checkout

Enable/Disable: Enable Stripe Gateway schaltet die Zahlungsart ein oder aus. Default: off.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Default: Stripe. Pflichtfeld.

Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Default: Pay securely with your credit or debit card via Stripe.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus Stripe Dashboard > Developers > API keys. Test- und Live-Schlüssel sind getrennt. Der Testmodus verwendet nur die Testschlüssel, der Live-Modus nur die Live-Schlüssel. Beim Speichern warnt das Modul, wenn ein Wert nicht mit dem erwarteten Präfix beginnt, z. B. wenn statt eines geheimen Schlüssels ein veröffentlichbarer Schlüssel eingefügt wurde.

Test Mode: verwendet die Stripe-Testschlüssel. Es wird kein echtes Geld abgebucht; bezahlen Sie mit Stripe-Testkarten wie 4242 4242 4242 4242. Default: on. Schalten Sie es aus, um echte Zahlungen anzunehmen. Solange es aktiv ist, sehen Kunden unter der Zahlungsart: Testmodus: Es wird keine echte Zahlung abgebucht.

Test Secret Key: der geheime Schlüssel des Testmodus. Er beginnt mit sk_test_ (oder rk_test_ bei einem eingeschränkten Schlüssel).

Test Webhook Secret: das Signaturgeheimnis (whsec_...) des im Testmodus angelegten Webhook-Endpunkts.

Live Secret Key: der geheime Schlüssel des Live-Modus. Er beginnt mit sk_live_ (oder rk_live_ bei einem eingeschränkten Schlüssel).

Live Webhook Secret: das Signaturgeheimnis (whsec_...) des im Live-Modus angelegten Webhook-Endpunkts.

Gespeicherte Schlüssel und Geheimnisse werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Gespeichert — zum Beibehalten leer lassen. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved secrets: Haken Sie einen Schlüssel oder ein Geheimnis an und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Webhook

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Legen Sie im Stripe Dashboard > Developers > Webhooks einen Endpunkt im Testmodus und einen weiteren im Live-Modus an. Verwenden Sie die URL unter Endpoint URL in diesem Abschnitt. Mit freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_stripe_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen, da Stripe Weiterleitungen nicht folgt.

Wählen Sie für jeden Endpunkt diese Ereignisse aus (sie sind auch in diesem Abschnitt aufgeführt):

Kopieren Sie nach dem Anlegen jedes Endpunkts dessen Signaturgeheimnis (whsec_...) aus Stripe und fügen Sie es in Test Webhook Secret bzw. Live Webhook Secret ein. Webhooks ohne gültige Signatur werden abgelehnt. Ein Ereignis muss mit dem Geheimnis des Modus signiert sein, in dem die Zahlung erfolgt ist, daher bestätigt ein Testgeheimnis nie eine Live-Zahlung. Ohne den Webhook wird eine Bestellung erst angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Bestellungen

Order Status After Payment: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird.

Verzögerte Zahlungen warten im Status Awaiting Stripe payment. Abweichungen bei Betrag oder Währung gehen immer in Stripe payment on hold.

Erweitert

Logging: schreibt Stripe-Anfragen und Webhooks in logs/strg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Schlüssel und Kundendaten werden nicht protokolliert. Default: off. Solange es ausgeschaltet ist, wird nichts geschrieben.

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 Einstellungen des Gateways und das Protokoll. Die Stripe-Transaktionen und -Erstattungen sowie die Bestellstatus des Moduls bleiben immer erhalten, damit bestehende Bestellungen weiter funktionieren. Default: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Stripe) und sieht den Hinweis Sie werden zu Stripe weitergeleitet, um die Zahlung sicher abzuschließen. Nach der Bestätigung erstellt das Modul eine Stripe-Checkout-Sitzung für den Warenkorbbetrag in der Warenkorbwährung und leitet den Kunden auf die Zahlungsseite von Stripe weiter. Dort bezahlt der Kunde mit Kredit- oder Debitkarte. Die E-Mail-Adresse des Kunden wird an Stripe übergeben, und die Zahlung erscheint auf der Stripe-Seite als Cart # mit der Warenkorbnummer. 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 Stripe die Zahlung bestätigt hat: durch den signierten Webhook oder durch eine serverseitige Anfrage an Stripe, wenn der Kunde zurückkehrt. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Ihre Zahlung mit Stripe ist eingegangen. Bei einer verzögerten Zahlung zeigt die Seite Ihre Zahlung wird von Stripe bestätigt. Sie erhalten eine E-Mail, sobald sie bestätigt ist. Schlägt eine verzögerte Zahlung später fehl, zeigt die Seite Ihre Stripe-Zahlung wurde nicht abgeschlossen. Bitte kontaktieren Sie uns zu dieser Bestellung. Hat Stripe die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt, zeigt eine Seite Zahlungsbestätigung denselben Text und eine Schaltfläche Check again; der Webhook legt die Bestellung an, sobald er eintrifft.

Bricht der Kunde auf der Stripe-Seite ab, wird die Stripe-Sitzung geschlossen und der Kunde kehrt zur Kasse zurück mit Die Zahlung wurde abgebrochen. Sie können es erneut versuchen oder eine andere Zahlungsart wählen. Wurde die Zahlung nicht abgeschlossen, lautet die Meldung Die Zahlung wurde nicht abgeschlossen. Sie können es erneut versuchen oder eine andere Zahlungsart wählen. Der Warenkorb bleibt erhalten. Jeder neue Versuch schließt die vorherige Stripe-Sitzung, sodass der Warenkorb nicht doppelt bezahlt werden kann. Stellt sich heraus, dass die vorherige Sitzung bereits bezahlt wurde, wird stattdessen die Bestellung angelegt.

Kann Stripe die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, z. B. Der Bestellbetrag liegt unter dem Mindestbetrag, den Stripe in dieser Währung abbuchen kann. Bitte wählen Sie eine andere Zahlungsart. Der technische Grund wird im Protokoll festgehalten.

Wird ein Gutschein im Warenkorb zwischen Zahlung und Bestätigung ungültig, entfernt PrestaShop ihn aus der Bestellung. Die Bestellung wird dann mit einer Notiz in Stripe payment on hold versetzt, weil der Kunde den Preis mit Rabatt bezahlt hat.

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

Das Modul nimmt nur Kartenzahlungen an, die sofort auf der Stripe-Seite erfasst werden. Es gibt keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, kein Kartenformular auf Ihrer Website, keine Apple-Pay- oder Google-Pay-Schaltflächen auf Ihrer Website und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

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

Payment accepted, Delivered or Stripe payment on hold: Die Zahlung wurde bestätigt. Der Status richtet sich nach Order Status After Payment. Die Zahlung wird mit der Stripe-Zahlungs-ID (pi_...) als Transaktions-ID erfasst, und eine Notiz zeigt die Stripe-Zahlung, die Sitzung und wie sie bestätigt wurde (Webhook oder Rückkehr).

Awaiting Stripe payment: Der Kunde hat die Kasse mit einer verzögerten Zahlungsart abgeschlossen. Die Bestellung wechselt in den Status für bezahlte Bestellungen, sobald Stripe die Zahlung bestätigt.

Stripe payment on hold after payment: Stripe hat einen anderen Betrag oder eine andere Währung gemeldet als den Bestellbetrag (z. B. wurde der Warenkorb geändert, nachdem die Zahlung begonnen hatte), ein Gutschein wurde entfernt, oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.

Payment error: Eine verzögerte Zahlung ist fehlgeschlagen.

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

Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, dies zu prüfen und das Duplikat im Stripe Dashboard zu erstatten.

Block „Stripe payment“

Die Bestellseite zeigt einen Block Stripe payment mit der Stripe-Zahlungs-ID (verlinkt mit der Zahlung im Stripe Dashboard), der Checkout-Sitzung, dem Zahlungsstatus, dem von Stripe abgebuchten Betrag und dem erstatteten Betrag, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Stripe notes der Bestellung.

Erstattungen

Geben Sie im Block Stripe payment den Betrag ein (vorausgefüllt wird der noch nicht erstattete Betrag), optional einen Grund, und klicken Sie auf Refund via Stripe. Bestätigen Sie die Frage Diesen Betrag über Stripe erstatten? Dies kann nicht rückgängig gemacht werden. Voll- und Teilerstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen erfolgen in dem Betrag und der Währung, die Stripe abgebucht hat. Nach einer Abweichung bei Betrag oder Währung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht den Bestellbetrag. Die Erstattung wird im Modus gesendet, in dem die Zahlung erfolgt ist (Test oder Live), daher muss dessen geheimer Schlüssel gesetzt sein. Lehnt Stripe die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der Stripe-Erstattungs-ID dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Stripe die Zahlung bestätigt hat.

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

Im Stripe Dashboard vorgenommene Erstattungen gelangen über den Webhook charge.refunded und werden den Notizen mit dem insgesamt in Stripe erstatteten Betrag hinzugefügt. Bestellstatus und Gutschriften werden nicht automatisch geändert. Aktualisieren Sie sie bei Bedarf manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Stripe Gateway ist der erste Block unter Modules > Module Manager > VibeFox Stripe 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 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-stripe 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 gilt für eine Domain: die Domain des Hauptshops, auch bei einem Multistore-Setup. 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 Stripe 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 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 der Registerkarte Alerts. Bestehende Bestellungen bleiben unberührt: 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. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Stripe erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der aktuelle Modus einen geheimen Schlüssel hat: Test Secret Key im Testmodus, Live Secret Key im Live-Modus. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt. 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 durchgegangen, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht. Prüfen Sie im Stripe Dashboard, ob der Endpunkt im verwendeten Modus existiert (Test oder Live), ob seine URL genau der unter Endpoint URL angezeigten entspricht und ob die vier Ereignisse ausgewählt sind. Prüfen Sie, ob das Signaturgeheimnis dieses Endpunkts im passenden Feld steht (Test Webhook Secret oder Live Webhook Secret). Das Stripe 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.

Der Webhook antwortet Webhook secret not configured: Es ist kein Webhook-Geheimnis gesetzt. Fügen Sie das Signaturgeheimnis in die Einstellungen ein.

Der Webhook antwortet Invalid signature: Das Signaturgeheimnis gehört zu einem anderen Endpunkt oder Modus, oder die Serveruhr ist falsch. Stripe-Signaturen werden innerhalb von 5 Minuten zur Serverzeit akzeptiert. Die Antwort lautet ebenfalls Invalid signature, wenn ein Ereignis einer Live-Zahlung mit dem Testgeheimnis signiert ist oder umgekehrt: Prüfen Sie, ob Test- und Live-Geheimnisse vertauscht sind.

Der Webhook antwortet Busy, retry: Die Bestellung wurde gerade von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (z. B. weil das Modul deaktiviert ist). Stripe wiederholt den Webhook automatisch. Aktivieren Sie Logging, um den Grund zu sehen.

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

Warnung „The value does not look right“ beim Speichern: Ein Schlüssel wurde in das falsche Feld eingefügt. Geheime Schlüssel beginnen mit sk_test_ / rk_test_ oder sk_live_ / rk_live_, Webhook-Geheimnisse mit whsec_.

Der Kunde sieht bei der Wahl von Stripe einen Fehler: Aktivieren Sie Logging und prüfen Sie das Feld Log auf der Modulseite. Ein falscher Schlüssel führt zur Meldung, dass die Zahlungsart nicht richtig konfiguriert ist. Ein Bestellbetrag unter dem Stripe-Mindestbetrag der Währung (z. B. 0.50 EUR) kann nicht über Stripe bezahlt werden.

Testzahlungen bestätigen keine Live-Zahlung: Test- und Live-Zahlungen sind getrennt. Stellen Sie Test Mode auf den gewünschten Modus um und verwenden Sie die Schlüssel und den Webhook dieses Modus.

Bestellung ist nach der Zahlung in Stripe payment on hold: Lesen Sie die Notizen im Block Stripe payment (siehe Bestellstatus) und erfüllen Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung wurde im Test- oder Live-Modus getätigt, und der geheime Schlüssel dieses Modus ist nicht gesetzt. Geben Sie ihn ein und versuchen Sie es erneut.

Deinstallation

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

Stripe ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Stripe verbunden noch wird es von Stripe unterstützt.