VibeFox Tpay for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer. Die OpenSSL-Erweiterung und ausgehende HTTPS-Verbindungen zu secure.tpay.com sind für die JWS-Signaturprüfung der Benachrichtigungen erforderlich.

Shop-Währung: nur Polnischer Złoty (PLN). Tpay rechnet in PLN ab, und die Open API hat kein Währungsfeld. Deshalb wird die Zahlungsmethode ausgeblendet, wenn der Shop (oder die zu bezahlende Bestellung) eine andere Währung verwendet.

Internetzugang zu Ihrer Website: Tpay sendet Zahlungsbenachrichtigungen an Ihren Shop, daher muss die Benachrichtigungsadresse aus dem Internet erreichbar sein (nicht durch den Wartungsmodus, eine Firewall oder die HTTP-Authentifizierung blockiert).

Tpay-Konto: Sie benötigen diese Werte aus dem Tpay-Händlerpanel: die Merchant ID (Ihre Tpay-Kontonummer), die Open-API-Schlüssel Client ID und Client secret (Integration, API) sowie den Sicherheitscode (Settings, Notifications). Die Sandbox-Schlüssel stammen von einem separaten Tpay-Sandbox-Konto.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert 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_tpay_payment per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Tpay > Manage oder klicken Sie auf der Seite Plugins unter dem Namen des Plugins auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzbereich oben auf der Seite ein und klicken Sie auf Activate.

5. Geben Sie die Sandbox-Schlüssel und die Produktionsschlüssel ein (siehe Konfiguration). Im Tpay-Panel muss außer dem Sicherheitscode nichts eingestellt werden: Die Benachrichtigungsadresse wird bei jeder Transaktion mitgesendet.

6. Aktivieren Sie Enable/Disable, testen Sie eine Zahlung im Sandbox-Modus und deaktivieren Sie anschließend Sandbox mode, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Tpay. Oberhalb der Felder zeigt die Seite Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. an, solange der Sandbox-Modus aktiv ist. Sie warnt, wenn die Schlüssel des aktuellen Modus unvollständig sind (Tpay wird dann nicht an der Kasse angezeigt), wenn die Shop-Währung nicht PLN ist und wenn die PHP-Erweiterung OpenSSL fehlt, während die JWS-Prüfung aktiv ist (Zahlungen würden dann nicht bestätigt). In der Liste der Zahlungsmethoden ist Tpay als einrichtungsbedürftig markiert, bis die Schlüssel des aktuellen Modus eingegeben sind. Leerzeichen, die bei Merchant ID oder Client ID eingefügt wurden, werden beim Speichern entfernt.

Allgemein

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

Title: der Titel der Zahlungsmethode, der Kunden an der Kasse angezeigt wird. Standard: Tpay.

Description: die Beschreibung der Zahlungsmethode, die Kunden an der Kasse angezeigt wird. Standard: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: Use the Tpay sandbox (test payments, no real money). Der Sandbox-Modus verwendet die Sandbox-Schlüssel und die Tpay-Sandbox-API. Deaktivieren Sie ihn, um mit den Produktionsschlüsseln echte Zahlungen anzunehmen. Erstattungen gehen immer an die Umgebung, in der die Bestellung bezahlt wurde. Standard: aktiv.

Produktionsschlüssel

Wo Sie sie finden: im Tpay-Händlerpanel unter Integration, API (Open-API-Schlüssel: Client ID und Secret); die Merchant ID ist Ihre Tpay-Kontonummer; der Sicherheitscode steht unter Settings, Notifications.

Merchant ID: Ihre Tpay-Kontonummer (Ziffern). Tpay sendet sie in jeder Benachrichtigung.

Client ID: die Open-API-Client-ID.

Client secret: das Open-API-Client-Secret.

Security code: wird zur Prüfung der MD5-Prüfsumme der Tpay-Benachrichtigungen verwendet.

Sandbox-Schlüssel

Die Sandbox ist ein separates Tpay-Testkonto mit eigenen Schlüsseln (siehe die Tpay-API-Dokumentation). Sie wird nur verwendet, solange Sandbox mode aktiv ist.

Sandbox Merchant ID: die Merchant ID des Sandbox-Kontos.

Sandbox Client ID: die Open-API-Client-ID des Sandbox-Kontos.

Sandbox Client secret: das Open-API-Client-Secret des Sandbox-Kontos.

Sandbox Security code: der Sicherheitscode für Benachrichtigungen des Sandbox-Kontos.

Zahlungsbenachrichtigungen

Tpay bestätigt Zahlungen an die Adresse, die in diesem Abschnitt angezeigt wird. Sie sieht etwa so aus: https://your-site/wc-api/wc_tp_payment/. Die Adresse wird automatisch bei jeder Transaktion übermittelt; im Tpay-Panel muss außer dem Sicherheitscode nichts eingestellt werden. Eine Bestellung wird erst als bezahlt markiert, wenn eine Benachrichtigung mit gültiger Prüfsumme und Signatur sowie passendem Betrag eingeht. Tpay wiederholt eine Benachrichtigung, bis Ihr Shop sie annimmt.

JWS signature: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Erfordert die PHP-Erweiterung OpenSSL und ausgehende HTTPS-Verbindungen zu secure.tpay.com. Die MD5-Prüfsumme wird immer geprüft. Standard: aktiv.

Erweitert

Debug log: Log payment events. Nur technische Ereignisse (keine Schlüssel, keine Kundendaten) unter WooCommerce > Status > Logs, Quelle wcp_tpay_payment. Standard: aus.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Das Deaktivieren des Plugins löscht nichts. Bestellungen und ihre Tpay-Zahlungsdaten bleiben immer erhalten. Standard: aus.

Einstellungen aus Version 1.0 werden automatisch übernommen: Schlüssel, die mit eingeschaltetem Testmodus verwendet wurden, werden zu den Sandbox-Schlüsseln.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Tpay) und gibt die Bestellung auf. Im Sandbox-Modus zeigt die Kasse Sandbox mode — no real money is charged. an. Das Plugin erstellt für den Bestellbetrag eine Tpay-Transaktion in PLN mit der Beschreibung Order # und der Bestellnummer, übergibt Name, E-Mail-Adresse, Anschrift und Telefonnummer des Kunden und leitet den Kunden auf die Tpay-Zahlungsseite weiter. Die Seite wird je nach Sprache der Website auf Polnisch, Englisch oder Ukrainisch angezeigt (andere Sprachen erhalten Englisch). Dort wählt der Kunde BLIK, eine Banküberweisung, eine Karte oder eine andere in Ihrem Tpay-Konto aktivierte Methode und bezahlt.

Die Bestellung wird erst als bezahlt markiert, wenn Tpay die Zahlung bestätigt. Tpay sendet eine Benachrichtigung an Ihren Shop; das Plugin prüft die MD5-Prüfsumme mit dem Sicherheitscode, die Merchant ID und (wenn aktiv) die JWS-Signatur und danach den Betrag: Er muss dem für diesen Zahlungsversuch angeforderten Betrag und dem Bestellbetrag entsprechen, und der bezahlte Betrag darf nicht niedriger sein. Benachrichtigungen ohne gültige Prüfsumme oder Signatur werden abgelehnt.

Nach der Zahlung kehrt der Kunde zur Seite „Bestellung eingegangen“ zurück. Die Rückkehr allein markiert die Bestellung nicht als bezahlt. Ist die Benachrichtigung noch nicht eingetroffen, fragt die Seite die Tpay API nach dem Status der Transaktion ab (höchstens alle 10 Sekunden) und wendet dieselben Prüfungen an. Solange die Zahlung nicht bestätigt ist, zeigt die Seite Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: mit einem Link Pay again. Meldet Tpay eine fehlgeschlagene Zahlung, zeigt die Seite Tpay reports that the payment did not go through. You can try again: mit demselben Link. Schlägt die Zahlung auf der Tpay-Seite fehl, schickt Tpay den Kunden zur Seite Pay for order derselben Bestellung zurück.

Jeder Zahlungsversuch hat eine eigene Referenz. Wenn der Kunde erneut bezahlt, werden die früheren unbezahlten Tpay-Transaktionen der Bestellung bei Tpay storniert; eine Zahlung, die bereits über einen früheren Link abgeschlossen wurde, wird weiterhin akzeptiert. Dieselbe Stornierung erfolgt, wenn eine unbezahlte Bestellung storniert wird, zum Beispiel durch das Zeitlimit der WooCommerce-Lagerreservierung.

Kann Tpay die Zahlung nicht starten, sieht der Kunde The Tpay payment could not be started. Please try again or choose another payment method. und der Grund wird im Protokoll festgehalten.

Die Zahlungsmethode funktioniert an 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 funktioniert nur in PLN. Im Shop gibt es keine Auswahl von Bank oder BLIK-Code (der Kunde wählt auf der Tpay-Seite), keine gespeicherten Karten, keine Abonnements, keine Apple-Pay- oder Google-Pay-Schaltflächen im Shop und keine Ratenzahlungsrechner.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Tpay-Transaktion wurde erstellt, die Zahlung ist aber noch nicht bestätigt. Die Bestellnotiz zeigt die Tpay-Transaktion und die Umgebung.

Processing: Tpay hat die Zahlung bestätigt. Dies ist der Standardstatus von WooCommerce nach der Zahlung (Bestellungen mit nur virtuellen, herunterladbaren Produkten werden Abgeschlossen). Die Notiz gibt an, ob die Zahlung durch die Benachrichtigung oder durch die Statusprüfung bestätigt wurde, und zeigt eine eventuelle Überzahlung. Die Transaktions-ID ist der Tpay-Transaktionstitel (TR-...).

On hold: Eine Zahlung ist eingegangen, ihr Betrag wich aber vom angeforderten Betrag oder vom Bestellbetrag ab, es wurde nur ein Teil bezahlt, oder die Bestellung war storniert worden. Die Bestellnotiz erklärt dies. Prüfen Sie die Zahlung im Tpay-Panel und schließen Sie die Bestellung ab oder erstatten Sie sie.

Failed: Tpay hat gemeldet, dass die Zahlung fehlgeschlagen ist. Nur eine ausstehende Bestellung wird als Fehlgeschlagen markiert. Der Kunde kann erneut bezahlen.

Meldet Tpay eine weitere Zahlung für eine bereits bezahlte oder erstattete Bestellung, bleibt die Bestellung unverändert; eine Notiz weist darauf hin, dass Sie die zusätzliche Zahlung bei Bedarf im Tpay-Panel erstatten sollten. Ein von Tpay gemeldeter Chargeback fügt eine Notiz hinzu.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Tpay (die Schaltfläche zeigt Ihren Title). Vollständige und teilweise Erstattungen werden für Bestellungen mit einer über Tpay eingegangenen Zahlung unterstützt; bei unbezahlten Bestellungen wird die Schaltfläche nicht angezeigt. Die Erstattung wird an die Umgebung (Sandbox oder Produktion) gesendet, in der die Bestellung bezahlt wurde, daher müssen die Schlüssel dieser Umgebung eingerichtet sein. Die Erstattung gilt erst als abgeschlossen, wenn Tpay sie bestätigt; eine von Tpay abgelehnte oder nicht bestätigte Erstattung wird als Fehler angezeigt und nicht in WooCommerce erfasst. Eine erfolgreiche Erstattung wird den Bestellnotizen zusammen mit dem von Ihnen eingegebenen Grund hinzugefügt (der Grund wird nicht an Tpay gesendet).

Im Tpay-Händlerpanel vorgenommene Erstattungen werden nicht automatisch in WooCommerce übernommen.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich befindet sich oben unter WooCommerce > Settings > Payments > Tpay. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Bereich 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 für eine Domain. Das Entfernen des Schlüssels von einer Website gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Tpay Kunden an 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 Zahlungsmethode weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis 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, arbeitet das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Tpay wird an der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und alle vier Schlüssel des aktuellen Modus eingegeben sind (Merchant ID, Client ID, Client secret, Security code). Prüfen Sie, ob die Shop-Währung (oder auf der Seite Pay for order die Bestellwährung) PLN ist. Die Einstellungsseite zeigt für jedes dieser Probleme eine Warnung an.

Die Zahlung ist erfolgt, die Bestellung bleibt aber Pending payment: Tpay konnte die Benachrichtigung nicht zustellen oder sie wurde abgelehnt. Aktivieren Sie Debug log und sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_tpay_payment, nach. Häufige Ursachen sind ein falscher Sicherheitscode oder eine falsche Merchant ID für den aktuellen Modus, eine blockierte Benachrichtigungsadresse (Wartungsmodus, Firewall, HTTP-Authentifizierung) oder ein Server ohne OpenSSL bzw. ohne ausgehende HTTPS-Verbindung für die JWS-Prüfung. Die Seite „Bestellung eingegangen“ prüft den Status ebenfalls, wenn der Kunde zurückkehrt.

Notification answered FALSE - invalid checksum: Die Merchant ID oder der Sicherheitscode in den Einstellungen stimmt nicht mit dem Tpay-Konto (Sandbox oder Produktion) der Zahlung überein.

Notification answered FALSE - invalid JWS signature: Die Signatur konnte nicht geprüft werden, etwa weil OpenSSL fehlt oder das Tpay-Zertifikat nicht heruntergeladen werden kann. Beheben Sie das Problem auf dem Server oder deaktivieren Sie bei Bedarf JWS signature; die MD5-Prüfsumme wird weiterhin geprüft.

Die Bestellung ist On hold: Lesen Sie die Bestellnotiz. Der bezahlte Betrag stimmte nicht mit der Bestellung überein, oder die Zahlung kam für eine stornierte Bestellung an. Prüfen Sie die Zahlung im Tpay-Panel und schließen Sie die Bestellung ab oder erstatten Sie sie.

Der Kunde sah The Tpay payment could not be started: Die Schlüssel des aktuellen Modus sind falsch oder Tpay hat die Anfrage abgelehnt. Das Protokoll zeigt den Tpay-Fehler.

Erstattung schlägt fehl: Meldet die Nachricht, dass Schlüssel fehlen, geben Sie die Schlüssel der Umgebung ein, in der die Bestellung bezahlt wurde. Hat Tpay die Erstattung nicht bestätigt, prüfen Sie die Transaktion im Tpay-Händlerpanel, bevor Sie es erneut versuchen.

Der Lizenzbereich zeigt einen Fehler: Folgen Sie der Meldung im Bereich. Ist der Schlüssel zum Beispiel bereits für eine andere Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Wurde 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 werden immer entfernt, ebenso die zwischengespeicherten Tpay-Zugriffstoken und Zertifikate. Die Einstellungen des Gateways und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Tpay-Transaktionsdaten und Transaktions-IDs.

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