VibeFox Transbank for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

Shop-Währung: chilenischer Peso (CLP). Webpay Plus berechnet nur ganze Pesos. Stellen Sie daher Number of decimals unter WooCommerce > Settings > General auf 0. In Shops mit 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 dessen produktivem Commerce Code und API Key Secret. Transbank stellt den Commerce Code bereit, sobald Ihre Anbindung genehmigt ist, und das API Key Secret nach dem Integrationsvalidierungsprozess (siehe Transbank-Entwicklerdokumentation). Für Tests sind keine Zugangsdaten nötig. 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 in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können auch den Ordner wcp_transbank_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Stellen Sie die Shop-Währung auf chilenischen Peso und Number of decimals auf 0 ein, unter WooCommerce > Settings > General.

4. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, oder klicken Sie auf der Plugins-Seite unter dem Namen des Plugins auf Settings.

5. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

6. Aktivieren Sie Enable / Disable und testen Sie eine Zahlung bei aktiviertem Integration (test) mode mit den Testkarten aus der Transbank-Entwicklerdokumentation.

7. Für den Live-Betrieb geben Sie Ihren Production Commerce Code und Ihr Production API Key Secret ein, deaktivieren Integration (test) mode und speichern.

Bei Transbank muss keine Return-URL und kein Webhook eingerichtet werden. Das Plugin sendet seine Return-URL bei jeder Transaktion mit.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Transbank Webpay Plus. Oberhalb der Felder warnt Sie die Seite, wenn Produktion gewählt ist, aber der Production Commerce Code oder der API Key fehlt oder ungültig ist (Webpay wird dann an der Kasse ausgeblendet), wenn die Shop-Währung nicht CLP ist (die Zahlungsart wird ausgeblendet) und wenn CLP-Preise Dezimalstellen haben (Summen werden auf ganze Pesos gerundet). Solange der Integrationsmodus aktiv ist, zeigt die Seite Integration (test) environment an: Es wird kein echtes Geld belastet. Nach dem Speichern richten sich die Warnungen nach den neuen Einstellungen. In der Liste der Zahlungsarten ist das Gateway als einrichtungsbedürftig markiert, solange Produktion gewählt ist, aber keine gültigen Zugangsdaten vorliegen.

Allgemein

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. Standard: Webpay Plus.

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

Umgebung und Zugangsdaten

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

Integration (test) mode: Use the Transbank integration environment. Zahlungen gehen an die Transbank-Integrationsumgebung mit deren öffentlichem Test-Commerce-Code (597055555532), der automatisch eingetragen wird. Die produktiven Zugangsdaten unten werden nicht verwendet, und es wird kein echtes Geld belastet. Standard: an. Deaktivieren Sie die Option für den Live-Betrieb.

Production Commerce Code: Ihr produktiver Commerce Code (Tbk-Api-Key-Id): 12 Ziffern, beginnend mit 5970. Wenn Ihrer 8 Ziffern hat, geben Sie ihn unverändert ein; das Plugin 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: der Tbk-Api-Key-Secret Ihres produktiven Commerce. Bewahren Sie ihn geheim auf. Leerzeichen werden beim Speichern entfernt.

Erweitert

Debug log: Log API requests and returns (errors are always logged). Details werden in WooCommerce > Status > Logs geschrieben, Quelle wcp_transbank_gateway; das Feld hat einen Link view logs. Fehler und Warnungen werden auch protokolliert, wenn diese Option aus ist. Es werden keine Kartendaten, API-Schlüssel oder vollständigen Tokens protokolliert. Standard: aus.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). 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 umstellen.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Webpay Plus) und gibt die Bestellung auf. Im Integrationsmodus zeigt die Kasse TEST MODE: Integration environment. Keine echten Belastungen. Das Plugin erstellt für den Bestellbetrag in ganzen Pesos eine Transbank-Transaktion (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 weiterleitet. Ohne JavaScript klickt der Kunde auf Proceed to Webpay. Bei Webpay zahlt der Kunde mit Kredit-, Debit- oder Prepaidkarte.

Bei der Rückkehr des Kunden bestätigt das Plugin die Transaktion serverseitig bei Transbank (commit). 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 sieht der Kunde die Seite „Bestellung eingegangen“. Schlägt der Bestätigungsaufruf fehl, etwa durch einen Timeout, fragt das Plugin bei Transbank den Transaktionsstatus ab. Lässt sich der Status immer noch nicht ermitteln, wird die Bestellung nicht verändert, 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.

Bricht der Kunde auf Webpay ab, läuft das Webpay-Formular ab oder meldet einen Fehler, wird nichts belastet. Die Bestellung bleibt auf „Zahlung ausstehend“, und der Kunde kehrt mit einer Meldung zur Seite Pay for order 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 Kunde kann auf derselben Seite erneut zahlen. Jeder neue Versuch ist eine neue Webpay-Transaktion.

Jeder Webpay-Versuch wird höchstens einmal bestätigt. Das Neuladen der Rückkehrseite, der Zurück-Button des Browsers oder eine zweite Rückkehr zur gleichen Zeit bestätigen nie zweimal und ändern nie die Bestellung. Wenn eine Bestellung keine Zahlung mehr benötigt (bereits durch einen anderen Versuch bezahlt, storniert oder erstattet), wird eine verspätete Rückkehr nicht bestätigt, sodass Transbank sie nicht belastet. 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.

Kann Webpay die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel 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 ins Protokoll geschrieben.

Die Zahlungsart funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

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 die Bestellung bleibt ausstehend; laut Transbank werden unbestätigte Transaktionen nicht abgerechnet. Das Plugin unterstützt keine Webpay Plus Mall, keine gespeicherten Oneclick-Karten, keine Abonnements, keine verzögerte Erfassung und keine Währungsumrechnung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Webpay geschickt und hat noch nicht bezahlt, abgebrochen, das Formular ablaufen lassen oder die Zahlung konnte noch nicht bestätigt werden. Eine Notiz erfasst jeden abgeschlossenen Versuch mit seiner Buy Order.

Processing or Completed: Transbank hat die Zahlung genehmigt. Der Status wird von WooCommerce gesetzt: In Bearbeitung oder, bei Bestellungen nur mit virtuellen herunterladbaren Produkten, Abgeschlossen. Die Bestellnotiz zeigt den Autorisierungscode, die letzten vier Kartenziffern, die Buy Order, den Betrag, die Zahlungsart und die Anzahl der Raten. Die Transaktions-ID ist das Webpay-Token.

On hold: Transbank hat eine Zahlung autorisiert, die nicht zur Bestellung passt (Betrag, Buy Order oder Sitzungs-ID), zum Beispiel weil die Bestellung bearbeitet wurde, nachdem die Zahlung begonnen hatte. Die Notiz listet die Abweichungen auf. Prüfen Sie das Transbank-Portal und erstatten oder vervollständigen Sie die Bestellung.

Failed: Die Zahlung wurde abgelehnt. Es wurde nichts belastet. Die Notiz zeigt den Antwortcode und den Status.

Gibt Webpay eine Zahlung für eine Bestellung zurück, die bereits bezahlt, storniert oder erstattet ist, wird die Zahlung nicht bestätigt, und eine Notiz bittet Sie, das Transbank-Portal zu prüfen, falls der Kunde eine Belastung meldet. Bestehende Bestellungen werden durch spätere Versuche nicht beeinflusst.

Erstattungen

Die Erstattungsschaltfläche wird nur bei Bestellungen angeboten, die über Webpay bezahlt wurden. Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Webpay Plus (die Schaltfläche verwendet den Titel der Zahlungsart). Vollständige und teilweise Erstattungen in ganzen Pesos werden unterstützt. Ein Teilbetrag mit Dezimalstellen wird mit Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. abgelehnt. Der letzte Rest eines Bestellbetrags mit Dezimalstellen wird wie die Belastung gerundet. Die Erstattung geht an die Umgebung, in der die Zahlung erfolgte; in der Produktion müssen daher die produktiven Zugangsdaten gesetzt sein.

Transbank antwortet mit einer Rückbuchung (REVERSED) oder einer Annullierung (NULLIFIED). Eine erfolgreiche Erstattung wird den Bestellnotizen mit Betrag, Typ, Autorisierungscode und dem bei Transbank verbleibenden Saldo hinzugefügt. Akzeptiert Transbank die Erstattung nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst. Im Transbank-Portal vorgenommene Erstattungen werden nicht in WooCommerce importiert.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Transbank Webpay Plus. 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 für eine Domain. Das Entfernen des Schlüssels von einer Website gibt ihren 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. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: 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

Webpay Plus erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, die Shop-Währung CLP ist (auf der Seite Pay for order die Bestellwährung) und, bei ausgeschaltetem Integrationsmodus, ob 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.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt auf Pending payment: Transbank hat keinen Webhook, daher wird die Bestellung nur bestätigt, wenn der Kunde von Webpay zurückkehrt. Hat der Kunde den Browser auf Webpay geschlossen, wurde die Transaktion nicht bestätigt und wird laut Transbank nicht abgerechnet. Prüfen Sie die Bestellnotizen und das Protokoll sowie 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. Die Bestellung wurde nicht verändert, und eine Notiz wurde hinzugefügt. Der Kunde kann es gleich noch einmal versuchen. Zeigt das Transbank-Portal die Transaktion als autorisiert, bestätigen Sie sie dort, bevor Sie versenden.

Der Kunde sieht beim Absenden der Bestellung einen Fehler: Aktivieren Sie Debug log und schauen Sie unter WooCommerce > Status > Logs, Quelle wcp_transbank_gateway, nach. 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. Eine Bestellung in einer anderen Währung als CLP kann nicht mit Webpay bezahlt werden.

Summen und Erstattungen weichen um einige Pesos ab: CLP-Preise haben Dezimalstellen. Webpay belastet ganze Pesos, daher werden Summen gerundet. Setzen Sie Number of decimals auf 0.

Erstattung schlägt fehl mit The production Commerce Code / API Key are missing: Die Zahlung wurde in der Produktion getätigt, 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. Es wurde nichts erstattet. Prüfen Sie die Transaktion im Transbank-Portal.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie einen Platz in Ihrem vibefox.net-Konto frei und klicken Sie auf Check now. Hat sich die Website-Adresse 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. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Einstellungen des Gateways, die übrigen Optionen und temporären Daten des Plugins sowie seine Protokolle (Logdateien, auch rotierte, und Protokolleinträge in der Datenbank) werden nur entfernt, wenn Delete data on uninstall aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Die in Bestellungen gespeicherten Transbank-Daten bleiben immer erhalten, da sie für Buchhaltung und Erstattungen benötigt werden. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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