VibeFox Tranzila for WooCommerce — Hilfe
Anforderungen
WordPress: 6.0 oder neuer.
WooCommerce: 8.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.
PHP: 8.0 oder neuer.
Shop-Währung: ILS, USD, EUR oder GBP. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.
Tranzila-Terminal: Sie benötigen den Terminalnamen. Das Terminal-Passwort (TranzilaPW) wird für den Handshake und für Erstattungen aus WooCommerce benötigt. Manche Terminals benötigen für Erstattungen zusätzlich ein separates Kreditpasswort (CreditPass). Terminalname und Passwörter stellt Tranzila bereit: Sie finden sie in Ihren Terminaleinstellungen oder erfragen sie beim Tranzila-Support. Tranzila bietet keine öffentliche Sandbox. Für Tests stellt Tranzila ein separates Testterminal bereit; tragen Sie dessen Namen als Terminalnamen ein.
Echte Besucher-IP: Zahlungsbenachrichtigungen werden anhand der IP-Adresse des Tranzila-Servers geprüft. Wenn Ihre Website hinter einem Proxy oder CDN wie Cloudflare liegt, muss der Webserver die echte Besucher-IP an PHP (REMOTE_ADDR) weitergeben.
VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 und klicken Sie auf Install Now. Alternativ können Sie den Ordner wcp_tranzila_payment_gateway per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Tranzila > 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. Tragen Sie den Terminal name (supplier) ein sowie das Terminal password (TranzilaPW), falls Sie den Handshake oder Erstattungen nutzen.
6. Lassen Sie Notifications eingeschaltet und prüfen Sie Trusted IP: Dort müssen die IP-Adressen stehen, von denen Tranzila Benachrichtigungen sendet. Bestätigen Sie die Liste mit dem Tranzila-Support.
7. Empfohlen: Aktivieren Sie den Handshake im Tranzila-Terminal, erlauben Sie dort die IP-Adresse Ihres Servers und schalten Sie danach im Plugin Handshake ein.
8. Schalten Sie Enable/Disable ein und testen Sie eine Zahlung mit dem Tranzila-Testterminal.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Tranzila. Oberhalb der Felder warnt die Seite, wenn der Terminalname leer ist (dann wird die Zahlungsart an der Kasse ausgeblendet), wenn Benachrichtigungen deaktiviert sind oder Trusted IP leer ist (bezahlte Bestellungen werden dann zur manuellen Prüfung auf Wartestellung gesetzt), wenn der Handshake ohne Terminal-Passwort aktiviert ist (die Zahlungsseite lässt sich dann nicht öffnen) und wenn die Shop-Währung nicht unterstützt wird. Beim Speichern wird ein ungültiger Terminalname oder ein ungültiger Eintrag in Trusted IP nicht gespeichert: Die Seite zeigt einen Fehler, und der vorherige Wert bleibt erhalten. Zahlen außerhalb des erlaubten Bereichs werden auf den nächsten erlaubten Wert korrigiert.
General
Enable/Disable: Enable Tranzila Payment Gateway schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Credit Card (Tranzila).
Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay securely with your credit card on the Tranzila payment page.
Terminal
Terminal name (supplier): Ihr Tranzila-Terminalname, zum Beispiel myshop. Nur Buchstaben, Ziffern, „-“ und „_“. Solange er nicht eingetragen ist, wird die Zahlungsart an der Kasse nicht angezeigt. Für Tests tragen Sie den Namen Ihres Tranzila-Testterminals ein.
Terminal password (TranzilaPW): das API-Passwort des Terminals. Es wird für den Handshake und für Erstattungen aus WooCommerce benötigt.
Refund password (CreditPass): nur, wenn Ihr Terminal für Gutschriftbuchungen (Erstattungen) ein separates Passwort verlangt. Ansonsten leer lassen.
Payment page
Payment page version: die Tranzila-Seite, die im iframe angezeigt wird.
Payment page language: die Sprache der Tranzila-Seite: Site language, Hebrew, English, Russian, Spanish, German, French oder Japanese. Standard: Hebrew. Site language verwendet die Sprache der WordPress-Locale des Besuchers, wenn es eine dieser Sprachen ist, andernfalls English.
iFrame width (px): 300 bis 1200. Standard: 600. Auf kleinen Bildschirmen ist der Rahmen nie breiter als die Seite.
iFrame height (px): 400 bis 1500. Standard: 650.
Max installments: die maximale Anzahl an Raten (tashlumim), die der Kunde auf der Zahlungsseite wählen darf, bis zu 36. 0 oder 1 bedeutet keine Raten. Standard: 0. Das Terminal muss für Ratenzahlungen freigeschaltet sein.
Handshake: Lock the amount with a handshake token (recommended). Vor dem Öffnen der Zahlungsseite fordert der Shop bei Tranzila ein Einmal-Token an, das an den Bestellbetrag gebunden ist, sodass der Betrag im Browser nicht verändert werden kann. Dafür sind das Terminal-Passwort, ein im Tranzila-Terminal aktivierter Handshake und die Freigabe der IP-Adresse Ihres Servers dort erforderlich. Standard: aus.
Payment confirmation
Tranzila-Benachrichtigungen sind nicht signiert. Eine Bestellung wird nur dann als bezahlt markiert, wenn die Benachrichtigung von einer Trusted IP stammt und ihr Bestellschlüssel, Terminal, Betrag und Währung zur Bestellung passen. Bei aktiviertem Handshake muss zusätzlich das Token zur Zahlungsseite der Bestellung passen. Die Rückkehr des Kunden von der Zahlungsseite markiert eine Bestellung nie als bezahlt.
Notifications: Confirm payments automatically with Tranzila notifications (notify URL). Standard: ein. Die Benachrichtigungs-URL wird bei jeder Zahlung an Tranzila übermittelt, Sie müssen sie daher nicht im Tranzila-Terminal eintragen. Sie sieht so aus: https://your-site/wc-api/tranzila_p_callback/ und wird unter dem Feld angezeigt. Wenn Benachrichtigungen aus sind, setzt ein Kunde, der nach einer erfolgreichen Zahlung zurückkehrt, die Bestellung auf Wartestellung, und Sie bestätigen die Zahlung manuell, nachdem Sie sie im Tranzila-Terminal geprüft haben.
Trusted IP: die IP-Adressen oder CIDR-Bereiche der Tranzila-Server, die Benachrichtigungen senden, durch Kommas getrennt. Standard: 80.244.170.7. Bestätigen Sie die aktuelle Liste mit dem Tranzila-Support. Benachrichtigungen von anderen Adressen werden abgelehnt. Ist das Feld leer, lassen sich Benachrichtigungen nicht prüfen: Eine gemeldete erfolgreiche Zahlung setzt die Bestellung zur manuellen Prüfung auf Wartestellung, und eine gemeldete Ablehnung ändert die Bestellung nicht.
Advanced
Debug log: Log payment page, notification and refund events schreibt in WooCommerce > Status > Logs, Quelle wcp_tranzila_payment_gateway. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Passwörter, Token und Kundendaten werden nie geschrieben. Standard: aus.
Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. Standard: aus.
Kasse
Der Kunde wählt die Zahlungsart (standardmäßig Credit Card (Tranzila)) und klickt auf Continue to payment. Die Bestellung wird mit dem Status Zahlung ausstehend angelegt, und der Kunde gelangt auf die Bestellzahlungsseite Ihres Shops. Dort öffnet sich die Tranzila-Zahlungsseite im iframe mit dem Bestellbetrag in der Bestellwährung, den Rechnungsdaten und einer kurzen Liste der bestellten Produkte. Die Seite zeigt Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". Unter dem Rahmen steht der Link Choose another payment method. Sind Raten erlaubt, wählt der Kunde ihre Anzahl auf der Tranzila-Seite.
Nach einer erfolgreichen Zahlung leitet Tranzila den Kunden zurück, und das ganze Fenster wechselt zur Seite „Bestellung eingegangen“ Ihres Shops. Die Bestellung wird erst als bezahlt markiert, wenn Tranzila dies mit einer Benachrichtigung bestätigt. Bis dahin zeigt die Seite Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Befindet sich die Bestellung zur Prüfung auf Wartestellung, erscheint Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.
Wird die Zahlung abgelehnt oder abgebrochen, kehrt der Kunde auf die Bestellzahlungsseite zurück, mit der Meldung The payment was not completed. You have not been charged — please try again or choose another payment method. Meldet Tranzila einen Antwortcode, werden Grund und Code ergänzt, zum Beispiel dass die Karte abgelaufen ist. Der Kunde kann erneut zahlen oder eine andere Zahlungsart wählen.
Lässt sich die Zahlungsseite nicht öffnen, etwa wenn der Handshake fehlschlägt, sieht der Kunde eine kurze Meldung wie Could not connect to Tranzila. Please try again in a moment. sowie den Link Choose another payment method. Der technische Grund wird ins Protokoll geschrieben.
Die Zahlungsart funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Auf der Seite Pay for order wird sie angeboten, wenn die Bestellwährung unterstützt wird. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.
Das Plugin nimmt nur einmalige Kartenzahlungen auf der Tranzila-Seite an. Es bietet keine gespeicherten Karten oder Token, keine Abonnements, keine getrennte Autorisierung und Erfassung (J5), keine eigenen Schaltflächen für Bit, Apple Pay oder Google Pay (was Ihre Tranzila-Zahlungsseite anbietet, wird im iframe angezeigt) und keine Tranzila-Rechnungen.
Bestellungen und Erstattungen
Order statuses
Pending payment: der Kunde wurde zur Zahlungsseite geschickt und hat noch nicht bezahlt, oder die Benachrichtigung von Tranzila ist noch nicht eingegangen.
Processing or Completed: die Zahlung wurde durch eine geprüfte Benachrichtigung bestätigt. WooCommerce setzt Processing, bzw. Completed für Bestellungen ohne Versand. Die Bestellnotiz zeigt den Betrag, die Tranzila-Transaktion und die Autorisierungsnummer sowie die Anzahl der Raten, falls vorhanden. Die Transaktions-ID ist der Tranzila-Transaktionsindex.
On hold: die Zahlung wurde eingegangen, aber nicht automatisch akzeptiert: Betrag, Währung oder Handshake-Token stimmten nicht mit der Bestellung überein, die Benachrichtigung ließ sich nicht prüfen, weil Trusted IP leer ist, oder Benachrichtigungen sind aus und der Kunde kam von einer erfolgreichen Zahlungsseite zurück. Die Bestellnotiz erklärt den Grund. Prüfen Sie die Zahlung im Tranzila-Terminal und ändern Sie den Status manuell.
Failed: Tranzila hat für eine ausstehende Bestellung eine abgelehnte Zahlung gemeldet. Die Notiz zeigt den Antwortcode und seine Bedeutung. Eine bereits bezahlte Bestellung wird nie auf Failed gesetzt.
Kommt eine Zahlung für eine stornierte Bestellung an, wird die Bestellung mit einer Notiz wieder geöffnet, die Sie bittet, vor dem Versand den Bestand zu prüfen. Wechselte der Kunde auf der Seite Pay for order zu einer anderen Zahlungsart, bezahlte aber auf einer noch offenen Tranzila-Seite, wird die Zahlungsart der Bestellung wieder auf Tranzila gesetzt. Kommt eine zweite Zahlung für eine bereits bezahlte, abgeschlossene oder erstattete Bestellung an, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, sie zu prüfen und das Duplikat im Tranzila-Terminal zu erstatten. Wiederholte Benachrichtigungen derselben Transaktion werden ignoriert.
Refunds
Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit Card (Tranzila) (die Schaltfläche zeigt den Titel der Zahlungsart). Volle und teilweise Erstattungen werden unterstützt. Die Erstattung erfolgt als Tranzila-Gutschriftbuchung der ursprünglichen Zahlung. Die Schaltfläche ist verfügbar, wenn das Terminal-Passwort gesetzt ist und die Bestellung eine bestätigte Tranzila-Transaktion mit Autorisierungsnummer hat. Eine erfolgreiche Erstattung wird mit der Tranzila-Gutschriftbuchung in den Bestellnotizen ergänzt.
Akzeptiert Tranzila die Erstattung nicht, zeigt WooCommerce den Fehler, zum Beispiel Tranzila declined the refund mit dem Code, und es wird keine Erstattung verbucht. Eine Bestellung, die auf einem anderen als dem aktuell eingestellten Terminal bezahlt wurde (zum Beispiel einem Testterminal), kann nicht aus WooCommerce erstattet werden; erstatten Sie sie in diesem Tranzila-Terminal. Im Tranzila-Terminal vorgenommene Erstattungen werden dem Shop nicht gemeldet. Falls nötig, legen Sie eine manuelle Erstattung in WooCommerce ohne die Tranzila-Schaltfläche an.
Lizenzschlüssel
Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock steht oben unter WooCommerce > Settings > Payments > Tranzila. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block 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 auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt den Domain-Platz nicht frei. Geben Sie ihn in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird Tranzila Kunden an der Kasse nicht angezeigt. Wird eine Zahlung dennoch gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert 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 bleiben unberührt: 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
Tranzila does not appear at checkout: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, Terminal name (supplier) ausgefüllt ist und die Shop-Währung (auf der Seite Pay for order die Bestellwährung) ILS, USD, EUR oder GBP ist. Die Einstellungsseite zeigt eine Warnung, wenn der Terminalname fehlt oder die Währung nicht unterstützt wird.
The payment went through, but the order stays Pending payment: die Benachrichtigung ist nicht angekommen oder wurde abgelehnt. Prüfen Sie, ob Notifications eingeschaltet ist und Trusted IP die Adressen enthält, von denen Tranzila Benachrichtigungen sendet. Fehler werden immer in WooCommerce > Status > Logs, Quelle wcp_tranzila_payment_gateway, geschrieben. Die Meldung, dass eine IP nicht in der Liste Trusted IP steht, bedeutet, dass die Einstellung Trusted IP oder Ihre Proxy-Konfiguration korrigiert werden muss: Hinter einem Proxy oder einer CDN muss der Webserver die echte Besucher-IP an PHP weitergeben.
Notification answers Forbidden: sie kam von einer IP-Adresse, die nicht in Trusted IP steht.
Notification answers Bad request or Not found: die Bestellung, ihr Bestellschlüssel, das Terminal oder der Transaktionsindex in der Benachrichtigung passen zu keiner Bestellung dieses Shops.
Notification answers Accepted for manual review: Trusted IP ist leer, daher konnte die Benachrichtigung nicht geprüft werden. Eine erfolgreiche Zahlung setzt die Bestellung auf Wartestellung. Tragen Sie Trusted IP ein, um Zahlungen automatisch zu bestätigen.
Notification answers Busy, retry: die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet, und die Benachrichtigung wurde nicht angewendet. Prüfen Sie die Zahlung im Tranzila-Terminal; wartet die Bestellung noch auf Zahlung und ist die Zahlung dort genehmigt, ändern Sie den Status manuell.
Some paid orders are On hold: lesen Sie die Bestellnotiz. Betrag, Währung oder Handshake-Token stimmten nicht, oder die Benachrichtigung ließ sich nicht prüfen (Trusted IP leer oder Benachrichtigungen deaktiviert). Prüfen Sie die Zahlung im Tranzila-Terminal und ändern Sie den Status manuell.
The payment page does not open with the handshake on: prüfen Sie Terminalname und Terminal-Passwort, ob der Handshake im Tranzila-Terminal aktiviert ist und ob die IP-Adresse Ihres Servers dort erlaubt ist. Das Protokoll zeigt den Grund.
Refunds fail: Erstattungen benötigen das Terminal password (TranzilaPW). Manche Terminals verlangen zusätzlich ein separates Kreditpasswort; tragen Sie es in Refund password (CreditPass) ein. Auf einem anderen Terminal bezahlte Bestellungen müssen in diesem Terminal erstattet werden.
Other currencies: das Plugin unterstützt ILS, USD, EUR und GBP. Entwickler können die Liste mit dem Filter tranzila_p_currency_map anpassen.
The license block shows an error: folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen 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. Die Einstellungen des Gateways, die auf Bestellungen gespeicherten Tranzila-Daten und die Protokolle des Plugins (einschließlich rotierter Protokolldateien) werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Tranzila ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Tranzila verbunden noch wird es von Tranzila unterstützt.