VibeFox TrustPay for WooCommerce — Hilfe
Anforderungen
WordPress: 6.0 oder neuer.
WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.
PHP: 8.0 oder neuer.
finby-Konto (TrustPay): Sie benötigen ein Projekt im finby Merchant Portal mit Project ID und Secret Key. Für Testzahlungen benötigen Sie ein separates Test-Projekt (Playground) mit eigener Project ID und eigenem Secret Key. Weitere Schlüssel sind nicht nötig: Der Secret Key dient sowohl dem API-Zugriff als auch der Prüfung der Signatur von Zahlungsbenachrichtigungen.
Erreichbare Benachrichtigungs-URL: finby muss Ihre Website aus dem Internet erreichen können. Eine Firewall, der Wartungsmodus oder ein Passwortschutz der Website blockiert die Zahlungsbenachrichtigungen.
VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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. Sie können den Ordner wcp_trustpay_gateway auch per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > TrustPay / finby, oder klicken Sie auf der Seite Plugins 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. Geben Sie Project ID und Secret Key Ihres Live-Projekts und für Tests die Ihres Test-Projekts ein (siehe Konfiguration).
6. Aktivieren Sie Enable / Disable und speichern Sie. Führen Sie eine Testzahlung mit aktiviertem Test mode durch und deaktivieren Sie danach Test mode, um echte Zahlungen anzunehmen.
Wenn Sie von Version 1.0 aktualisieren, bleiben Ihre Project ID und Ihr Secret Key als Live-Zugangsdaten erhalten, und der Testmodus wird deaktiviert. Prüfen Sie die Einstellungen nach dem Update.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > TrustPay / finby. Oberhalb der Felder warnt Sie die Seite, wenn das Gateway aktiviert ist, aber Project ID oder Secret Key des aktuellen Modus leer sind, und wenn die Shop-Währung nicht unterstützt wird. In beiden Fällen wird die Zahlungsart in der Kasse ausgeblendet. In der Liste der Zahlungsarten ist das Gateway als einrichtungsbedürftig markiert, bis der aktuelle Modus Project ID und Secret Key hat.
Allgemein
Enable / Disable: Enable TrustPay / finby card payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den Kunden in der Kasse sehen. Standard: Card payment (TrustPay).
Description: der Text unter der Zahlungsart in der Kasse. Standard: Pay securely by card on the TrustPay / finby payment page.
API-Zugangsdaten
Kopieren Sie Project ID und Secret Key Ihres Projekts aus dem finby (TrustPay) Merchant Portal. Der Abschnitt enthält einen Link zum Merchant Portal. Testzahlungen nutzen ein separates Test-Projekt (Playground) mit eigener Project ID und eigenem Secret Key. Dort wird kein echtes Geld abgebucht.
Test mode: Use the test project (no real payments). Neue Zahlungen und Erstattungen verwenden die Testzugangsdaten. Erstattungen einer Bestellung gehen immer an das Projekt, über das die Bestellung bezahlt wurde. Standard: an.
Live Project ID: die numerische Project ID Ihres Live-Projekts.
Live Secret key: der Secret Key des Live-Projekts. Er wird benötigt, um API-Zugriffstoken zu erhalten und Zahlungsbenachrichtigungen zu prüfen.
Test Project ID: die numerische Project ID Ihres Test-Projekts (Playground).
Test Secret key: der Secret Key des Test-Projekts.
Eine Project ID darf nur Ziffern enthalten. Wenn Sie einen anderen Wert speichern, zeigt die Seite einen Fehler, und der bisherige Wert bleibt erhalten. Secret Keys werden genau so gespeichert, wie Sie sie eingeben; nur Leerzeichen am Anfang und Ende werden entfernt.
Zahlungsbenachrichtigungen
Die Bestellung wird nur als bezahlt markiert, wenn finby die Zahlung mit einer signierten Benachrichtigung bestätigt. Das Plugin sendet die Benachrichtigungs-URL bei jeder Zahlung automatisch, Sie müssen sie also nicht einrichten. Der Abschnitt zeigt die URL, zum Beispiel https://your-site/wc-api/trustpay_payment_callback/. Sie können sie auch als Benachrichtigungs-URL Ihrer Projekte im Merchant Portal eintragen. Benachrichtigungen ohne gültige Signatur werden abgelehnt.
Das Plugin fragt finby nicht selbst nach dem Zahlungsstatus. Wenn eine Benachrichtigung Ihre Website nicht erreicht, bleibt die Bestellung auf Pending payment, bis finby sie zustellt.
Erweitert
Order status after payment: der Bestellstatus nach einer erfolgreichen Zahlung. Der Status wird in einem Schritt gesetzt, sodass der Kunde nur eine E-Mail erhält.
Debug logging: Log API requests and notifications fügt dem Protokoll Details hinzu. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Die Protokolle finden Sie unter WooCommerce > Status > Logs, Quelle wcp_trustpay_gateway. Sie enthalten keine Schlüssel, Token, Kartendaten oder Kundendaten. Standard: aus.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). Standard: aus.
Kasse
Der Kunde wählt die Zahlungsart (standardmäßig Card payment (TrustPay)) und gibt die Bestellung auf. Im Testmodus zeigt die Kasse unter der Beschreibung Test mode: no real payment will be taken. an.
Kartenzahlungen benötigen die Rechnungsadresse. Fehlt Straße, Ort, Postleitzahl oder Land, sieht der Kunde Please enter your billing address (street, city, postcode and country) — it is required for card payments.
Das Plugin erstellt bei finby eine Kartenzahlungsanfrage für den Bestellbetrag in der Bestellwährung. Name, Adresse und E-Mail-Adresse des Kunden werden für 3-D Secure übermittelt, die Bestell-ID als Referenz. Der Kunde wird zur Zahlungsseite von finby weitergeleitet und zahlt dort mit Karte. Die Seite öffnet sich in der Sprache Ihres Shops, sofern finby sie unterstützt, andernfalls auf Englisch. Eine Notiz zur Bestellung zeigt die Zahlungsanfrage, den Betrag und das Projekt (Test oder Live).
Nach der Zahlung kehrt der Kunde zur Bestellbestätigung Ihres Shops zurück, und der Warenkorb wird geleert. Die Bestellung wird erst als bezahlt markiert, wenn finby dies mit der signierten Benachrichtigung bestätigt. Die Rückkehr selbst ändert den Zahlungsstatus nie.
Bricht der Kunde auf der Zahlungsseite ab oder meldet die Zahlungsseite einen Fehler, kehrt er zur Seite Pay for order zurück, mit der Meldung The card payment was cancelled. You can try again or choose another payment method. oder The card payment was not completed. Please try again or choose another payment method. Der Bestellung wird eine Notiz hinzugefügt. Der Kunde kann auf dieser Seite erneut bezahlen.
Kann finby die Zahlung nicht starten, sieht der Kunde We could not start the card payment. Please try again in a moment or choose another payment method. Der technische Grund wird im Protokoll festgehalten.
Währungen: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF und USD. HUF-Beträge werden ohne Dezimalstellen übermittelt. Auf der Seite Pay for order wird die Bestellwährung geprüft.
Die Zahlungsart funktioniert in der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel. Das Plugin enthält Übersetzungen für Englisch, Slowakisch und Tschechisch.
Das Plugin akzeptiert nur Kartenzahlungen als Kauf in einem Schritt auf der finby-Seite. Es gibt keine Banküberweisungen oder andere Zahlungsarten von finby, keine Apple-Pay- oder Google-Pay-Buttons, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine getrennte Autorisierung und Erfassung und keine Statusabfrage.
Bestellungen und Erstattungen
Bestellstatus
Pending payment: Der Kunde wurde zu finby weitergeleitet und hat noch nicht bezahlt, oder die Benachrichtigung ist noch nicht eingegangen.
Processing or Completed: finby hat die Zahlung bestätigt, und Betrag und Währung stimmen mit der Zahlungsanfrage und dem Bestellbetrag überein. Der Status richtet sich nach Order status after payment. Die Bestellnotiz zeigt Betrag, Zahlungsanfrage und Projekt. Die Transaktions-ID ist die Zahlungsanfrage-ID von finby.
On hold: wird in drei Fällen gesetzt. Die Zahlung ist bei finby noch offen, und die Bestellung wartet auf das Endergebnis. Die Zahlung wurde nur autorisiert, nicht erfasst: Erfassen oder stornieren Sie sie im finby Merchant Portal und aktualisieren Sie dann die Bestellung. Oder der bezahlte Betrag oder die Währung weicht von der Zahlungsanfrage oder dem Bestellbetrag ab, etwa weil die Bestellung bearbeitet wurde, nachdem der Kunde zur Zahlungsseite geschickt wurde: Prüfen Sie die Zahlung vor dem Versand. Die Bestellnotiz erklärt den Fall.
Failed: finby hat die letzte Zahlung der Bestellung abgelehnt. Die Notiz zeigt den Grund, wenn finby ihn übermittelt. Der Kunde kann über Pay for order erneut bezahlen.
Stornierte oder erstattete Bestellungen werden durch eine späte Zahlung nie wieder geöffnet. Eine Notiz bittet Sie, die Bestellung wiederherzustellen oder die Zahlung im Merchant Portal zu erstatten. Trifft eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert, und eine Notiz bittet Sie, die doppelte Zahlung im Merchant Portal zu erstatten. Von finby gemeldete Chargebacks und Disputes werden als Notizen hinzugefügt.
Erstattungen
Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Card payment (TrustPay) (die Schaltfläche zeigt Ihren Title). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung geht an das Projekt, über das die Bestellung bezahlt wurde (Test oder Live), auch wenn Sie seitdem den Modus gewechselt haben. Daher müssen Project ID und Secret Key dieses Modus eingetragen sein. Erstattungen in HUF müssen ganze Beträge sein.
Eine Erstattung wird nur erfasst, wenn finby sie annimmt. Andernfalls zeigt WooCommerce TrustPay refused the refund: mit dem Grund an, und es wird keine Erstattung erstellt. Eine erfolgreiche Erstattung wird den Bestellnotizen hinzugefügt.
Im finby Merchant Portal vorgenommene Erstattungen werden nicht als WooCommerce-Erstattungen erfasst. Sendet finby dazu eine Benachrichtigung, wird sie als Bestellnotiz hinzugefügt, und der Bestellstatus ändert sich nicht.
Lizenzschlüssel
Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > TrustPay / finby. 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 funktioniert auf einer 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 die Zahlungsart Kunden in der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.
Läuft eine Lizenz ab, funktioniert das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.
Fehlerbehebung
Card payment (TrustPay) erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und der aktuelle Modus Project ID und Secret Key hat: Test Project ID und Test Secret key im Testmodus, Live Project ID und Live Secret key im Live-Modus. Die Shop-Währung bzw. die Bestellwährung auf der Seite Pay for order muss eine der unterstützten Währungen sein. Die Einstellungsseite zeigt in beiden Fällen eine Warnung. Entwickler können die Währungsliste mit dem Filter trustpay_p_supported_currencies ändern.
Die Zahlung war erfolgreich, aber die Bestellung bleibt auf Pending payment: Die Benachrichtigung hat Ihren Shop nicht erreicht. Prüfen Sie, dass https://your-site/wc-api/trustpay_payment_callback/ aus dem Internet erreichbar ist (keine Firewall, kein Wartungsmodus, kein Passwortschutz). finby wiederholt die Benachrichtigung. Sehen Sie im Protokoll unter WooCommerce > Status > Logs, Quelle wcp_trustpay_gateway, nach.
Das Protokoll zeigt Notification rejected: invalid signature or unknown project: Die Benachrichtigung kam von einem Projekt, dessen Project ID nicht in den Einstellungen steht, oder der Secret Key dieses Projekts ist falsch. Der Shop antwortet mit Invalid signature, und die Bestellung wird nicht geändert. Prüfen Sie Project ID und Secret Key des Modus, in dem die Zahlung erfolgte.
Das Protokoll zeigt Notification ignored: Die Benachrichtigung gehört zu einer Zahlungsanfrage, die dieser Shop nicht für diese Bestellung erstellt hat, oder zu einem anderen Projekt als dem, mit dem die Zahlung gestartet wurde. Die Bestellung wird nicht geändert.
Die Benachrichtigung wird mit Busy, retry later beantwortet: Die Bestellung wurde im selben Moment von einer anderen Benachrichtigung aktualisiert. finby wiederholt sie.
Der Kunde sieht We could not start the card payment: Öffnen Sie das Protokoll. Eine falsche Project ID oder ein falscher Secret Key führt zu der Meldung, dass finby die Zugangsdaten des Projekts abgelehnt hat. Prüfen Sie, dass die Testdaten in den Testfeldern und die Livedaten in den Livefeldern stehen.
Kartenzahlung vorübergehend nicht verfügbar: Der Kunde sieht diese Meldung, wenn dem aktuellen Modus Project ID oder Secret Key fehlen. Tragen Sie sie ein und speichern Sie.
Bestellung ist On hold mit der Notiz zu Betrags- oder Währungsabweichung: Die Benachrichtigung war echt, aber der bezahlte Betrag oder die Währung weicht von der Zahlungsanfrage oder dem Bestellbetrag ab. Prüfen Sie die Zahlung im Merchant Portal vor dem Versand und erfüllen Sie dann die Bestellung oder erstatten Sie die Zahlung.
Erstattung schlägt mit einer Meldung zum Projekt fehl: Die Bestellung wurde über das Test- oder Live-Projekt bezahlt, und Project ID oder Secret Key dieses Modus sind nicht eingetragen oder es ist nun eine andere Project ID gespeichert. Geben Sie die Zugangsdaten dieses Projekts ein oder erstatten Sie die Zahlung im finby Merchant Portal.
Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel etwa 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
Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins sowie die zwischengespeicherten API-Zugriffstoken werden immer entfernt. Die Gateway-Einstellungen und die Plugin-Protokolle (Protokolldateien einschließlich älterer rotierter Dateien und Protokolleinträge in der Datenbank) werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestelldaten bleiben erhalten: Bestehende Bestellungen behalten ihre Zahlungsnotizen, Zahlungsanfrage-IDs und Transaktions-IDs.
TrustPay und finby sind Marken ihrer jeweiligen Inhaber. Dieses Plugin ist nicht mit TrustPay oder finby verbunden und wird von keinem der beiden unterstützt.