VibeFox TrustPay for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.
finby-Konto (TrustPay): Sie brauchen ein Projekt im finby Merchant Portal mit seiner Project ID und seinem Secret Key. Für Testzahlungen brauchen Sie ein separates Testprojekt (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 Ihren Shop aus dem Internet erreichen können. Eine Firewall, ein Wartungslogin oder eine HTTP-Authentifizierung vor dem Shop blockiert die Zahlungsbenachrichtigungen.
VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel gilt 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.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure. Später finden Sie VibeFox TrustPay Gateway in der Modulliste und klicken dort auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Geben Sie Project ID und Secret Key Ihres Testprojekts und, für echte Zahlungen, Ihres Live-Projekts ein (siehe Konfiguration).
5. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Führen Sie eine Testzahlung mit eingeschaltetem Test mode durch und schalten Sie danach Test mode aus, um echte Zahlungen anzunehmen.
Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting TrustPay payment und TrustPay payment on hold. PrestaShop verknüpft ein neues Zahlungsmodul mit den Ländern, die bei der Installation aktiv sind. Für Länder, die Sie später hinzufügen, setzen Sie bei dem Modul unter Payment > Preferences ein Häkchen. Dort können Sie das Modul außerdem nach Währung und Kundengruppe einschränken.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn das Modul aktiviert ist, aber Project ID oder Secret Key des aktuellen Modus leer sind, und wenn die Standardwährung des Shops nicht unterstützt wird. In beiden Fällen wird die Zahlungsart im Bestellvorgang ausgeblendet.
TrustPay / finby
Enable / Disable: Enable TrustPay / finby card payments schaltet die Zahlungsart ein oder aus. Standard: off.
Title: der Name der Zahlungsart, den Kunden im Bestellvorgang sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Card payment (TrustPay). Pflichtfeld.
Description: der Text unter der Zahlungsart im Bestellvorgang. 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 Testprojekt (Playground) mit eigener Project ID und eigenem Secret Key. Dort wird kein echtes Geld abgebucht.
Test mode: nutzt das Testprojekt (keine echten Zahlungen). Neue Zahlungen und Erstattungen verwenden die Testzugangsdaten. Erstattungen einer Bestellung gehen immer an das Projekt, über das die Bestellung bezahlt wurde. Standard: on. Solange er eingeschaltet ist, sehen Kunden unter der Zahlungsart Test mode: no real payment will be taken.
Live Project ID: die numerische Project ID Ihres Live-Projekts.
Live Secret key: der Secret Key des Live-Projekts. Er dient dazu, API-Zugangstoken abzurufen und Zahlungsbenachrichtigungen zu prüfen.
Test Project ID: die numerische Project ID Ihres Testprojekts (Playground).
Test Secret key: der Secret Key des Testprojekts.
Eine Project ID darf nur Ziffern enthalten. Speichern Sie einen anderen Wert, zeigt die Seite must contain digits only — the previous value was kept. an, und die übrigen Felder werden gespeichert. Secret Keys werden genau so gespeichert, wie Sie sie eingeben; nur Leerzeichen am Anfang und am Ende werden entfernt. Gespeicherte Secret Keys werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten. Beim Speichern der Einstellungen werden außerdem die zwischengespeicherten API-Zugangstoken verworfen, sodass die neuen Zugangsdaten sofort verwendet werden.
Clear saved secrets: markieren Sie einen Secret Key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Zahlungsbenachrichtigungen
Eine Bestellung wird erst als bezahlt markiert, nachdem finby die Zahlung mit einer signierten Benachrichtigung bestätigt hat. Das Modul sendet die Benachrichtigungs-URL bei jeder Zahlung automatisch, Sie müssen sie also nicht einrichten. Der Abschnitt zeigt die URL unter Notification URL. Mit SEO-URLs sieht sie etwa so aus: https://your-shop/module/wcp_trustpay_gateway/callback, gegebenenfalls mit einem Sprachcode. Sie können sie auch als Benachrichtigungs-URL in den Projekten im Merchant Portal eintragen. Benachrichtigungen ohne gültige Signatur werden abgelehnt.
Das Modul fragt finby nicht selbst nach dem Zahlungsstatus. Kann eine Benachrichtigung Ihren Shop nicht erreichen, wird keine Bestellung angelegt, bis finby sie zustellt. finby wiederholt Benachrichtigungen.
Erweitert
Order status after payment: der Bestellstatus, der nach erfolgreicher Zahlung gesetzt wird. Der Status wird in einem Schritt gesetzt, damit der Kunde nur eine E-Mail erhält.
Debug logging: schreibt API-Anfragen und Benachrichtigungen in logs/trustpay_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über den Webbrowser öffnen. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Das Protokoll enthält keine Schlüssel, Token, Kartendaten oder Kundendaten. 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: wenn aktiv, entfernt die Deinstallation des Moduls die Modul-Einstellungen und das Protokoll. Bestelldaten bleiben erhalten: Bestellungen, TrustPay-Zahlungsdaten und Erstattungen sowie die Bestellstatus. Standard: off.
Bestellvorgang
Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Card payment (TrustPay)) und bestätigt die Bestellung. Die Zahlungsart wird nur in den unterstützten Währungen angeboten: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF und USD. HUF-Beträge werden ohne Nachkommastellen übertragen.
Kartenzahlungen benötigen eine Adresse. Fehlt die Straße, die Stadt, die Postleitzahl oder das Land, sieht der Kunde Please enter your billing address (street, city, postcode and country) — it is required for card payments.
Das Modul erstellt bei finby eine Kartenzahlungsanfrage für den Warenkorbbetrag in der Warenkorbwährung. Name, Adresse und E-Mail-Adresse des Kunden werden für 3-D Secure übermittelt, die Warenkorbnummer wird als Referenz gesendet. An diesem Punkt existiert noch keine Bestellung. Der Kunde wird zur Zahlungsseite von finby weitergeleitet und bezahlt dort mit Karte. Die Seite öffnet sich in der Sprache des Warenkorbs, sofern finby sie unterstützt, andernfalls auf Englisch.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, nachdem finby die Zahlung mit der signierten Benachrichtigung bestätigt hat. Die Rückkehr selbst ändert den Zahlungsstatus nie. Ist die Benachrichtigung bereits eingegangen, sieht der Kunde die übliche Bestellbestätigungsseite. Ist sie noch nicht da, erscheint eine Seite Payment confirmation, die mitteilt, dass finby die Kartenzahlung bestätigt und die Bestellung angelegt wird, sobald die Bestätigung eingeht. Sie enthält eine Schaltfläche Check again und eine Schaltfläche Back to checkout. Solange die Bestellung Awaiting TrustPay payment oder TrustPay payment on hold ist, zeigt die Bestätigungsseite Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Hat finby die Zahlung abgelehnt oder wurde die unbezahlte Bestellung storniert, zeigt sie Your card payment was not completed. Please contact us about this order.
Bricht der Kunde auf der Zahlungsseite ab, kehrt er zum Bestellvorgang zurück, wo The card payment was cancelled. You can try again or choose another payment method. steht. Gibt die Zahlungsseite einen Fehler zurück oder hat finby die Zahlung bereits abgelehnt, lautet die Meldung The card payment was not completed. Please try again or choose another payment method. Der Warenkorb bleibt erhalten, und der Kunde kann erneut bezahlen.
Kann finby die Zahlung nicht starten, bleibt der Kunde im Bestellvorgang mit 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.
Die Benachrichtigung funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.
Das Modul nimmt nur Kartenzahlungen an, als Einmalkauf auf der finby-Seite. Es bietet keine Banküberweisungen oder anderen finby-Zahlungsarten, keine Apple-Pay- oder Google-Pay-Buttons auf Ihrer Website, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine getrennte Autorisierung und Erfassung sowie keine Statusabfrage.
Bestellungen und Erstattungen
Bestellstatus
No order yet: der Kunde wurde zu finby weitergeleitet und hat nicht bezahlt, oder die Benachrichtigung ist noch nicht eingegangen. Es existiert nur der Warenkorb.
Payment accepted or Delivered: finby hat die Zahlung bestätigt, und Betrag und Währung stimmen mit der Zahlungsanfrage und dem Warenkorbbetrag überein. Der Status folgt Order status after payment. Die Zahlung wird mit der ID der finby-Zahlungsanfrage als Transaktions-ID erfasst, und eine Notiz nennt Betrag, Zahlungsanfrage und Projekt (Test oder Live).
Awaiting TrustPay payment: finby hat die letzte Zahlung als ausstehend gemeldet. Die Bestellung wechselt in den bezahlten Status, sobald finby die Zahlung bestätigt.
TrustPay payment on hold: wird in zwei Fällen gesetzt. Die Zahlung wurde nur autorisiert, nicht erfasst: Erfassen oder stornieren Sie sie im finby Merchant Portal und aktualisieren Sie danach die Bestellung. Oder der bezahlte Betrag oder die Währung weicht von der Zahlungsanfrage oder dem Warenkorbbetrag ab, etwa weil der Warenkorb geändert wurde, nachdem der Kunde zur Zahlungsseite geleitet wurde: Prüfen Sie die Zahlung vor dem Versand. Die Notiz erklärt den Fall.
Payment error: finby hat die letzte Zahlung einer wartenden Bestellung abgelehnt. Die Notiz nennt den Grund, sobald finby ihn übermittelt. Eine später bestätigte Zahlung setzt die Bestellung trotzdem in den bezahlten Status.
Refunded: die Zahlung wurde über das Modul vollständig erstattet.
Stornierte oder erstattete Bestellungen werden durch eine verspätete Zahlung nie wieder geöffnet. Eine Notiz fordert Sie auf, die Bestellung wiederherzustellen oder die Zahlung im Merchant Portal zu erstatten. Trifft eine zweite Zahlung zu einer bereits bezahlten Bestellung ein, bleibt die Bestellung unverändert, und eine Notiz fordert Sie auf, die doppelte Zahlung im Merchant Portal zu erstatten. Von finby gemeldete Rückbuchungen und Streitfälle werden als Notizen hinzugefügt.
TrustPay- / finby-Zahlungsblock
Die Bestellseite zeigt einen Block TrustPay / finby payment mit der ID der Zahlungsanfrage, der finby-Zahlungs-ID, dem Projekt, dem Zahlungsstatus, den angefragten und bezahlten Beträgen, dem erstatteten Betrag, dem Hinweis Test project bei Testzahlungen, dem Erstattungsverlauf und den TrustPay notes der Bestellung.
Erstattungen
Geben Sie im Block TrustPay / finby payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via TrustPay. Bestätigen Sie die Frage Refund this amount through TrustPay? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Erstattungen erfolgen in dem Betrag und in der Währung, die finby für die Zahlung gemeldet hat. Nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht bis zum Bestellbetrag. HUF-Erstattungen müssen ganze Beträge sein.
Die Erstattung geht an das Projekt, über das die Bestellung bezahlt wurde (Test oder Live), auch wenn Sie seitdem den Modus gewechselt haben. Für dieses Projekt müssen Project ID und Secret Key eingetragen sein, und seine Project ID darf sich nicht geändert haben. Eine Erstattung wird nur erfasst, wenn finby sie annimmt. Andernfalls zeigt der Block TrustPay refused the refund: mit dem Grund, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über finby zurück. Im finby Merchant Portal vorgenommene Erstattungen werden nicht als Erstattungen erfasst. Sendet finby dazu eine Benachrichtigung, wird sie als Notiz hinzugefügt, und der Bestellstatus ändert sich nicht.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox TrustPay Gateway ist der erste Block auf Modules > Module Manager > VibeFox TrustPay Gateway > Configure, über den 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-trustpay 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 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 gilt für eine Domain: die Domain des Haupt-Shops, auch bei einer Multistore-Einrichtung. 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 die Kartenzahlung Kunden im Bestellvorgang nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront erkennt nicht, dass Sie im Back Office angemeldet sind, daher ist die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber den Bestellvorgang nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen bleiben unberührt: bereits begonnene Zahlungen werden weiterhin durch die TrustPay-Benachrichtigung und die Rückkehr in den Shop bestätigt, und Erstattungen funktionieren.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber 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 der 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
Card payment (TrustPay) erscheint nicht im Bestellvorgang: 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 Warenkorbwährung muss zu den unterstützten Währungen gehören. Die Einstellungsseite zeigt eine Warnung, wenn Zugangsdaten fehlen oder die Standardwährung nicht unterstützt wird. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.
Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: die Benachrichtigung hat Ihren Shop nicht erreicht. Prüfen Sie, ob die unter Notification URL angezeigte URL aus dem Internet erreichbar ist (keine Firewall, kein Wartungslogin und keine HTTP-Authentifizierung). finby wiederholt die Benachrichtigung, und die Bestellung wird angelegt, sobald sie eingeht. Aktivieren Sie Debug logging und sehen Sie sich das Feld Log auf der Modulseite an.
Das Protokoll zeigt Notification rejected: invalid signature or unknown project: die Benachrichtigung stammt 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 ändert nichts. Prüfen Sie Project ID und Secret Key des Modus, in dem die Zahlung erfolgt ist.
Das Protokoll zeigt Notification ignored: die Benachrichtigung gehört zu einer Zahlungsanfrage, die dieser Shop für diesen Warenkorb nicht erstellt hat, oder zu einem anderen Projekt oder Modus als dem, mit dem die Zahlung gestartet wurde. Es wird nichts geändert.
Die Benachrichtigung wird mit Busy, retry later oder Temporary error beantwortet: der Warenkorb wurde gerade durch eine andere Benachrichtigung aktualisiert, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). finby wiederholt sie. Das Protokoll zeigt den Grund.
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 einer Meldung, dass finby die Zugangsdaten des Projekts abgelehnt hat. Prüfen Sie, ob die Testzugangsdaten in den Testfeldern und die Live-Zugangsdaten in den Live-Feldern stehen.
Card payment is temporarily unavailable: der Kunde sieht dies, wenn der aktuelle Modus keine Project ID oder keinen Secret Key hat. Geben Sie beides ein und speichern Sie.
Bestellung ist TrustPay payment on hold: lesen Sie die Notizen im Block TrustPay / finby payment (siehe Bestellstatus). 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 gesetzt, oder dort ist inzwischen eine andere Project ID gespeichert. Geben Sie die Zugangsdaten dieses Projekts ein oder erstatten Sie die Zahlung im finby Merchant Portal.
Invalid refund amount: at most … can be refunded: der Betrag ist größer als der bezahlte Betrag abzüglich der bereits über das Modul erfolgten Erstattungen.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox TrustPay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Die zwischengespeicherten API-Zugangstoken werden immer entfernt. Ist Delete data on uninstall aktiv, werden die Modul-Einstellungen und das Protokoll entfernt. Ist es aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die TrustPay-Zahlungsdaten und Erstattungen sowie die Bestellstatus Awaiting TrustPay payment und TrustPay payment on hold bleiben immer erhalten, damit zuvor bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
TrustPay und finby sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist weder mit TrustPay noch mit finby verbunden und wird von ihnen nicht unterstützt.