VibeFox Braintree for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv.

PHP: 8.0 oder neuer.

HTTPS: Ihre Website sollte HTTPS verwenden.

Braintree-Konto: Sie benötigen Merchant ID, Public Key und Private Key Ihres Braintree-Kontos. Sie finden sie im Braintree Control Panel (Sandbox: sandbox.braintreegateway.com, Live: www.braintreegateway.com) unter dem Zahnrad-Symbol, API, API Keys. Sandbox- und Live-Konten haben unterschiedliche Schlüssel. 3-D Secure muss für Ihr Braintree-Händlerkonto aktiviert sein, sofern Sie 3-D Secure nicht auf Disabled setzen. Ein Webhook ist nicht nötig.

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_braintree_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Braintree > 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. Kopieren Sie Merchant ID, Public Key und Private Key aus dem Braintree Control Panel in die Felder für Sandbox oder Live.

6. Schalten Sie Enable/Disable ein. Lassen Sie Sandbox mode eingeschaltet und führen Sie eine Testbestellung mit einer Braintree-Testkarte durch, zum Beispiel 4111 1111 1111 1111 mit einem beliebigen zukünftigen Ablaufdatum. Für 3-D Secure verwenden Sie die 3-D-Secure-Testkarten von Braintree.

7. Entfernen Sie das Häkchen bei Sandbox mode, um mit den Live-Zugangsdaten echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Braintree. Ist das Gateway aktiviert, aber die Merchant ID, der Public Key oder der Private Key des gewählten Modus fehlt, warnt die Seite, dass die Zahlungsmethode an der Kasse ausgeblendet bleibt, bis sie ausgefüllt sind. Die Seite zeigt nur die Zugangsdatenfelder des gewählten Modus; beide Sätze bleiben gespeichert.

Allgemein

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Credit / debit card.

Description: der Text über dem Kartenformular an der Kasse. Standard: Pay securely with your credit or debit card via Braintree.

API-Zugangsdaten

Melden Sie sich im Braintree Control Panel (Sandbox oder Live) an, klicken Sie auf das Zahnrad-Symbol, dann auf API und API Keys. Dort sind die öffentlichen und privaten Schlüssel aufgeführt; die Merchant ID steht auf derselben Seite.

Sandbox mode: Use the Braintree sandbox (test payments, no real money). Standard: ein. Entfernen Sie das Häkchen, um mit den Live-Zugangsdaten echte Zahlungen anzunehmen. Erstattungen, Erfassungen und Stornierungen verwenden immer die Umgebung, in der die Bestellung bezahlt wurde.

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.

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 ein (zum Beispiel mystore_EUR) oder je Währung eine: 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 wird nicht belastet.

Zahlung

Transaction type: wie die Karte belastet wird.

3-D Secure: 3-D Secure 2 (starke Kundenauthentifizierung) ist für die meisten Kartenzahlungen im EWR und im Vereinigten Königreich vorgeschrieben. Es muss außerdem für Ihr Braintree-Konto aktiviert sein.

Erweitert

Debug log: Also log API calls and payment steps (errors are always logged). Protokolle finden Sie unter WooCommerce > Status > Logs, Quelle wcp_braintree_gateway. Sie enthalten nie API-Schlüssel, Karten- oder Kundendaten. Standard: aus.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Credit / debit card) und gibt die Karte im Braintree-Formular auf der Kassenseite ein. Im Sandbox-Modus zeigt das Formular SANDBOX / TEST MODE — no real money is charged. Ist 3-D Secure eingeschaltet, bestätigt der Kunde beim Aufgeben der Bestellung die Authentifizierung seiner Bank.

Das Plugin belastet das Einmal-Token über die Braintree-API für den Bestellbetrag in der Bestellwährung und verwendet die Bestellnummer als Bestell-ID. Die Bestellung wird nur auf Grundlage der authentifizierten Antwort von Braintree als bezahlt markiert, nachdem Betrag und Währung mit der Bestellung abgeglichen wurden. Wird die Zahlung genehmigt, gelangt der Kunde zur Seite „Bestellung eingegangen“. Kartenzahlungen brauchen keinen Webhook: Das Ergebnis ist sofort bekannt.

Schlägt die Zahlung fehl, bleibt die Bestellung auf „Zahlung ausstehend“, der Grund wird den Bestellnotizen hinzugefügt, und der Kunde sieht eine klare 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. Stimmt die belastete Währung nicht mit der Bestellung ü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.

Eine Bestellung wird nie doppelt belastet: Ein zweites Absenden, 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.

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.

Das Plugin akzeptiert nur Kartenzahlungen. Es bietet keine gespeicherten Karten (Vaulting), keine WooCommerce Subscriptions oder Vorbestellungen, kein PayPal, Venmo, Apple Pay, Google Pay, ACH oder lokale Zahlungsmethoden, keine Braintree-Webhooks sowie keine Level-2/3-Daten, Artikelpositionen oder Fastlane.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Zahlung wurde noch nicht geleistet oder abgelehnt.

Processing or Completed: Die Karte wurde belastet (Sale) oder eine Autorisierung wurde erfasst. WooCommerce setzt den Status „In Bearbeitung“ oder bei Bestellungen, die nur virtuelle herunterladbare Produkte enthalten, „Abgeschlossen“. Die Bestellnotiz zeigt Betrag, Transaktions-ID und das Ergebnis von 3-D Secure. Die Transaktions-ID ist die Braintree-Transaktions-ID; auf der Bestellseite verlinkt sie zur Transaktion im Braintree Control Panel.

On hold: Die Mittel sind nur autorisiert (Authorize only). Eine Bestellung wird ebenfalls auf Wartend gesetzt, wenn Braintree einen unerwarteten Transaktionsstatus zurückgibt oder wenn eine Belastung in der falschen Währung nicht automatisch storniert werden konnte. Die Bestellnotiz erklärt, was im Braintree Control Panel zu prüfen ist.

Cancelled: Eine Autorisierung wurde mit Void Braintree authorization storniert.

Erfassung und Stornierung

Öffnen Sie bei einer Bestellung mit Autorisierung die Bestellung, wählen Sie unter den Bestellaktionen Capture Braintree payment oder Void Braintree authorization und klicken Sie auf die Schaltfläche zum Aktualisieren. Die Erfassung markiert die Bestellung als bezahlt; die Stornierung storniert die Bestellung und gibt den gesperrten Betrag an den Kunden frei. Schlägt die Aktion fehl, wird der Fehler auf der Bestellseite angezeigt und den Bestellnotizen hinzugefügt.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit / debit card (die Schaltfläche verwendet den Titel Ihrer Zahlungsmethode). Vollständige und Teilerstattungen werden unterstützt. Braintree kann nur abgerechnete Transaktionen erstatten, in der Regel innerhalb von 24 Stunden. Vor der Abrechnung wird eine vollständige Erstattung als Stornierung ausgefü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) gesendet, in der die Bestellung bezahlt wurde. Akzeptiert Braintree die Erstattung nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung verbucht. Eine erfolgreiche Erstattung oder Stornierung wird den Bestellnotizen hinzugefügt.

Chargebacks (Rückbuchungen) und abgelehnte Abrechnungen werden nicht mit WooCommerce synchronisiert. Prüfen Sie sie im Braintree Control Panel.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Braintree. 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 Braintree 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: Erfassungen, Stornierungen 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

Braintree erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der gewählte Modus eine Merchant ID, einen Public Key und einen Private Key hat. Die Einstellungsseite zeigt eine Warnung, wenn ein Schlüssel fehlt.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt bei Pending payment: Kartenzahlungen werden sofort bestätigt, ohne Webhook. Steht in der Bestellnotiz, dass die Antwort von Braintree verloren ging, prüfen Sie im Braintree Control Panel, ob es eine Transaktion mit dieser Bestellnummer gibt, bevor Sie eine weitere Zahlung annehmen. Schalten Sie das Debug log ein und sehen Sie in WooCommerce > Status > Logs, Quelle wcp_braintree_gateway, nach.

Das Kartenformular zeigt Could not initialize payment form: die Schlüssel des gewählten Modus 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 (nicht empfohlen im EWR und im Vereinigten Königreich, wo SCA vorgeschrieben ist).

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

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.

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 und die Protokolle werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Die Braintree-Daten an den Bestellungen bleiben immer erhalten, weil sie für Erstattungen nach einer Neuinstallation benötigt werden. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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