VibeFox Tpay 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. Für die JWS-Signaturprüfung der Benachrichtigungen werden die OpenSSL-Erweiterung und ausgehende HTTPS-Verbindungen zu secure.tpay.com benötigt.

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 Warenkorb eine andere Währung verwendet.

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

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

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. Klicken Sie nach Abschluss des Uploads auf Configure oder suchen Sie VibeFox Tpay Payment 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. Geben Sie die Sandbox-Schlüssel und die Produktionsschlüssel ein (siehe Konfiguration). Im Tpay-Portal muss außer dem Sicherheitscode nichts eingestellt werden: Die Benachrichtigungsadresse wird bei jeder Transaktion übermittelt.

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Sandbox-Modus und deaktivieren Sie dann Sandbox mode, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul den Bestellstatus Tpay payment on hold an. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken; PLN muss für das Modul erlaubt bleiben.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Tpay Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged., solange der Sandbox-Modus aktiv ist. Sie wird außerdem gewarnt, wenn die Schlüssel des aktuellen Modus unvollständig sind (Tpay wird dann an der Kasse nicht angezeigt), wenn die Standardwährung des Shops 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). Leerzeichen, die bei der Merchant ID oder der Client ID eingefügt wurden, werden beim Speichern entfernt.

Tpay

Enable/Disable: Enable Tpay payments aktiviert oder deaktiviert die Zahlungsmethode. Standard: aus.

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

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: verwendet die Tpay-Sandbox (Testzahlungen, kein echtes Geld) mit den Sandbox-Schlüsseln und openapi.sandbox.tpay.com. Deaktivieren Sie die Option, um echte Zahlungen mit den Produktionsschlüsseln anzunehmen. Erstattungen gehen immer an die Umgebung, in der die Bestellung bezahlt wurde. Standard: an.

Production keys

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

Merchant ID: Ihre Tpay-Konto-ID (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 keys

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.

Gespeicherte Geheimnisse (Client secret und Security code beider Umgebungen) werden 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.

Clear saved secrets: Aktivieren Sie das Kästchen eines Geheimnisses und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

Payment notifications

Notification URL: Tpay bestätigt Zahlungen an die hier angezeigte Adresse. Mit freundlichen URLs sieht sie etwa so aus: https://your-shop/module/wcp_tpay_payment/notify, gegebenenfalls mit einem Sprachkürzel wie /en/. Die Adresse wird bei jeder Transaktion automatisch übermittelt; im Tpay-Portal muss außer dem Sicherheitscode nichts eingestellt werden. Eine Bestellung wird erst nach einer Benachrichtigung mit gültiger Prüfsumme und Signatur und passendem Betrag angelegt (oder nach einer passenden Statusprüfung, wenn der Kunde zurückkehrt). Tpay wiederholt eine Benachrichtigung, bis Ihr Shop sie annimmt.

JWS signature: prüft zusätzlich die X-JWS-Signature der Benachrichtigungen mit dem Tpay-Zertifikat (empfohlen). Erfordert die OpenSSL-Erweiterung von PHP und ausgehende HTTPS-Verbindungen zu secure.tpay.com. Die Zertifikate werden einen Tag lang zwischengespeichert. Die MD5-Prüfsumme wird immer geprüft. Standard: an.

Advanced

Debug log: protokolliert Zahlungsereignisse: nur technische Ereignisse (keine Schlüssel, keine Kundendaten) in logs/wc_tp_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Standard: aus. Solange die Option deaktiviert ist, wird nichts protokolliert, auch keine Fehler. Aktivieren Sie sie daher, bevor Sie nach der Ursache eines Problems suchen.

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 aktiviert, entfernt das Deinstallieren des Moduls die Modul-Einstellungen und das Protokoll. Bestellungen und ihre Tpay-Zahlungsdaten bleiben immer erhalten. Standard: aus.

Bestellvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Tpay). Im Sandbox-Modus zeigt die Zahlungsoption Sandbox mode - no real money is charged. Nach der Bestätigung legt das Modul eine Tpay-Transaktion für die Warenkorbsumme in PLN an, mit der Beschreibung Cart # und der Warenkorbnummer, übergibt Name, E-Mail-Adresse, Rechnungsadresse und Telefonnummer des Kunden und leitet den Kunden zur Tpay-Zahlungsseite weiter. Die Seite wird je nach Shop-Sprache 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. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Die Bestellung wird erst als bezahlt markiert, nachdem Tpay die Zahlung bestätigt hat. Tpay sendet eine Benachrichtigung an Ihren Shop; das Modul prüft die MD5-Prüfsumme mit dem Sicherheitscode, die Merchant ID und (sofern aktiviert) die JWS-Signatur, und zwar mit den Schlüsseln der Umgebung, in der die Zahlung gestartet wurde. Danach wird der Betrag geprüft: Er muss dem für diesen Zahlungsversuch angeforderten Betrag und der Warenkorbsumme entsprechen, und der bezahlte Betrag darf nicht niedriger sein. Benachrichtigungen ohne gültige Prüfsumme oder Signatur werden abgelehnt. Anschließend wird die Bestellung angelegt, und der Kunde erhält die übliche Bestellbestätigungsseite.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Rückkehr allein markiert nichts als bezahlt. Ist die Benachrichtigung noch nicht eingetroffen, fragt das Modul bei der Tpay-API den Status der Transaktion ab (höchstens alle 10 Sekunden) und wendet dieselben Prüfungen an. Solange die Zahlung nicht bestätigt ist, zeigt eine Seite Payment confirmation den Hinweis 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 einer Schaltfläche Refresh und einer Schaltfläche Pay again, die zurück zum Bestellvorgang führt. Die Benachrichtigung legt die Bestellung an, sobald sie eintrifft.

Meldet Tpay, dass die Zahlung fehlgeschlagen ist, kehrt der Kunde zum Bestellvorgang zurück, mit dem Hinweis Tpay reports that the payment did not go through. Please try again or choose another payment method. Schlägt die Zahlung auf der Tpay-Seite fehl, leitet Tpay den Kunden zurück zum Bestellvorgang. Der Warenkorb bleibt in beiden Fällen erhalten. Wurde die Bestellung angehalten, zeigt die Bestätigungsseite Your payment is being verified. We will contact you as soon as it is confirmed.

Jeder Zahlungsversuch hat eine eigene Referenz. Wenn der Kunde erneut bezahlt, werden die früheren unbezahlten Tpay-Transaktionen des Warenkorbs bei Tpay storniert; eine Zahlung, die bereits über einen früheren Link eingegangen ist, wird weiterhin akzeptiert. Hat der Warenkorb bereits eine Bestellung, gelangt der Kunde zu deren Bestätigungsseite statt zu einer neuen Zahlung.

Kann Tpay die Zahlung nicht starten, bleibt der Kunde im Bestellvorgang mit dem Hinweis The Tpay payment could not be started. Please try again or choose another payment method., und der Grund wird im Protokoll festgehalten (wenn Debug log aktiviert ist).

Die Benachrichtigungsadresse funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul 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

No order yet: Der Kunde wurde zu Tpay weitergeleitet und hat nicht bezahlt, oder Tpay hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb. Eine fehlgeschlagene Zahlung erzeugt ebenfalls keine Bestellung.

Payment accepted: Tpay hat die Zahlung bestätigt. Die Zahlung wird mit dem Tpay-Transaktionstitel (TR-...) als Transaktions-ID erfasst. Eine Notiz gibt an, ob sie durch die Benachrichtigung oder durch die Statusprüfung bestätigt wurde, außerdem die Umgebung und eine etwaige Überzahlung.

Tpay payment on hold: Eine Zahlung ist eingegangen, aber ihr Betrag wich vom angeforderten Betrag oder von der Warenkorbsumme ab (etwa weil der Warenkorb nach Beginn der Zahlung geändert wurde), es wurde nur ein Teil bezahlt, oder die Zahlung kam erst, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Zahlung im Tpay-Portal und liefern Sie die Bestellung aus oder erstatten Sie die Zahlung. Bezahlt der Kunde danach über einen neuen Versuch den richtigen Betrag, wechselt die Bestellung zu Payment accepted.

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

Meldet Tpay eine weitere Zahlung für eine Bestellung, die bereits bezahlt oder erstattet ist, bleibt die Bestellung unverändert; eine Notiz weist Sie darauf hin, die zusätzliche Zahlung bei Bedarf im Tpay-Portal zu erstatten. Ein von Tpay gemeldeter Chargeback fügt eine Notiz hinzu.

Tpay-Zahlungsblock

Die Bestellseite zeigt einen Block Tpay payment mit Titel und ID der Tpay-Transaktion, der Zahlungsreferenz (CRC), der Umgebung (mit der Markierung Sandbox bei Sandbox-Zahlungen), dem Zahlungsstatus und der Art der Bestätigung, dem bezahlten Betrag, der Bestellsumme und dem erstatteten Betrag, dem Erstattungsverlauf, allen Payment attempts des Warenkorbs und den Payment notes der Bestellung.

Erstattungen

Geben Sie im Block Tpay payment den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Tpay. Bestätigen Sie die Abfrage Refund this amount through Tpay? This cannot be undone. Vollständige und teilweise Erstattungen werden für Bestellungen mit einer über Tpay eingegangenen Zahlung unterstützt, auch für angehaltene Bestellungen. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modules-Seiten ist nicht erforderlich. Sie können bis zu dem Betrag erstatten, den die bezahlende Tpay-Transaktion eingezogen hat, höchstens jedoch die Bestellsumme: Nach einer Teilzahlung oder einem geänderten Warenkorb zeigt der Block Refundable (paid through Tpay). 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 erledigt, wenn Tpay sie bestätigt; eine von Tpay abgelehnte oder nicht bestätigte Erstattung wird als Fehler angezeigt und nicht erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen hinzugefügt, zusammen mit dem von Ihnen eingegebenen Grund (der Grund wird nicht an Tpay übermittelt). Die Erstattung des gesamten erstattungsfähigen Betrags 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 Tpay zurück. Erstattungen, die im Tpay-Händlerportal vorgenommen werden, werden nicht automatisch in PrestaShop übernommen.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Tpay Payment ist der erste Block auf Modules > Module Manager > VibeFox Tpay Payment > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, 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 zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-tpay 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, zeigt der Block den Grund an, 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 gilt für eine Domain: die Domain des Hauptshops, 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 Tpay 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 weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber es nicht im Bestellvorgang testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren weiter.

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 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

Tpay erscheint nicht im Bestellvorgang: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable aktiviert ist und alle vier Schlüssel des aktuellen Modus eingetragen sind (Merchant ID, Client ID, Client secret, Security code). Prüfen Sie, ob die Warenkorbwährung PLN ist und ob das Modul für PLN, das Land des Kunden und die Kundengruppe unter Payment > Preferences erlaubt ist. Die Einstellungsseite zeigt eine Warnung bei fehlenden Schlüsseln und bei einer Shop-Währung, die nicht PLN ist.

Die Zahlung wurde durchgeführt, aber es wurde keine Bestellung angelegt: Tpay konnte die Benachrichtigung nicht zustellen oder sie wurde abgelehnt. Aktivieren Sie Debug log und sehen Sie im Feld Log auf der Modulseite nach. Typische Ursachen sind ein falscher Sicherheitscode oder eine falsche Merchant ID für die Umgebung der Zahlung, eine blockierte Benachrichtigungsadresse (Firewall, HTTP-Authentifizierung) oder ein Server ohne OpenSSL oder ohne ausgehende HTTPS-Verbindung für die JWS-Prüfung. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop 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.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: Der Warenkorb wurde im selben Moment von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (etwa weil das Modul deaktiviert ist). Tpay wiederholt die Benachrichtigung automatisch. Aktivieren Sie Debug log, um den Grund zu sehen.

Die Benachrichtigungs-URL zeigt FALSE - POST only in the browser: Das ist normal. Die URL akzeptiert nur Benachrichtigungen von Tpay.

Die Bestellung ist Tpay payment on hold: Lesen Sie die Notizen im Block Tpay payment (siehe Bestellstatus), prüfen Sie die Zahlung im Tpay-Portal und liefern Sie dann die Bestellung aus oder erstatten Sie die Zahlung.

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

Der Kunde sah We could not match this payment to an order: Der Rücksprunglink gehörte nicht zum Warenkorb des Kunden. Wurde der Kunde belastet, legt die Benachrichtigung die Bestellung trotzdem an; prüfen Sie das Tpay-Portal.

Erstattung schlägt fehl: Wenn die Meldung besagt, dass Schlüssel fehlen, geben Sie die Schlüssel der Umgebung ein, in der die Bestellung bezahlt wurde. Wenn die Meldung besagt, dass der Betrag zu hoch ist, kann höchstens der angezeigte Betrag erstattet werden. Hat Tpay die Erstattung nicht bestätigt, prüfen Sie die Transaktion im Tpay-Händlerportal, bevor Sie es erneut versuchen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Tpay Payment und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Die zwischengespeicherten Tpay-Zugriffstoken und Zertifikate werden immer entfernt. Ist Delete data on uninstall aktiviert, werden auch die Modul-Einstellungen und das Protokoll entfernt. Ist die Option deaktiviert, bleiben die Einstellungen für eine spätere Neuinstallation erhalten. Die Tpay-Transaktionen und -Erstattungen sowie der Bestellstatus Tpay 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.

Tpay ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Tpay verbunden und wird nicht von Tpay unterstützt.