VibeFox Paytrail for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder höher.

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

PHP: 8.0 oder höher.

Shop-Währung: EUR. Paytrail akzeptiert ausschließlich Euro. Bei jeder anderen Währung wird die Zahlungsmethode an der Kasse ausgeblendet. Beträge werden in Cent übermittelt.

Internetzugriff auf Ihre Website: Paytrail bestätigt jede Zahlung über einen Server-zu-Server-Callback; daher sollte die Website aus dem Internet erreichbar sein. Auch ohne Callbacks werden Bestellungen bestätigt, wenn der Kunde von Paytrail zurückkehrt.

Paytrail-Konto: Sie benötigen Ihre Merchant ID und Ihren Secret Key, die im Paytrail-Händlerportal (Konto- oder Integrationsdetails) angezeigt werden. Für Tests ist kein Konto erforderlich: Der Testmodus nutzt das öffentliche Paytrail-Testkonto. Die Zahlungsmethoden selbst werden in Ihrem Paytrail-Konto aktiviert.

VibeFox-Lizenzschlüssel: erworben auf vibefox.net. 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 aus und klicken Sie auf Install Now. Alternativ können Sie den Ordner wcp_paytrail_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

5. Um das Plugin zunächst auszuprobieren, aktivieren Sie Test mode. Für echte Zahlungen deaktivieren Sie das Häkchen und tragen Sie Ihre Merchant ID sowie Ihren Secret key ein. In Paytrail muss keine Callback-URL eingerichtet werden.

6. Aktivieren Sie Enable/Disable und speichern Sie.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Paytrail. Oberhalb der Felder zeigt die Seite Test mode is active. an, solange der Testmodus aktiv ist. Im Live-Modus warnt sie, wenn die Merchant ID oder der Secret Key fehlt, sowie wenn die Shop-Währung nicht EUR ist. In beiden Fällen wird Paytrail an der Kasse nicht angezeigt. In der Liste der Zahlungsmethoden wird Paytrail als einrichtungsbedürftig gekennzeichnet, solange im Live-Modus Zugangsdaten fehlen.

Beim Speichern wird eine Merchant ID, die andere Zeichen als Ziffern enthält, nicht gespeichert: Es wird ein Fehler angezeigt und der bisherige Wert beibehalten.

General

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

Title: der Titel, der Kunden während der Kasse angezeigt wird. Standard: Paytrail.

Description: der Text, der Kunden während der Kasse angezeigt wird. Standard: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API credentials

Ihre Merchant ID und Ihr Secret Key werden im Paytrail-Händlerportal (Konto- oder Integrationsdetails) angezeigt. Es werden nur Zahlungen in EUR unterstützt.

Test mode: Use the Paytrail test account. Neue Zahlungen nutzen das öffentliche Paytrail-Testkonto (Merchant ID 375917) anstelle Ihrer eigenen Zugangsdaten. Es wird kein echtes Geld abgebucht. Kunden sehen an der Kasse Test mode: no real payment will be made.. Der Secret Key des Testkontos ist öffentlich, sodass jeder eine Zahlung für eine im Testmodus erstellte Bestellung simulieren könnte. Lassen Sie den Testmodus in einem Live-Shop niemals aktiviert. Standard: aus.

Merchant ID: Ihre Paytrail Merchant ID (nur Ziffern). Wird verwendet, wenn der Testmodus aus ist.

Secret key: Ihr Paytrail Secret Key. Wird verwendet, wenn der Testmodus aus ist.

Callbacks und Erstattungen verwenden immer die Zugangsdaten des Modus, in dem die Zahlung erfolgt ist; das Umschalten zwischen Test- und Live-Modus beeinträchtigt ältere Bestellungen daher nicht.

Orders

Dieser Abschnitt zeigt die Callback-URL an, die etwa wie https://your-site/wc-api/ptg_paytrail/ aussieht. Paytrail bestätigt jede Zahlung per Server-zu-Server-Aufruf an diese URL. Sie wird mit jeder Zahlung übermittelt, sodass im Paytrail-Portal nichts konfiguriert werden muss; die Website muss jedoch aus dem Internet erreichbar sein.

Order status after payment: der Status einer bezahlten Bestellung. Der Status wird in einem Schritt gesetzt, sodass der Kunde nur eine Reihe von E-Mails erhält.

Advanced

Debug log: Log API requests and callbacks. Wird nach WooCommerce > Status > Logs geschrieben, Quelle wcp_paytrail_gateway, ohne personenbezogene Daten oder Schlüssel. Fehler werden immer protokolliert. Standard: aus.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. Das Deaktivieren des Plugins löscht niemals Daten. Ohne die Paytrail-Transaktionsdaten sind Erstattungen alter Bestellungen aus WooCommerce heraus nicht mehr möglich. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Paytrail) und gibt die Bestellung auf. Das Plugin erstellt eine Paytrail-Zahlung über den Gesamtbetrag der Bestellung in Euro und übermittelt die Bestellpositionen: Produkte, Versand und Gebühren, jeweils mit dem Mehrwertsteuersatz auf eine Nachkommastelle gerundet. Die Positionen ergeben in der Summe stets den Zahlungsbetrag; eine Rundungsdifferenz wird in eine Position eingerechnet oder als Position Rounding übermittelt. Rechnungs- und Lieferadressen werden nur übermittelt, wenn sie vollständig sind, und lange Werte werden auf die Paytrail-Grenzwerte gekürzt. Die Sprache der Zahlungsseite ist Finnisch, Schwedisch oder Englisch, passend zum Gebietsschema des Shops.

Der Kunde wird zur Paytrail-Zahlungsseite weitergeleitet, wählt eine für Ihr Paytrail-Konto aktivierte Zahlungsmethode und bezahlt. Paytrail bestätigt die Zahlung anschließend doppelt: Es leitet den Kunden zurück zu Ihrem Shop und ruft die Callback-URL per Server-zu-Server-Aufruf auf. Beide werden nur mit einer gültigen Signatur akzeptiert, die mit den Zugangsdaten dieses Zahlungsversuchs erstellt wurde, und nur für den für diese Bestellung erstellten Versuch. Der bezahlte Betrag wird mit der Gesamtsumme der Bestellung verglichen. Erst wenn Paytrail die Zahlung auf diese Weise bestätigt, wird die Bestellung als bezahlt markiert. Das Plugin verarbeitet folgende Paytrail-Status:

Nach erfolgreicher Zahlung sieht der Kunde die Seite „Bestellung erhalten“. Nach einer abgebrochenen oder fehlgeschlagenen Zahlung gelangt der Kunde zur Seite Pay for order mit dem Hinweis The Paytrail payment was cancelled or failed. You can try again or choose another payment method.. Ist die Zahlung noch nicht abgeschlossen, lautet der Hinweis The Paytrail payment has not been completed yet. You can try again or choose another payment method..

Kann Paytrail die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (falsche Zugangsdaten) oder Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method.. Die technische Ursache wird in den Bestellnotizen und im Protokoll vermerkt. Bestellungen über dem Höchstbetrag von Paytrail können nicht über Paytrail bezahlt werden.

Eine Paytrail-Zahlung kann nicht über die API storniert werden. Wenn der Kunde eine neue Zahlung startet und danach auch eine ältere, noch offene Zahlungsseite bezahlt, wird die zweite Zahlung in den Bestellnotizen als zu erstattendes Duplikat gemeldet.

Die Zahlungsmethode funktioniert an der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist kompatibel mit WooCommerce High-Performance Order Storage (HPOS).

Der Kunde wählt die Zahlungsmethode auf der Paytrail-Seite, nicht in Ihrer Kasse. Das Plugin bietet keine Kartentokenisierung oder gespeicherte Karten, kein WooCommerce Subscriptions, kein Shop-in-Shop, keine manuelle Rechnungsaktivierung und keine Abrechnungsberichte.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: die Paytrail-Zahlung wurde erstellt und der Kunde hat noch nicht bezahlt. Die Bestellnotiz zeigt die Paytrail-Transaktions-ID, den Betrag und den Modus.

Processing or Completed: die Zahlung wurde bestätigt. Der Status richtet sich nach Order status after payment. Die Bestellnotiz zeigt die Transaktion, die bei Paytrail verwendete Zahlungsmethode und den Betrag. Die Transaktions-ID ist die Paytrail-Transaktions-ID.

On hold: die Zahlung steht beim Anbieter aus (Rechnung oder verzögerte Zahlung), der bezahlte Betrag weicht vom Gesamtbetrag der Bestellung ab, die Zahlung traf nach Stornierung der Bestellung ein oder eine Testzahlung ging im Live-Modus ein (kein echtes Geld). Die Bestellnotiz erläutert den Grund. Prüfen Sie die Bestellung und führen Sie sie anschließend aus oder erstatten Sie die Zahlung.

Failed: der letzte Zahlungsversuch ist fehlgeschlagen oder wurde vom Kunden abgebrochen. Der Kunde kann erneut bezahlen.

Wiederholte oder parallele Callbacks erzeugen niemals doppelte Notizen, Lagerbestandsreduzierungen oder E-Mails. Wird ein zweiter Versuch einer bereits bezahlten Bestellung bezahlt, wird die Bestellung nicht erneut geändert; eine Notiz Duplicate payment fordert Sie auf, den Betrag im Paytrail-Händlerportal zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Paytrail (die Schaltfläche zeigt Ihren Title). Es werden vollständige und Teil-Erstattungen unterstützt, ausschließlich für Beträge (keine Erstattung einzelner Positionen). Die Schaltfläche ist nur bei Bestellungen mit einer bestätigten Paytrail-Zahlung verfügbar. Die Erstattung nutzt die Zugangsdaten des Modus, in dem die Zahlung erfolgt ist; für eine Live-Zahlung müssen also die Live-Zugangsdaten hinterlegt sein.

Unterstützt die Zahlungsmethode keine direkten Erstattungen, leitet das Plugin automatisch eine E-Mail-Erstattung ein: Paytrail sendet dem Kunden eine E-Mail zur Eingabe eines Bankkontos. Hierfür ist eine Rechnungs-E-Mail-Adresse an der Bestellung erforderlich. Die Bestellnotiz gibt an, welche Art der Erstattung eingeleitet wurde.

Eine Erstattung kann sofort abgeschlossen oder später verarbeitet werden. Die spätere Bestätigung von Paytrail wird als Notiz hinzugefügt. Konnte Paytrail die Erstattung nicht abschließen, weist eine Notiz darauf hin, dass das Geld nicht an den Kunden zurückgezahlt wurde: Erstatten Sie den Betrag auf anderem Weg und löschen Sie die WooCommerce-Erstattung. Lehnt Paytrail die Erstattung sofort ab, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst.

Im Paytrail-Händlerportal vorgenommene Erstattungen werden nicht mit WooCommerce synchronisiert.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Paytrail. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status an, beispielsweise das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Verwenden Sie Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um ihn von dieser Website zu entfernen. Der Link Manage licenses and domains in your account öffnet Ihr Konto auf vibefox.net.

Ein Schlüssel funktioniert auf einer 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 Paytrail den Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one.. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin mit dem Vermerk (unlicensed — visible to admins only), sodass Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. 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, für Updates und Support ist jedoch eine Verlängerung erforderlich. Der Status wird im Hintergrund automatisch erneut überprüft.

Fehlerbehebung

Paytrail erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable aktiviert ist und entweder Test mode aktiv ist oder Merchant ID und Secret key ausgefüllt sind. Prüfen Sie, ob die Shop-Währung (oder die Bestellwährung auf der Seite Pay for order) EUR ist. Die Einstellungsseite zeigt für jedes dieser Probleme eine Warnung an.

Die Zahlung ging durch, aber die Bestellung bleibt auf Pending payment: der Callback kann Ihre Website nicht erreichen und der Kunde ist nicht zum Shop zurückgekehrt. Die im Abschnitt Orders angezeigte Callback-URL muss aus dem Internet erreichbar sein (kein Wartungsmodus, keine HTTP-Basisauthentifizierung oder zwischengeschaltete Firewall).

Callback oder Rückkehr antwortet mit Payment verification failed.: die Signatur ist ungültig oder die Zahlung gehört nicht zu einem Zahlungsversuch dieser Bestellung. Die Bestellung wird nicht verändert. Prüfen Sie, ob der Secret key korrekt ist und zur Merchant ID gehört.

Die Zahlung wird nicht erstellt: die Bestellnotiz und das Protokoll zeigen den Paytrail-Fehler, zum Beispiel Paytrail API error (401): … bei falschen Zugangsdaten. Aktivieren Sie Debug log und sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_paytrail_gateway nach.

Die Merchant ID wird nicht gespeichert: sie darf nur Ziffern enthalten. Kopieren Sie sie erneut aus dem Paytrail-Händlerportal.

Die Bestellung steht auf On hold: lesen Sie die Bestellnotiz. Ursache ist eine ausstehende oder verzögerte Zahlung, ein abweichender Zahlungsbetrag, eine Zahlung nach einer Stornierung oder eine Testzahlung im Live-Modus.

Erstattung schlägt fehl: lesen Sie die Meldung. This order has no confirmed Paytrail payment. Refund it manually. bedeutet, dass keine bestätigte Paytrail-Zahlung zur Erstattung vorliegt. Eine Meldung über fehlende Live-Zugangsdaten bedeutet, dass die Zahlung im Live-Modus getätigt wurde und die Live-Zugangsdaten nicht hinterlegt sind. Unterstützt die Zahlungsmethode nur E-Mail-Erstattungen, benötigt die Bestellung eine Rechnungs-E-Mail-Adresse.

Entwickler-Hooks: der Filter ptg_payment_request ändert die Zahlungsanforderung, bevor sie signiert und gesendet wird; der Filter ptg_icon ändert das Kassen-Symbol.

Der Lizenzblock zeigt einen Fehler an: folgen Sie den Hinweisen im Block. Wird der Schlüssel beispielsweise bereits auf einer anderen Domain verwendet, geben Sie einen Platz in Ihrem vibefox.net-Konto frei und klicken Sie auf Check now. Hat sich die Website-Adresse 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. Um es zu entfernen, deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden dabei immer entfernt. Die Gateway-Einstellungen, das Protokoll dieses Plugins und die bei Bestellungen gespeicherten Paytrail-Daten (Zahlungsversuche, Transaktionsdaten, Erfassungsdatensätze von Erstattungen) werden nur gelöscht, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs; ohne die Paytrail-Daten können alte Bestellungen jedoch nicht mehr aus WooCommerce heraus erstattet werden.

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