VibeFox Paytrail for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder höher. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Währung: EUR. Paytrail akzeptiert nur Euro. Bei einem Warenkorb in einer anderen Währung wird die Zahlungsmethode an der Kasse ausgeblendet. Beträge werden in Cent übermittelt.

Internetzugang zu Ihrem Shop: Paytrail bestätigt jede Zahlung per Server-zu-Server-Callback, daher sollte der Shop aus dem Internet erreichbar sein. Ohne Callbacks werden Bestellungen trotzdem angelegt, wenn der Kunde von Paytrail zurückkehrt.

Paytrail-Konto: Sie benötigen Ihre Merchant ID und Ihren Secret Key, die im Paytrail-Händlerportal angezeigt werden (Konto- bzw. Integrationsdaten). Zum Testen wird kein Konto benötigt: Der Testmodus verwendet das öffentliche Testkonto von Paytrail. Die Zahlungsmethoden selbst werden in Ihrem Paytrail-Konto aktiviert.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. 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 Paytrail 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. Um das Modul zuerst auszuprobieren, aktivieren Sie Test mode. Für echte Zahlungen deaktivieren Sie es und tragen Ihre Merchant ID und Ihren Secret key ein. In Paytrail muss keine Callback-URL konfiguriert werden.

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save.

Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting Paytrail payment und Paytrail payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können es unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite bei aktivem Testmodus Test mode is active. Payments use the public Paytrail test account — no real money is charged. an. Im Echtbetrieb warnt sie, wenn Merchant ID oder Secret key fehlen oder wenn die Merchant ID das öffentliche Testkonto 375917 ist. Sie warnt auch, wenn die Shop-Währung nicht EUR ist. In all diesen Fällen wird Paytrail nicht an der Kasse angezeigt.

Beim Speichern wird eine Merchant ID, die andere Zeichen als Ziffern enthält, nicht gespeichert, und es erscheint der Fehler Paytrail merchant ID must contain digits only. The previous value was kept.. Der Title darf nicht leer sein.

Paytrail

Enable/Disable: Enable Paytrail aktiviert oder deaktiviert die Zahlungsmethode. Standard: off.

Title: der Titel, der Kunden an der Kasse angezeigt wird. Er ist zugleich der Name der Zahlungsmethode, der in der Bestellung gespeichert wird. Standard: Paytrail. Pflichtfeld.

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

API-Zugangsdaten

Ihre Merchant ID und Ihr Secret Key werden im Paytrail-Händlerportal angezeigt (Konto- bzw. Integrationsdaten). Der Abschnitt verlinkt auf das Händlerportal. Es werden nur Zahlungen in EUR unterstützt.

Test mode: verwendet für neue Zahlungen das öffentliche Testkonto von Paytrail (Merchant ID 375917) statt Ihrer eigenen Zugangsdaten. Es wird kein echtes Geld abgebucht, und es werden keine Schlüssel benötigt. Kunden sehen Test mode: no real payment will be made. unter der Zahlungsmethode. Der Secret Key des Testkontos ist öffentlich, daher könnte jeder eine im Testmodus ausgeführte Zahlung simulieren. Lassen Sie den Testmodus in einem Live-Shop niemals aktiviert. Standard: off.

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

Secret key: Ihr Paytrail-Secret-Key. Wird verwendet, wenn der Testmodus deaktiviert ist. Der gespeicherte Schlüssel wird 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.

Gespeicherten Secret key löschen: Setzen Sie den Haken bei Secret key und klicken Sie auf Save, um den gespeicherten Schlüssel zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Callbacks und Erstattungen verwenden immer die Zugangsdaten des Modus, in dem die Zahlung erfolgt ist. Ein Wechsel zwischen Test- und Echtbetrieb bricht daher keine älteren Bestellungen.

Bestellungen

Callback URL: zeigt die URL, unter der Paytrail jede Zahlung server-zu-server bestätigt. Mit schönen URLs sieht sie so aus: https://your-shop/module/wcp_paytrail_gateway/callback. Sie wird mit jeder Zahlung übermittelt, daher muss im Paytrail-Panel nichts eingerichtet werden, aber der Shop muss aus dem Internet erreichbar sein.

Order status after payment: der Status einer bezahlten Bestellung.

Ausstehende Zahlungen warten in Awaiting Paytrail payment. Betragsabweichungen und andere Probleme gehen immer in Paytrail payment on hold.

Erweitert

Debug log: protokolliert API-Anfragen und Callbacks in logs/ptg_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Personenbezogene Daten und Schlüssel werden nicht protokolliert. Fehler und Warnungen werden immer protokolliert. 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 Einstellungen und das Protokoll. Das Deaktivieren des Moduls löscht nie etwas. Die Paytrail-Transaktionsdaten der Bestellungen bleiben immer erhalten, da Erstattungen älterer Bestellungen sie benötigen. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Paytrail) und bestätigt. Das Modul legt für die Warenkorbsumme in Euro eine Paytrail-Zahlung an und übermittelt dazu die Bestellzeilen: Produkte nach Warenkorbregeln, Versand und Geschenkverpackung, jeweils mit ihrem MwSt.-Satz auf eine Nachkommastelle. Die Zeilen ergeben immer den Zahlungsbetrag; eine Rundungsdifferenz wird einer Zeile zugeschlagen oder als Zeile Rounding übermittelt. Rechnungs- und Lieferadressen werden nur übermittelt, wenn sie vollständig sind, und lange Werte werden auf die Grenzen von Paytrail gekürzt. Die Sprache der Zahlungsseite ist Finnisch, Schwedisch oder Englisch, je nach Sprache des Warenkorbs. Zu diesem Zeitpunkt existiert noch keine Bestellung.

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 zweimal: Es leitet den Kunden zurück in Ihren Shop und ruft die Callback-URL server-zu-server auf. Beides wird nur mit einer gültigen Signatur akzeptiert, die mit den Zugangsdaten dieses Zahlungsversuchs erstellt wurde, und nur für einen Versuch, der für diesen Warenkorb angelegt wurde. Der bezahlte Betrag wird mit der Warenkorbsumme verglichen. Die Bestellung gilt erst als bezahlt, wenn Paytrail die Zahlung auf diesem Weg bestätigt. Das Modul verarbeitet folgende Paytrail-Status:

Nach einer erfolgreichen Zahlung sieht der Kunde die übliche Bestellbestätigungsseite mit Your Paytrail payment has been received. Bei einer ausstehenden Zahlung zeigt die Seite Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Verbucht der Callback die Zahlung genau in diesem Moment, bittet eine Seite Payment confirmation den Kunden, nicht erneut zu bezahlen, und bietet eine Schaltfläche Check again an.

Nach einer abgebrochenen oder fehlgeschlagenen Zahlung kehrt der Kunde zur Kasse zurück, mit The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Ist die Zahlung noch nicht abgeschlossen, lautet die Meldung The Paytrail payment has not been completed yet. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Eine Rückkehr, die nicht überprüft werden kann, zeigt Payment verification failed. und verändert nichts.

Kann Paytrail die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen 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. Der technische Grund wird im Protokoll festgehalten. Eine Gesamtsumme außerhalb der Grenzen von Paytrail führt zu This order total cannot be paid with Paytrail. Please choose another payment method.

Eine Paytrail-Zahlung kann nicht über die API storniert werden. Jeder neue Versuch für den Warenkorb ist eine neue Paytrail-Zahlung. Bezahlt der Kunde zusätzlich eine ältere, noch offene Zahlungsseite, wird die zweite Zahlung an der Bestellung als Duplikat zur Erstattung gemeldet.

Der Callback funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Der Kunde wählt die Zahlungsmethode auf der Paytrail-Seite, nicht an Ihrer Kasse. Das Modul bietet keine Kartentokenisierung oder gespeicherten Karten, keine Abonnements, kein Shop-in-Shop, keine manuelle Rechnungsaktivierung und keine Abrechnungsberichte.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: der Kunde wurde zu Paytrail geschickt und hat noch nicht bezahlt, oder Paytrail hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted or Delivered: die Zahlung wurde bestätigt. Der Status folgt Order status after payment. Die Zahlung wird mit der Paytrail-Transaktions-ID erfasst, und eine Notiz zeigt die Transaktion, die bei Paytrail verwendete Zahlungsmethode und den Betrag.

Awaiting Paytrail payment: die Zahlung steht beim Anbieter aus (Rechnung oder verzögerte Zahlung). Die Bestellung wechselt in den bezahlten Status, wenn Paytrail die Zahlung bestätigt, oder in Payment error, wenn sie fehlschlägt.

Paytrail payment on hold: der bezahlte Betrag weicht von der Bestellsumme ab (der tatsächlich bezahlte Betrag wird erfasst), die Zahlung ist eingegangen, nachdem die Bestellung storniert wurde, oder eine Testzahlung wurde empfangen, während der Shop live ist (kein echtes Geld, nichts wird erfasst). Die Notiz erklärt den Grund. Prüfen Sie die Bestellung und bearbeiten Sie sie dann weiter oder erstatten Sie die Zahlung.

Payment error: eine ausstehende Zahlung ist fehlgeschlagen oder wurde abgebrochen.

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

Wiederholte oder parallele Callbacks erzeugen nie eine zweite Bestellung und keine doppelten Notizen. Wird ein zweiter Versuch eines bereits bezahlten Warenkorbs bezahlt, bleibt die Bestellung unverändert; eine Notiz Duplicate payment bittet Sie, die Zahlung im Paytrail-Händlerportal zu erstatten.

Paytrail-Zahlungsblock

Die Bestellseite zeigt einen Block Paytrail payment mit Transaktions-ID, Modus (ein Abzeichen TEST mode bei Testzahlungen), Zahlungsmethode, Paytrail-Status, bezahltem und erstattetem Betrag, dem Erstattungsformular, dem Erstattungsverlauf, den Zahlungsversuchen des Warenkorbs und den Paytrail notes der Bestellung.

Erstattungen

Geben Sie im Block Paytrail payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund für die Bestellnotiz, und klicken Sie auf Refund via Paytrail. Bestätigen Sie die Rückfrage Refund this amount through Paytrail? This cannot be undone. Volle und Teilerstattungen werden unterstützt, nur nach Betrag. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Sie können bis zu dem Betrag erstatten, den Paytrail tatsächlich eingezogen hat. Nach einer Betragsabweichung ist die Grenze daher der vom Kunden bezahlte Betrag, nicht die Bestellsumme. Die Erstattung verwendet die Zugangsdaten des Modus, in dem die Zahlung erfolgte; bei einer Echtzahlung müssen also die Echtzugangsdaten hinterlegt sein. Erstattungen sind verfügbar, sobald Paytrail die Zahlung bestätigt hat.

Unterstützt die Zahlungsmethode keine direkten Erstattungen, startet das Modul automatisch eine Erstattung per E-Mail: Paytrail schickt dem Kunden eine E-Mail, um eine Bankverbindung einzugeben. Dafür wird die E-Mail-Adresse des Kunden in der Bestellung benötigt. Die Notiz zeigt an, welche Art der Erstattung gestartet wurde.

Eine Erstattung kann sofort abgeschlossen oder später bearbeitet 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 dem Kunden nicht zurückgegeben wurde; die Erstattung zählt dann nicht mehr als erstattet, und Sie müssen den Kunden auf anderem Weg erstatten. Lehnt Paytrail die Erstattung sofort ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine volle 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 Paytrail zurück. Im Paytrail-Händlerportal vorgenommene Erstattungen werden nicht zurück in PrestaShop synchronisiert.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Paytrail Gateway ist der erste Block auf Modules > Module Manager > VibeFox Paytrail Gateway > Configure, oberhalb der Einstellungen. Geben 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-paytrail 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. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domain-Platz 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 in einer Multistore-Konfiguration. 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 Paytrail Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher ist die Zahlungsmethode 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 der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin durch die Callbacks und die Rückkehr des Kunden bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach 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

Paytrail erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und entweder Test mode aktiv ist oder Merchant ID und Secret key ausgefüllt sind (nicht das öffentliche Testkonto 375917). Prüfen Sie, ob die Warenkorbwährung EUR ist. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung bei fehlenden Zugangsdaten und bei falscher Shop-Währung.

Die Zahlung wurde durchgeführt, aber es wurde keine Bestellung angelegt: der Callback kann Ihren Shop nicht erreichen, und der Kunde ist nicht in den Shop zurückgekehrt. Die Callback URL im Abschnitt Bestellungen muss aus dem Internet erreichbar sein (keine Basisauthentifizierung oder Firewall im Weg).

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

Callback meldet Temporarily unavailable: die Bestellung wurde im selben Moment von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Paytrail ruft erneut auf. Sehen Sie im Feld Log nach dem Grund.

Der Kunde sieht beim Wählen von Paytrail einen Fehler: sehen Sie im Feld Log auf der Modulseite nach. Paytrail API error (401) bedeutet zum Beispiel falsche Zugangsdaten. Aktivieren Sie Debug log für mehr Details.

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

Bestellung ist Paytrail payment on hold: lesen Sie die Notizen im Block Paytrail payment. Der Grund ist ein abweichender bezahlter Betrag, eine Zahlung nach der Stornierung oder eine Testzahlung im Echtbetrieb.

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 zum Erstatten vorliegt. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. bedeutet, dass die Zahlung im Echtbetrieb erfolgte und die Echtzugangsdaten nicht hinterlegt sind. Invalid refund amount: at most … bedeutet, dass der Betrag größer ist als der noch erstattbare Rest. Unterstützt die Zahlungsmethode nur Erstattungen per E-Mail, benötigt die Bestellung die E-Mail-Adresse des Kunden.

Entwickler-Hook: der Hook actionWcpPaytrailPaymentRequest ändert die Zahlungsanfrage, bevor sie signiert und gesendet wird.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Paytrail 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 Einstellungen und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Paytrail-Transaktionen und Erstattungen sowie die Bestellstatus Awaiting Paytrail payment und Paytrail payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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