VibeFox Transbank 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.

Währung: chilenischer Peso (CLP). Webpay Plus berechnet nur ganze Pesos. Stellen Sie deshalb die Genauigkeit der Währung CLP unter International > Localization > Currencies auf 0 ein. Bei Warenkörben in einer anderen Währung wird die Zahlungsart nicht angezeigt.

Transbank-Konto: Für Echtzahlungen benötigen Sie einen Standard-Webpay-Plus-Commerce (sofortige Erfassung) mit seinem produktiven Commerce Code und seinem API Key Secret. Transbank stellt Ihnen den Commerce Code bereit, sobald Ihre Anbindung genehmigt ist, und das API Key Secret nach dem Validierungsprozess der Integration (siehe Entwicklerdokumentation von Transbank). Für Tests werden keine Zugangsdaten benötigt. Commerce-Codes für Webpay Plus Mall, Oneclick und verzögerte Erfassung werden nicht unterstützt.

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 später VibeFox Transbank Gateway in der Modulliste und klicken Sie 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. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Testen Sie eine Zahlung bei aktiviertem Integration (test) mode mit den Testkarten aus der Entwicklerdokumentation von Transbank.

5. Um live zu gehen, geben Sie Ihren Production Commerce Code und Ihr Production API Key Secret ein, deaktivieren Sie Integration (test) mode und klicken Sie auf Save.

Bei Transbank muss weder eine Rückkehr-URL noch ein Webhook eingerichtet werden. Das Modul sendet seine Rückkehr-URL mit jeder Transaktion.

Bei der Installation legt das Modul den Bestellstatus Transbank payment on hold an. PrestaShop aktiviert das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken; die Währung CLP muss für das Modul erlaubt bleiben.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Transbank Gateway > Configure. Jeder Abschnitt hat seinen eigenen Button Save, der die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn Produktion gewählt ist, der produktive Commerce Code oder der API Key aber fehlt oder ungültig ist (Webpay wird dann an der Kasse ausgeblendet), wenn die Standardwährung des Shops nicht CLP ist (die Zahlungsart wird für andere Währungen ausgeblendet) und wenn CLP Dezimalstellen hat (Beträge werden auf ganze Pesos gerundet). Solange der Integrationsmodus aktiv ist, zeigt die Seite an, dass Zahlungen an die Integrationsumgebung von Transbank mit dem öffentlichen Test-Commerce-Code gehen und kein echtes Geld abgebucht wird.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Webpay Plus. Pflichtfeld: Beim Speichern mit leerem Titel erscheint Enter a title for the payment method.

Description: der Text, der unter der Zahlungsart an der Kasse angezeigt wird. Standard: Pay with credit, debit or prepaid card via Webpay.

Umgebung und Zugangsdaten

Der Abschnittstext verlinkt auf die Entwicklerdokumentation von Transbank und erklärt, wann Transbank die produktiven Zugangsdaten ausgibt.

Integration (test) mode: Zahlungen gehen an die Integrationsumgebung von Transbank mit ihrem öffentlichen Test-Commerce-Code (597055555532), der automatisch eingetragen wird. Die produktiven Zugangsdaten unten werden nicht verwendet, und es wird kein echtes Geld abgebucht. Standard: an. Zum Live-Betrieb ausschalten. Solange er aktiv ist, sehen Kunden TEST MODE: Integrationsumgebung. Keine echten Abbuchungen. über der Beschreibung der Zahlungsart.

Production Commerce Code: Ihr produktiver Commerce Code (Tbk-Api-Key-Id): 12 Ziffern, beginnend mit 5970. Hat Ihrer 8 Ziffern, geben Sie ihn so ein, wie er ist; das Modul ergänzt beim Speichern das Präfix 5970. Leerzeichen und andere Zeichen werden entfernt. Die öffentlichen Test-Commerce-Codes von Transbank werden in der Produktion nicht akzeptiert.

Production API Key Secret: das Tbk-Api-Key-Secret Ihres produktiven Commerce. Halten Sie es geheim. Leerzeichen werden beim Speichern entfernt. Ein gespeicherter 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.

Clear saved API key: Setzen Sie den Haken bei Production API Key Secret und klicken Sie auf Save, um den gespeicherten Schlüssel zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Rückkehr-URL

Return from Webpay: die Adresse, zu der Transbank den Kunden zurückschickt, nur zur Information angezeigt. Bei Transbank muss nichts eingerichtet werden: Das Modul sendet diese URL mit jeder Transaktion. Sie muss für Kunden erreichbar sein; der Wartungsmodus blockiert sie nicht.

Erweitert

Debug log: protokolliert API-Anfragen und Rückkehren in logs/wc_tbk_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. Es werden keine Kartendaten, API-Schlüssel oder vollständigen Tokens protokolliert. Standard: aus.

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 die Deinstallation des Moduls die Einstellungen des Gateways und das Protokoll. Bestelldaten bleiben erhalten. Standard: aus.

Test und Live

Integration (test) mode bestimmt, wohin neue Zahlungen gehen. Jede Zahlung merkt sich ihre Umgebung: Bestätigung und Erstattungen einer Zahlung gehen immer an die Umgebung (Integration oder Produktion) und mit den Zugangsdaten, mit denen sie erstellt wurde, auch wenn Sie den Modus später ändern.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Webpay Plus mit dem Webpay-Logo) und bestätigt. Das Modul erstellt eine Transbank-Transaktion für den Warenkorbbetrag in ganzen Pesos (ein Betrag mit Dezimalstellen wird auf den nächsten Peso gerundet) und leitet den Kunden auf eine kurze Seite Redirecting to Webpay. Please wait... weiter, die zum Webpay-Formular führt. Ohne JavaScript klickt der Kunde auf Proceed to Webpay. Auf Webpay zahlt der Kunde mit Kredit-, Debit- oder Prepaidkarte. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Bei der Rückkehr des Kunden bestätigt (committet) das Modul die Transaktion serverseitig bei Transbank. Die Bestellung wird erst als bezahlt markiert, nachdem Transbank bestätigt hat: Die Antwort muss genehmigt sein, und Betrag, Buy Order und Sitzung müssen mit dem übereinstimmen, was der Shop für diesen Versuch gesendet hat. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Your Webpay payment has been received. Bei einer Bestellung in Prüfung zeigt die Seite Your Webpay payment was received and is being reviewed by the shop.

Schlägt der Bestätigungsaufruf fehl, etwa durch eine Zeitüberschreitung, fragt das Modul bei Transbank den Transaktionsstatus ab. Lässt sich der Status dann immer noch nicht ermitteln, wird keine Bestellung angelegt und der Kunde sieht We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. Bestätigt gerade eine andere Anfrage denselben Warenkorb, oder hat Transbank die Zahlung genehmigt, die Bestellung aber noch nicht angelegt werden können, sieht der Kunde eine Seite Payment confirmation mit Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. und einem Button Check again. Die Bestellung wird dann aus der gespeicherten Antwort angelegt, ohne eine zweite Bestätigung.

Bricht der Kunde auf Webpay ab oder läuft das Webpay-Formular ab bzw. meldet einen Fehler, wird nichts abgebucht. Der Kunde kehrt mit einer Meldung zur Kasse zurück, zum Beispiel You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Eine abgelehnte Karte zeigt Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. Der Warenkorb bleibt erhalten, und jeder neue Versuch ist eine neue Webpay-Transaktion.

Hat sich der Warenkorb geändert, nachdem die Zahlung begonnen wurde (etwa in einem anderen Tab, oder ein Gutschein im Warenkorb ist nicht mehr gültig und PrestaShop hat ihn entfernt), wird die Transaktion nicht bestätigt, und Transbank belastet sie nicht. Der Kunde sieht Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Hat der Warenkorb bereits eine Bestellung (bezahlt durch einen anderen Versuch oder eine andere Zahlungsart), wird auch eine verspätete Rückkehr nicht bestätigt, und der Kunde sieht This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged., wenn diese Bestellung nicht bezahlt ist.

Kann Webpay die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, etwa Could not connect to Webpay. Please try again in a moment. oder Webpay payments are not available at the moment. Please choose another payment method. Der technische Grund wird im Protokoll festgehalten.

Die Rückkehr von Webpay funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Transbank hat keinen Zahlungs-Webhook: Das Ergebnis wird verarbeitet, wenn der Kunde von Webpay zurückkehrt. Schließt der Kunde den Browser auf Webpay und kehrt nie zurück, wird die Transaktion nicht bestätigt und keine Bestellung angelegt; laut Transbank werden unbestätigte Transaktionen nicht abgerechnet. Das Modul unterstützt weder Webpay Plus Mall, Oneclick-Karten, Abonnements, verzögerte Erfassung noch Währungsumrechnung.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde wurde zu Webpay weitergeleitet und hat nicht bezahlt, abgebrochen, das Formular ablaufen lassen, die Karte wurde abgelehnt oder die Zahlung konnte noch nicht bestätigt werden. Es existiert nur der Warenkorb.

Payment accepted: Transbank hat die Zahlung genehmigt. Die Zahlung wird mit dem Webpay-Token als Transaktions-ID erfasst, und eine Notiz zeigt den Autorisierungscode, die letzten vier Kartenziffern, die Buy Order, den Betrag, die Zahlungsart und die Anzahl der Raten.

Transbank payment on hold: Transbank hat eine Zahlung autorisiert, die nicht zur Bestellung passt (Betrag, Buy Order oder Sitzung), oder ein Gutschein im Warenkorb ist nicht mehr gültig, nachdem Transbank die Zahlung genehmigt hat, und PrestaShop hat ihn entfernt. Die Zahlung wird mit dem Betrag erfasst, den Transbank abgebucht hat, und die Notiz listet die Abweichungen auf. Prüfen Sie das Transbank-Portal und bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

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

Gibt Webpay eine Zahlung für einen Warenkorb zurück, der bereits eine Bestellung hat, wird die Zahlung nicht bestätigt, und eine Notiz bei dieser Bestellung bittet Sie, das Transbank-Portal zu prüfen, falls der Kunde eine Abbuchung meldet. Bestehende Bestellungen werden durch spätere Versuche nicht berührt.

Block Transbank Webpay Plus

Die Bestellseite zeigt einen Block Transbank Webpay Plus mit der Buy Order und ihrer Umgebung, dem Zahlungsstatus, dem Autorisierungscode, Karten- und Zahlungsart mit der Anzahl der Raten, dem abgebuchten und erstatteten Betrag, einem Abzeichen Integration für Testzahlungen, dem Erstattungsverlauf, den Webpay attempts of the cart und den Transbank notes der Bestellung.

Erstattungen

Geben Sie im Block Transbank Webpay Plus den Betrag in CLP ein (der noch nicht erstattete Betrag wird eingetragen), optional einen Grund, und klicken Sie auf Refund via Transbank. Bestätigen Sie die Frage Refund this amount via Transbank? Vollständige und teilweise Erstattungen werden in ganzen Pesos unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Ein Teilbetrag mit Dezimalstellen wird mit Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. abgelehnt. Ein Restbetrag einer Bestellsumme mit Dezimalstellen wird wie die Abbuchung gerundet. Erstattungen sind bis zum Betrag möglich, den Transbank abgebucht hat; nach einer Abweichung können Sie also den Betrag erstatten, den der Kunde tatsächlich bezahlt hat. Die Erstattung geht an die Umgebung, in der die Zahlung erfolgte; für eine Produktivzahlung müssen daher die produktiven Zugangsdaten eingetragen sein.

Transbank antwortet mit einer Stornierung (REVERSED) oder einer Annullierung (NULLIFIED). Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit Betrag, Art, Autorisierungscode und dem bei Transbank verbleibenden Saldo hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht. Akzeptiert Transbank die Erstattung nicht, zeigt der Block den Fehler, und es wird keine Erstattung erfasst.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsbuttons von PrestaShop auf der Bestellseite schicken kein Geld über Transbank zurück. Im Transbank-Portal vorgenommene Erstattungen werden nicht in PrestaShop importiert.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Transbank Gateway ist der erste Block auf Modules > Module Manager > VibeFox Transbank Gateway > Configure, oberhalb der Einstellungen. Tragen 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 zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-transbank 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. Nach einer Änderung der Shop-Adresse 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 bei 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 Webpay Plus Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Die 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 nicht an der Kasse testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, wenn der Kunde von Webpay zurückkehrt, und Erstattungen über die Bestellseite funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird während der 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. Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Webpay Plus erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, die Warenkorb-Währung CLP ist und, bei ausgeschaltetem Integrationsmodus, ein gültiger Production Commerce Code (12 Ziffern, beginnend mit 5970) und ein Production API Key Secret gespeichert sind. Die Einstellungsseite zeigt für jede fehlende Bedingung eine Warnung. Prüfen Sie unter Payment > Preferences, ob das Modul für CLP, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: Transbank hat keinen Webhook, daher wird die Bestellung nur angelegt, wenn der Kunde von Webpay zurückkehrt. Hat der Kunde den Browser auf Webpay geschlossen, wurde die Transaktion nicht bestätigt und laut Transbank nicht abgerechnet. Aktivieren Sie das Debug log, sehen Sie sich das Feld Log an und prüfen Sie die Transaktion im Transbank-Portal.

Der Kunde sieht We could not confirm your Webpay payment with Transbank: Der Bestätigungsaufruf ist fehlgeschlagen und der Status konnte nicht geprüft werden. Es wurde keine Bestellung angelegt, der Grund steht im Protokoll. Der Kunde kann es in einem Moment erneut versuchen. Zeigt das Transbank-Portal die Transaktion als autorisiert, kontaktieren Sie den Kunden, bevor er erneut zahlt.

Der Kunde sieht Your cart changed after the Webpay payment was started: Der Warenkorbbetrag wich von der Transaktion ab, etwa wegen einer Änderung in einem anderen Tab oder eines abgelaufenen Gutscheins. Es wurde nichts abgebucht; der Kunde zahlt den neuen Betrag.

Der Kunde sieht einen Fehler bei der Auswahl von Webpay Plus: Aktivieren Sie das Debug log und sehen Sie sich das Feld Log auf der Modulseite an. Webpay payments are not available at the moment bedeutet meist falsche produktive Zugangsdaten. Could not connect to Webpay bedeutet, dass Transbank nicht erreicht werden konnte. Transbank Webpay only supports payments in CLP (Chilean Peso) bedeutet, dass der Warenkorb in einer anderen Währung ist.

Beträge und Erstattungen weichen um einige Pesos ab: Die Währung CLP hat Dezimalstellen. Webpay berechnet nur ganze Pesos, daher werden Beträge gerundet. Stellen Sie die Genauigkeit von CLP unter International > Localization > Currencies auf 0 ein.

Die Bestellung ist nach der Zahlung Transbank payment on hold: Lesen Sie die Notizen im Block Transbank Webpay Plus (siehe Bestellstatus), und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt fehl mit The production Commerce Code / API Key are missing: Die Zahlung wurde in der Produktion gemacht, und die produktiven Zugangsdaten sind nicht gespeichert. Geben Sie sie ein und versuchen Sie es erneut.

Erstattung schlägt fehl mit Transbank refused the refund oder Transbank did not approve the refund: Transbank hat sie nicht akzeptiert; die Meldung zeigt den Grund bzw. den Typ und den Antwortcode, den Transbank zurückgegeben hat. Es wurde nichts erstattet. Prüfen Sie die Transaktion im Transbank-Portal.

Erstattung schlägt fehl mit Another request is processing this order: Die Bestellung wurde im selben Moment erstattet oder bestätigt. Versuchen Sie es in einem Moment erneut.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Transbank 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 des Gateways und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Webpay-Versuche und Erstattungen der Bestellungen sowie der Bestellstatus Transbank 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.

Transbank und Webpay sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist nicht mit Transbank verbunden und wird nicht von Transbank unterstützt.