VibeFox Datatrans for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv.

PHP: 8.0 oder neuer.

HTTPS: Ihre Website muss über HTTPS aus dem Internet erreichbar sein, damit Datatrans Webhooks zustellen kann.

Datatrans-Konto: Sie benötigen die Merchant ID, das Server-zu-Server-API-Passwort und, empfohlen, den HMAC-SHA256-Signaturschlüssel für Webhooks. Die Sandbox-Zugangsdaten erhalten Sie im Datatrans-Sandbox-Web-Admin (admin.sandbox.datatrans.com), die Live-Zugangsdaten im Live-Web-Admin (admin.datatrans.com). Sandbox und Live sind getrennte Datatrans-Konten mit unterschiedlichen Merchant IDs und Schlüsseln.

Währung: Die Shop-Währung (oder die Bestellwährung Ihres Multiwährungs-Plugins) muss für Ihr Datatrans-Händlerkonto aktiviert sein.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt 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 den Ordner wcp_datatrans_gateway auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate. WooCommerce muss aktiv sein.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Datatrans > Manage, oder klicken Sie auf der Plugins-Seite unter dem Plugin-Namen auf Settings.

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

5. Geben Sie die Sandbox-Zugangsdaten und, für echte Zahlungen, die Live-Zugangsdaten ein (siehe Konfiguration).

6. Schalten Sie Enable/Disable ein. Lassen Sie Sandbox mode während der Tests eingeschaltet und entfernen Sie dann das Häkchen, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Datatrans. Ist das Gateway aktiviert, aber die Merchant ID oder das API-Passwort der aktuellen Umgebung fehlt, zeigt die Seite Datatrans is hidden at checkout until these settings are filled in: mit der Liste der fehlenden Felder. Solange der Sandbox-Modus aktiv ist, zeigt sie Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Webhook

Die Webhook URL wird oben in den Einstellungen angezeigt. Sie sieht so aus: https://your-site/wc-api/datatrans_payment_callback/. Das Plugin sendet diese URL mit jeder Transaktion an Datatrans, Sie müssen sie also nirgends eintragen. Sie können sie zusätzlich in den Webhook-Einstellungen des Datatrans-Web-Admin eintragen, um Aktualisierungen zu dort vorgenommenen Erfassungen und Stornierungen zu erhalten.

Der Webhook meldet den Zustand der Transaktion. Das Plugin reagiert auf diese Zustände:

Mit einem HMAC-Signaturschlüssel wird jeder Webhook anhand seines Datatrans-Signature-Headers geprüft. Webhooks ohne gültige Signatur werden abgelehnt. Ohne Signaturschlüssel vertraut das Plugin dem Inhalt des Webhooks nicht und prüft jeden Webhook gegen die Datatrans-Status-API. Ohne den Webhook wird eine Bestellung nur bestätigt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Allgemein

Enable/Disable: Enable Datatrans Payment schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Datatrans.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Der Modus schaltet sowohl die Hosts der API und der Zahlungsseite als auch die unten stehenden Zugangsdaten um. Erstattungen und Erfassungen verwenden immer die Umgebung, in der die Zahlung erfolgte. Standard: ein. Entfernen Sie das Häkchen, um echte Zahlungen anzunehmen.

Sandbox-Zugangsdaten

Kopieren Sie sie aus dem Datatrans-Sandbox-Web-Admin (admin.sandbox.datatrans.com). Der Signaturschlüssel befindet sich dort in den Sicherheitseinstellungen.

Sandbox merchant ID: die Merchant ID Ihres Sandbox-Kontos.

Sandbox API password: das Server-zu-Server-API-Passwort Ihres Sandbox-Kontos.

Sandbox HMAC sign key: der Hex-Schlüssel zur Überprüfung des Datatrans-Signature-Headers von Webhooks. Ohne ihn wird jeder Webhook erneut gegen die Datatrans-Status-API geprüft.

Live-Zugangsdaten

Kopieren Sie sie aus dem Datatrans-Live-Web-Admin (admin.datatrans.com).

Production merchant ID: die Merchant ID Ihres Live-Kontos.

Production API password: das Server-zu-Server-API-Passwort Ihres Live-Kontos.

Production HMAC sign key: der Hex-Schlüssel zur Überprüfung des Datatrans-Signature-Headers von Live-Webhooks. Ohne ihn wird jeder Webhook erneut gegen die Datatrans-Status-API geprüft.

Ein Signaturschlüssel muss eine von Datatrans ausgestellte hexadezimale Zeichenfolge sein. Jeder andere Wert wird nicht gespeichert: Die Seite zeigt einen Fehler und behält den vorherigen Wert bei. Wenn Sie von Version 1.0 aktualisieren, wird der einzige Satz Zugangsdaten dieser Version in die Sandbox-Felder übernommen, sofern der Sandbox-Modus aktiv war; andernfalls bleibt er in den Live-Feldern.

Zahlungsabwicklung

Auto settle: Capture (settle) payments immediately. Standard: ein. Wenn Sie es ausschalten, werden Zahlungen nur autorisiert: Die Bestellung wird auf „In Wartestellung“ gesetzt, und Sie erfassen sie später mit der Bestellaktion Capture Datatrans payment oder geben sie mit Cancel Datatrans authorization frei.

Order status after payment: der Bestellstatus, der gesetzt wird, sobald die Zahlung abgerechnet ist. Der Status wird sofort gesetzt, ohne einen zweiten Statuswechsel.

Erweitert

Logging: Log payment events and API calls schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_datatrans_gateway. Fehler werden immer protokolliert. Es werden keine Schlüssel, Kartendaten oder Kundendaten geschrieben. Standard: aus.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Datatrans) und gibt die Bestellung auf. Das Plugin erstellt für den Bestellbetrag in der Bestellwährung eine Datatrans-Transaktion mit der Bestell-ID als Referenz und leitet den Kunden zur Datatrans-Zahlungsseite weiter. Dort bezahlt der Kunde mit einer beliebigen in Ihrem Datatrans-Konto aktivierten Methode, zum Beispiel Karte, TWINT oder PostFinance. Die Zahlungsseite öffnet sich auf Deutsch, Englisch, Französisch oder Italienisch, wenn Ihre Website eine dieser Sprachen verwendet; andernfalls wählt Datatrans die Sprache.

Nach der Zahlung kehrt der Kunde zur Bestellbestätigungsseite Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn Datatrans sie bestätigt: durch den Webhook oder durch eine serverseitige Anfrage an die Datatrans-Status-API bei der Rückkehr des Kunden. Die Rücksprungadresse enthält den Bestellschlüssel, und die Rückkehr allein markiert eine Bestellung nie als bezahlt.

Wenn der Kunde auf der Zahlungsseite abbricht, gelangt er auf die Seite Pay for order mit der Meldung The payment was canceled. You can try again or choose another payment method. Nach einer fehlgeschlagenen Zahlung lautet die Meldung The payment was not completed. Please try again or choose another payment method. Die Bestellung bleibt zahlbar, und der Kunde kann es erneut versuchen.

Wenn Datatrans die Zahlung nicht starten kann, sieht der Kunde The payment could not be started. Please try again or choose another payment method. Der Grund wird ins Protokoll geschrieben.

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

Das Plugin verarbeitet nur Einmalzahlungen auf der Datatrans-Zahlungsseite. Es unterstützt keine gespeicherten Karten oder Aliase, keine Abonnements, keine Lightbox- oder Secure-Fields-Integration, keine Auswahl der Zahlungsmethoden in den Einstellungen und keine Teilerfassung einer Autorisierung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Datatrans weitergeleitet und hat noch nicht bezahlt, hat auf der Zahlungsseite abgebrochen, oder Datatrans hat die Zahlung noch nicht bestätigt. Jede neue Transaktion wird mit ihrer ID und Umgebung in der Bestellung vermerkt.

Processing, Completed or On Hold: Die Zahlung wurde abgerechnet. Der Status richtet sich nach Order status after payment. Die Bestellnotiz zeigt den Betrag, die Zahlungsmethode, die Datatrans-Transaktions-ID und die Umgebung (Sandbox oder Live). Die Transaktions-ID wird in der Bestellung gespeichert.

On hold, authorized: Bei ausgeschaltetem Auto settle wurde die Zahlung autorisiert, aber nicht erfasst. Öffnen Sie die Bestellung und wählen Sie in den Bestellaktionen Capture Datatrans payment oder Cancel Datatrans authorization. Die Erfassung verwendet den aktuellen Bestellbetrag, der nicht höher sein darf als der autorisierte Betrag. Ist er höher oder lehnt Datatrans die Erfassung oder Stornierung ab, wird der Grund den Bestellnotizen hinzugefügt.

On hold after payment: Datatrans hat einen anderen Betrag oder eine andere Währung als den Bestellbetrag gemeldet (zum Beispiel, weil die Bestellung nach dem Start der Zahlung bearbeitet wurde), oder die Zahlung ging ein, nachdem die Bestellung storniert worden war. Die Bestellnotiz erklärt es. Prüfen Sie die Transaktion im Datatrans-Web-Admin und wickeln Sie die Bestellung ab oder erstatten Sie die Zahlung.

Failed: Die Zahlung ist fehlgeschlagen oder wurde abgelehnt. Der Kunde kann es erneut versuchen.

Cancelled: Die Autorisierung wurde freigegeben, durch die Bestellaktion oder im Datatrans-Web-Admin.

Eine verspätete Meldung über Fehlschlag oder Stornierung ändert eine bezahlte Bestellung nie. Geht für eine bereits bezahlte Bestellung eine zweite erfolgreiche Zahlung ein, bleibt die Bestellung unverändert. Eine Notiz warnt vor einer möglichen Doppelbelastung und bittet Sie, diese bei Bedarf in Datatrans zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Datatrans. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird in der Umgebung gesendet, in der die Zahlung erfolgte; daher müssen die Zugangsdaten dieser Umgebung hinterlegt sein. Eine wiederholte Erstattung wird nicht doppelt gutgeschrieben. Wenn Datatrans die Erstattung nicht annimmt, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird den Bestellnotizen mit dem Betrag und der Datatrans-Erstattungstransaktions-ID hinzugefügt.

Bei einer Zahlung, die nur autorisiert ist, storniert die Erstattung des vollen Betrags die Autorisierung. Eine Teilerstattung ist erst möglich, wenn die Zahlung erfasst wurde.

Im Datatrans-Web-Admin vorgenommene Erstattungen werden in WooCommerce nicht erfasst. Erstellen Sie bei Bedarf in WooCommerce eine manuelle Erstattung ohne Refund via Datatrans.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben auf WooCommerce > Settings > Payments > Datatrans. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status an, 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 gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Datatrans den Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), sodass Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen und Erfassungen funktionieren.

Wenn eine Lizenz abläuft, arbeitet das Plugin weiter, aber für Updates und Support ist eine Verlängerung nötig. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Datatrans erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Merchant ID und das API-Passwort der aktuellen Umgebung gesetzt sind: im Sandbox-Modus die Sandbox-Felder, sonst die Live-Felder. Die Einstellungsseite listet die fehlenden Felder auf.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt „Zahlung ausstehend“: Datatrans konnte die Webhook-URL nicht erreichen, und der Kunde ist nicht in den Shop zurückgekehrt. Prüfen Sie, ob die Website über HTTPS aus dem Internet erreichbar ist und ob kein Sicherheits-Plugin oder keine Firewall Anfragen an /wc-api/datatrans_payment_callback/ blockiert. Prüfen Sie, ob der Signaturschlüssel in den Einstellungen zur Umgebung der Zahlung gehört. Schalten Sie Logging ein und sehen Sie unter WooCommerce > Status > Logs nach, Quelle wcp_datatrans_gateway.

Der Webhook antwortet Invalid signature: Der HMAC-Signaturschlüssel in den Einstellungen stimmt nicht mit dem im Datatrans-Web-Admin überein oder gehört zur anderen Umgebung. Kopieren Sie den Schlüssel erneut.

Der Webhook antwortet Not configured oder Verification failed: Der Webhook musste mit der Datatrans-Status-API geprüft werden, aber die Zugangsdaten dieser Umgebung fehlen, oder Datatrans hat nicht geantwortet. Datatrans wiederholt den Webhook.

Der HMAC-Signaturschlüssel wird nicht gespeichert: Der Schlüssel muss eine hexadezimale Zeichenfolge sein. Kopieren Sie ihn erneut aus dem Datatrans-Web-Admin.

Der Kunde sieht The payment could not be started: Die Merchant ID oder das API-Passwort ist falsch, gehört zur anderen Umgebung, oder die Währung ist für Ihr Datatrans-Konto nicht aktiviert. Schalten Sie Logging ein, um den Grund zu sehen.

Die Bestellung ist nach der Zahlung „In Wartestellung“: Lesen Sie die Bestellnotiz. Der gezahlte Betrag oder die Währung wich von der Bestellung ab, die Zahlung kam nach der Stornierung der Bestellung, oder die Zahlung ist nur autorisiert und wartet auf die Erfassung.

Die Erfassung ist nicht möglich: Der Bestellbetrag ist höher als der autorisierte Betrag. Die Erfassung verwendet den aktuellen Bestellbetrag; reduzieren Sie ihn daher auf den autorisierten Betrag oder weniger.

Die Erstattung schlägt mit einer Meldung zu den Zugangsdaten fehl: Die Zahlung erfolgte in der anderen Umgebung, und deren Zugangsdaten sind nicht hinterlegt. Tragen Sie sie ein und versuchen Sie es erneut. Bei einer autorisierten Zahlung erstatten Sie den vollen Betrag oder erfassen die Zahlung zuerst.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wird 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. 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.

Für Entwickler: Die Readme erwähnt den Filter wcp_datatrans_gateway_init_request, zum Beispiel, um die auf der Datatrans-Seite angezeigten Zahlungsmethoden einzuschränken.

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 Gateway-Einstellungen 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.

Datatrans ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist nicht mit Datatrans verbunden und wird von Datatrans nicht empfohlen.