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

Braintree-Konto: Sie benötigen die Merchant ID, den Public Key und den Private Key Ihres Braintree-Kontos. Sie finden sie im Braintree Control Panel (Sandbox: sandbox.braintreegateway.com, Live: www.braintreegateway.com) unter dem Zahnradsymbol, API, API Keys. Sandbox- und Live-Konten haben unterschiedliche Schlüssel. 3-D Secure muss für Ihr Braintree-Händlerkonto aktiviert sein, es sei denn, Sie setzen 3-D Secure auf Disabled. Kein Webhook erforderlich: Kartenzahlungen werden sofort bestätigt.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 Braintree 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. Kopieren Sie Merchant ID, Public Key und Private Key aus dem Braintree Control Panel in die Felder für Sandbox oder Live.

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Lassen Sie Sandbox mode eingeschaltet und legen Sie eine Testbestellung mit einer Braintree-Sandbox-Testkarte an. Schalten Sie danach Sandbox mode aus, um mit den Live-Zugangsdaten echte Zahlungen anzunehmen.

Bei der Installation legt das Modul zwei Bestellstatus an: Braintree payment authorized und Braintree payment on hold. PrestaShop bietet das neue 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 Braintree Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Ist die Zahlungsart aktiviert, aber die Merchant ID, der Public Key oder der Private Key der gewählten Umgebung fehlt, warnt die Seite, dass die Zahlungsart an der Kasse ausgeblendet wird, bis diese ausgefüllt sind. Solange der Sandbox-Modus aktiv ist, zeigt die Seite Sandbox mode is on: test payments, no real money. an.

Braintree

Enable/Disable: Enable Braintree card payments schaltet die Zahlungsart ein oder aus. Standard: off.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit / debit card. Pflichtfeld.

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

API-Zugangsdaten

Melden Sie sich im Braintree Control Panel an (Sandbox oder Live), klicken Sie auf das Zahnradsymbol, dann auf API und API Keys. Dort sind der Public Key und der Private Key aufgeführt, und die Merchant ID wird auf derselben Seite angezeigt. Die Seite zeigt nur die Zugangsdatenfelder der gewählten Umgebung; beide Sätze bleiben gespeichert.

Sandbox mode: nutzt die Braintree-Sandbox (Testzahlungen, kein echtes Geld). Standard: on. Schalten Sie ihn aus, um mit den Live-Zugangsdaten echte Zahlungen anzunehmen. Erstattungen, Erfassungen und Stornierungen verwenden immer die Umgebung, in der die Bestellung bezahlt wurde. Solange der Modus aktiv ist, sehen Kunden SANDBOX / TEST MODE — no real money is charged. unter der Zahlungsart.

Sandbox Merchant ID und Live Merchant ID: die Merchant ID des Sandbox- bzw. Live-Kontos.

Sandbox Public Key und Live Public Key: der Public Key dieses Kontos.

Sandbox Private Key und Live Private Key: der Private Key dieses Kontos. Gespeicherte Private 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.

Sandbox merchant account ID(s) und Live merchant account ID(s): optional. Braintree belastet in der Währung des Händlerkontos. Lassen Sie das Feld leer, um Ihr Standard-Händlerkonto zu verwenden, geben Sie eine ID (zum Beispiel mystore_EUR) oder je Währung eine ID ein: EUR=mystore_EUR, USD=mystore_USD. Stimmt die belastete Währung nicht mit der Bestellwährung überein, wird die Transaktion automatisch storniert und der Kunde nicht belastet.

Clear saved private keys: Aktivieren Sie das Kontrollkästchen bei Sandbox Private Key oder Live Private Key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlung

Transaction type: wie die Karte belastet wird.

3-D Secure: 3-D Secure 2 (Strong Customer Authentication) ist im EWR und im Vereinigten Königreich für die meisten Kartenzahlungen vorgeschrieben. Es muss auch für Ihr Braintree-Konto aktiviert sein (wenden Sie sich an den Braintree-Support, wenn Zahlungen mit einem 3-D-Secure-Konfigurationsfehler fehlschlagen).

Das 3-D-Secure-Ergebnis wird serverseitig geprüft, nicht nur im Browser, bevor die Karte belastet wird.

Erweitert

Debug log: protokolliert zusätzlich API-Aufrufe und Zahlungsschritte in logs/wc_btg_debug.log.php im Modulordner. Die Datei kann nicht über das Web aufgerufen werden. Fehler werden immer protokolliert, auch wenn dies ausgeschaltet ist. Das Protokoll enthält nie API-Schlüssel, Karten- oder Kundendaten. 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 die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Braintree-Transaktionen, Erstattungen und Bestellstatus bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation noch erstattet, erfasst oder storniert werden können. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit / debit card) und gibt die Karte im Braintree-Formular innerhalb der Zahlungsoption ein. Das Formular wird nur auf der Kassenseite von Braintree geladen und verwendet die Sprache des Shops. Ist 3-D Secure aktiviert, schließt der Kunde beim Abschicken der Bestellung die Überprüfung seiner Bank ab; Warenkorbsumme, E-Mail-Adresse und Rechnungsadresse werden dabei übergeben.

Das Modul belastet anschließend das Einmal-Token über die Braintree-API für die Warenkorbsumme in der Warenkorbwährung, wobei die Warenkorbnummer als Bestell-ID in Braintree verwendet wird. Vor diesem Punkt existiert keine Bestellung. Der belastete Betrag und die Währung werden mit dem Warenkorb abgeglichen. Die Bestellung wird erst angelegt, nachdem Braintree die Zahlung akzeptiert hat, und der Kunde sieht die übliche PrestaShop-Bestellbestätigungsseite.

Schlägt die Zahlung fehl, wird keine Bestellung angelegt, der Grund wird im Modul-Protokoll vermerkt, und der Kunde bleibt im Zahlungsschritt mit einer Meldung, zum Beispiel Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. oder The card security code or billing address could not be verified. Please check your details and try again. Der Kunde kann sofort erneut versuchen. Stimmen die belastete Währung oder der Betrag nicht mit dem Warenkorb überein, wird die Transaktion storniert, und der Kunde sieht This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.

Ein Warenkorb wird nie zweimal belastet. Eine zweite Absendung, während die Zahlung läuft, zeigt This order is already being paid. Please wait a moment and check your e-mail before trying again. Wurde die Karte belastet, PrestaShop konnte die Bestellung aber nicht anlegen, sieht der Kunde Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Der nächste Versuch für denselben Warenkorb legt die Bestellung aus der gespeicherten Transaktion an, ohne erneut zu belasten.

Das Modul akzeptiert nur Kartenzahlungen. Es unterstützt keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, kein PayPal, Venmo, Apple Pay, Google Pay oder lokale Zahlungsarten und keine Braintree-Webhooks.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Die Zahlung wurde nicht geleistet oder abgelehnt. Es existiert nur der Warenkorb.

Payment accepted: Die Karte wurde belastet (Sale) oder eine Autorisierung wurde erfasst. Die Zahlung wird mit der Braintree-Transaktions-ID erfasst, und eine interne Notiz in den Nachrichten der Bestellung zeigt Betrag, Transaktions-ID und das 3-D-Secure-Ergebnis.

Braintree payment authorized: Die Mittel sind nur autorisiert (Authorize only). Es wird keine Zahlung erfasst, bis Sie sie erfassen.

Braintree payment on hold: Braintree hat einen unerwarteten Transaktionsstatus zurückgegeben, oder eine Belastung in falscher Währung oder mit falschem Betrag konnte nicht automatisch storniert werden. Die Notiz erklärt, was im Braintree Control Panel zu prüfen ist.

Canceled: Eine Autorisierung wurde storniert.

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

Trifft für eine bereits angelegte Bestellung eine weitere Transaktion ein, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, sie im Braintree Control Panel zu prüfen und zu stornieren oder zu erstatten.

Braintree-Zahlungsblock

Die Bestellseite zeigt einen Block Braintree payment mit der Transaktions-ID (verlinkt mit der Transaktion im Braintree Control Panel der jeweiligen Umgebung), dem Transaktionsstatus, dem Betrag und dem Händlerkonto, dem 3-D-Secure-Ergebnis, dem belasteten und erstatteten Betrag, einem Badge Sandbox für Sandbox-Zahlungen und dem Erstattungsverlauf. Die Schaltflächen des Blocks erfordern das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modules-Seiten ist nicht nötig.

Erfassung und Stornierung

Bei einer Bestellung mit dem Status Braintree payment authorized klicken Sie auf Capture Braintree payment, um den Bestellbetrag zu belasten, oder auf Void Braintree authorization, um den zurückgehaltenen Betrag freizugeben. Die Erfassung setzt die Bestellung auf Payment accepted und erfasst die Zahlung; die Stornierung setzt sie auf Canceled. Schlägt die Aktion fehl, wird der Fehler im Block angezeigt und in den Bestellnotizen ergänzt.

Erstattungen

Geben Sie im Block Braintree payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Braintree. Bestätigen Sie die Abfrage Refund this amount through Braintree? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Erstattungen erfolgen in dem Betrag und der Währung, die Braintree belastet hat; nach einer Abweichung von Betrag oder Währung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat. Braintree erstattet nur abgerechnete Transaktionen, in der Regel innerhalb von 24 Stunden. Vor der Abrechnung wird eine vollständige Erstattung als Stornierung durchgeführt; eine Teilerstattung schlägt dann mit einer Meldung fehl, dass auf die Abrechnung gewartet werden muss. Die Erstattung wird an die Umgebung (Sandbox oder Live) der Zahlung gesendet, daher müssen die Zugangsdaten dieser Umgebung hinterlegt sein. Lehnt Braintree die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine Teilerstattung ändert den Status nicht.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Braintree zurück. Chargebacks, abgelehnte Abrechnungen und Erstattungen, die im Braintree Control Panel vorgenommen werden, werden nicht mit PrestaShop synchronisiert.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Braintree Gateway ist der erste Block auf Modules > Module Manager > VibeFox Braintree 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, 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-braintree 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. 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-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 Braintree 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 einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erfassungen, Stornierungen und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern jedoch 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

Braintree erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die gewählte Umgebung eine Merchant ID, einen Public Key und einen Private Key hat. Die Einstellungsseite zeigt eine Warnung, wenn ein Schlüssel fehlt. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe zugelassen ist.

Die Karte wurde belastet, aber es wurde keine Bestellung angelegt: Kartenzahlungen werden sofort bestätigt, ohne Webhook. Sehen Sie im Feld Log auf der Modulseite nach. Meldet das Protokoll, dass die Antwort von Braintree verloren ging, prüfen Sie im Braintree Control Panel, ob eine Transaktion mit der Warenkorbnummer als Bestell-ID existiert, bevor Sie eine weitere Zahlung annehmen. Konnte die Bestellung nach der Belastung nicht angelegt werden, erstellt der nächste Zahlungsversuch für denselben Warenkorb sie ohne erneute Belastung.

Das Kartenformular zeigt Could not initialize payment form: Die Schlüssel der gewählten Umgebung sind falsch, oder die Händlerkonto-ID existiert in diesem Konto nicht. Prüfen Sie die Schlüssel und die Händlerkonto-IDs und laden Sie die Seite neu.

3-D Secure schlägt bei jeder Zahlung fehl: 3-D Secure muss für Ihr Braintree-Händlerkonto aktiviert sein. Wenden Sie sich an den Braintree-Support oder setzen Sie 3-D Secure auf Disabled (im EWR und im Vereinigten Königreich nicht empfohlen, dort ist SCA vorgeschrieben).

Dem Kunden wird mitgeteilt, dass die Zahlung in der Bestellwährung nicht verarbeitet werden konnte: Braintree hat in der Währung des Händlerkontos belastet. Geben Sie die Händlerkonto-ID für die Warenkorbwährung im Feld Händlerkonto der aktuellen Umgebung ein.

Der Kunde sieht die Meldung The order total must be greater than zero to pay by card: Die Warenkorbsumme ist null, zum Beispiel nach einem Gutschein. Solche Bestellungen können nicht mit Karte bezahlt werden.

Eine Teilerstattung schlägt direkt nach der Zahlung fehl: Braintree kann nur abgerechnete Transaktionen erstatten, in der Regel innerhalb von 24 Stunden. Erstatten Sie den vollen Betrag, um die Transaktion jetzt zu stornieren, oder führen Sie die Teilerstattung nach der Abrechnung durch.

Erstattung, Erfassung oder Stornierung schlägt mit einer Meldung zur Umgebung fehl: Die Zahlung wurde in der Sandbox- bzw. Live-Umgebung getätigt, und die Zugangsdaten dieser Umgebung sind nicht hinterlegt. Geben Sie sie ein und versuchen Sie es erneut.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Braintree 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 die Option ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Braintree-Transaktionen und Erstattungen sowie die Bestellstatus Braintree payment authorized und Braintree payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation noch erstattet, erfasst oder storniert werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Braintree ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu Braintree und wird von Braintree nicht unterstützt.