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

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

Erreichbarer Shop: Datatrans sendet die Webhooks von seinen eigenen Servern, daher muss Ihr Shop aus dem Internet erreichbar sein.

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Datatrans Gateway in der Modulliste und klicken Sie auf Configure.

3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Configure-Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie die Sandbox-Zugangsdaten aus dem Sandbox-Web-Admin von Datatrans ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Führen Sie eine Testzahlung im Sandbox-Modus durch. Wenn alles funktioniert, geben Sie die Produktionszugangsdaten ein und deaktivieren Sie Sandbox mode.

Bei der Installation legt das Modul den Bestellstatus Datatrans payment on hold an. PrestaShop aktiviert das neue Zahlungsmodul standardmäßig für alle Währungen, Länder und Kundengruppen. Sie können diese in Payment > Preferences einschränken; Datatrans wird nur für die dort erlaubten Währungen angezeigt.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Ist die Zahlungsmethode aktiviert, aber in der aktuellen Umgebung fehlen Merchant ID oder API-Passwort, zeigt die Seite Datatrans is hidden at checkout until these settings are filled in: mit den fehlenden Feldern an. Solange der Sandbox-Modus aktiv ist, zeigt die Seite Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged. an.

Datatrans

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Datatrans. Pflichtfeld.

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

Sandbox mode: nutzt die Datatrans-Sandbox: Testzahlungen, kein echtes Geld. Der Schalter wechselt sowohl die Datatrans-Server als auch die für neue Zahlungen verwendeten Zugangsdaten. Standard: ein. Schalten Sie ihn aus, um echte Zahlungen anzunehmen. Solange er eingeschaltet ist, sehen Kunden Sandbox mode: no real payment is taken. unter der Zahlungsmethode. Erstattungen und Erfassungen verwenden immer die Umgebung, in der die Zahlung erfolgte, unabhängig von diesem Schalter.

Sandbox-Zugangsdaten

Kopieren Sie sie aus dem Sandbox-Web-Admin von Datatrans (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 des Sandbox-Kontos.

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

Produktionszugangsdaten

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

Production merchant ID: die Merchant ID Ihres Produktionskontos.

Production API password: das Server-zu-Server-API-Passwort des Produktionskontos.

Production HMAC sign key: der hexadezimale Schlüssel zur Prüfung des Headers Datatrans-Signature der Produktions-Webhooks. Ohne ihn wird jeder Webhook über die Status-API von Datatrans erneut geprüft.

Gespeicherte Passwörter und Signaturschlüssel 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. Ein Signaturschlüssel muss eine hexadezimale Zeichenfolge sein, wie von Datatrans ausgegeben. Jeder andere Wert wird nicht gespeichert: Die Seite zeigt einen Fehler an und behält den bisherigen Wert; die übrigen Einstellungen werden gespeichert.

Clear saved secrets: Setzen Sie den Haken bei einem Passwort oder Signaturschlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Webhook-URL

Der Abschnitt zeigt die Webhook-URL Ihres Shops. Mit freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_datatrans_gateway/webhook, eventuell mit einem Sprachcode wie /en/. Das Modul übermittelt diese URL bei jeder Transaktion an Datatrans, Sie müssen sie also nirgends eintragen. Sie können sie auch in den Webhook-Einstellungen des Datatrans-Web-Admins hinterlegen, um Aktualisierungen für dort vorgenommene Erfassungen und Stornierungen zu erhalten; kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Im Datatrans-Web-Admin vorgenommene Erstattungen werden nicht in der Bestellung übernommen.

Der Webhook meldet den Status der Transaktion. Das Modul reagiert auf folgende Status:

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

Zahlungsabwicklung

Auto settle: erfasst (begleicht) Zahlungen sofort. Ist die Option deaktiviert, werden Zahlungen nur autorisiert: Die Bestellung wird in Datatrans payment on hold gesetzt, und Sie erfassen sie später mit Capture Datatrans payment im Datatrans-Block der Bestellung oder geben sie mit Cancel Datatrans authorization frei. Standard: ein.

Order status after payment: der Bestellstatus, sobald die Zahlung beglichen ist.

Nur autorisierte Zahlungen sowie Abweichungen bei Betrag oder Währung gehen immer in Datatrans payment on hold.

Erweitert

Logging: schreibt Zahlungsereignisse und API-Aufrufe in logs/datatrans_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler werden immer protokolliert, auch wenn dieser Schalter aus ist. Es werden keine Schlüssel, Kartendaten oder Kundendaten geschrieben. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls mit einer Schaltfläche zum Leeren.

Delete data on uninstall: ist die Option eingeschaltet, werden beim Deinstallieren des Moduls die Modul-Einstellungen und das Protokoll entfernt. Die Datatrans-Zahlungsdaten der Bestellungen (Transaktionen, Erstattungen) und der Bestellstatus bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Datatrans) und sieht den Hinweis You will be redirected to the Datatrans payment page to complete the payment securely. Nach der Bestätigung legt das Modul eine Datatrans-Transaktion für den Warenkorbbetrag in der Warenkorbwährung an und leitet den Kunden zur Datatrans-Zahlungsseite weiter. Die Seite öffnet sich auf Deutsch, Englisch, Französisch oder Italienisch, wenn die Shopsprache eine davon ist. Dort bezahlt der Kunde mit einer beliebigen in Ihrem Datatrans-Konto aktivierten Methode. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach dem Bezahlen kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Datatrans die Zahlung bestätigt: durch den Webhook oder durch eine serverseitige Anfrage an die Status-API von Datatrans, wenn der Kunde zurückkehrt. Die Rücksprung-Adresse enthält den sicheren Schlüssel des Warenkorbs, und die Rückkehr selbst legt nie eine Bestellung an. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Your payment with Datatrans has been received. Bei einer nur autorisierten Zahlung zeigt die Seite Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Hat Datatrans die Zahlung noch nicht bestätigt, zeigt eine Seite Payment confirmation den Hinweis Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. mit der Schaltfläche Check again; der Webhook legt die Bestellung an, sobald er eintrifft.

Bricht der Kunde auf der Datatrans-Seite ab, kehrt er zur Kasse zurück und sieht The payment was canceled. You can try again or choose another payment method. Ist die Zahlung fehlgeschlagen, lautet die Meldung The payment was not completed. Please try again or choose another payment method. Der Warenkorb bleibt erhalten. Ein neuer Versuch legt eine neue Datatrans-Transaktion an; eine späte Zahlung aus einem früheren Versuch wird weiterhin erkannt.

Kann Datatrans die Zahlung nicht starten, bleibt der Kunde an der Kasse mit The payment could not be started. Please try again or choose another payment method. Der technische Grund wird im Protokoll gespeichert.

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

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

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde an Datatrans weitergeleitet und hat nicht bezahlt, die Zahlung ist fehlgeschlagen oder wurde abgebrochen, oder Datatrans hat sie noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted, Delivered or Datatrans payment on hold: die Zahlung wurde beglichen. Der Status richtet sich nach Order status after payment. Die Zahlung wird mit der Datatrans-Transaktions-ID erfasst, und eine Notiz zeigt den Betrag, die Zahlungsmethode, die Umgebung und die Art der Bestätigung (Webhook oder Rücksprung).

Datatrans payment on hold nach einer Autorisierung: Auto settle ist aus, und die Zahlung wurde nur autorisiert. Erfassen oder stornieren Sie sie im Block der Bestellung.

Datatrans payment on hold nach der Zahlung: Datatrans hat einen anderen Betrag oder eine andere Währung gemeldet als den Warenkorbbetrag (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlung begonnen hatte), oder die Zahlung ging ein, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Transaktion im Datatrans-Web-Admin und schließen Sie die Bestellung ab oder erstatten Sie die Zahlung.

Canceled: die Autorisierung wurde freigegeben, im Block der Bestellung oder im Datatrans-Web-Admin.

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

Geht eine zweite Zahlung für einen Warenkorb ein, der bereits bezahlt oder autorisiert ist, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, sie zu prüfen und das Duplikat im Datatrans-Web-Admin zu erstatten. Eine fehlgeschlagene oder abgebrochene Transaktion stuft eine bezahlte Bestellung nie herab.

Datatrans-Zahlungsblock

Die Bestellseite zeigt einen Block Datatrans payment mit der Transaktions-ID, dem Datatrans-Status, der Zahlungsmethode, dem Betrag, den bezahlten und erstatteten Beträgen, einem Badge Sandbox für Sandbox-Zahlungen, dem Erstattungsverlauf und den Datatrans notes der Bestellung. Die Aktionen des Blocks erfordern das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig.

Erfassen und stornieren

Bei einer nur autorisierten Zahlung zeigt der Block Capture Datatrans payment und Cancel Datatrans authorization. Die Erfassung begleicht die Zahlung für die aktuelle Bestellsumme, die nicht höher sein darf als der autorisierte Betrag; danach wechselt die Bestellung in den Status aus Order status after payment. Die Stornierung gibt die Autorisierung frei und setzt die Bestellung auf Canceled. Beide Aktionen gehen an die Umgebung der Zahlung. Lehnt Datatrans ab, zeigt der Block den Fehler, und es wird eine Notiz hinzugefügt.

Erstattungen

Geben Sie im Block Datatrans payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Datatrans. Bestätigen Sie die Frage Refund this amount through Datatrans? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt, bis zu dem Betrag, den Datatrans tatsächlich abgebucht hat, abzüglich früherer Erstattungen. Die Erstattung wird an die Umgebung der Zahlung gesendet, daher müssen deren Merchant ID und API-Passwort eingetragen sein. Eine wiederholte Erstattung wird nicht doppelt gutgeschrieben. Akzeptiert Datatrans die Erstattung nicht, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der Transaktions-ID der Datatrans-Erstattung dem Verlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht.

Bei einer nur autorisierten Zahlung wurde noch nichts abgebucht: Erstattet werden kann nur der volle Betrag, was die Autorisierung storniert. Erstattungen sind verfügbar, sobald Datatrans die Zahlung beglichen hat; eine Autorisierung mit abweichendem Betrag kann erst nach der Erfassung erstattet werden.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Datatrans zurück. Im Datatrans-Web-Admin vorgenommene Erstattungen werden nicht in PrestaShop erfasst.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Datatrans Gateway ist der erste Block auf Modules > Module Manager > VibeFox Datatrans Gateway > Configure, oberhalb der Einstellungen. Fügen 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-payment-datatrans 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. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, 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-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 Datatrans Kunden an der Kasse nicht angezeigt. Versucht ein Kunde trotzdem eine Zahlung, sieht er 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 Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen 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. Beim Deinstallieren oder Zurücksetzen des Moduls werden der Lizenzschlüssel und der Lizenzstatus immer entfernt.

Fehlerbehebung

Datatrans does not appear at checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die aktuelle Umgebung ihre Merchant ID und ihr API-Passwort hat: im Sandbox-Modus die Sandbox-Felder, sonst die Produktionsfelder. Die Einstellungsseite listet die fehlenden Felder auf. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

The payment went through, but no order was created: Datatrans konnte die Webhook-URL nicht erreichen, und der Kunde ist nicht in den Shop zurückgekehrt. Prüfen Sie, ob der Shop aus dem Internet erreichbar ist und keine Firewall Anfragen an die Webhook-URL blockiert. Prüfen Sie, ob der Signaturschlüssel in den Einstellungen zur Umgebung der Zahlung gehört. Sehen Sie im Feld Log auf der Modulseite nach.

Webhook answers 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.

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

Webhook answers Busy, retry: Die Bestellung wurde gerade von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Datatrans wiederholt den Webhook. Das Protokoll zeigt den Grund.

The webhook URL shows Method not allowed in the browser: Das ist normal. Die URL akzeptiert nur Anfragen von Datatrans.

The HMAC sign key is not saved: Der Schlüssel muss eine hexadezimale Zeichenfolge sein. Kopieren Sie ihn erneut aus dem Datatrans-Web-Admin.

The customer sees Datatrans payments are not configured yet: Die Merchant ID oder das API-Passwort der aktuellen Umgebung fehlt.

The customer sees The payment could not be started: Sehen Sie im Feld Log nach. Eine falsche Merchant ID oder ein falsches API-Passwort oder Zugangsdaten der falschen Umgebung sind die üblichen Ursachen.

Order is Datatrans payment on hold after payment: Lesen Sie die Datatrans notes im Block der Bestellung (siehe Bestellstatus) und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

Capture is refused: Die Bestellsumme ist höher als der autorisierte Betrag. Datatrans kann nicht mehr erfassen, als autorisiert wurde.

Refund or capture fails with a message about missing credentials: Die Zahlung wurde in der anderen Umgebung getätigt, und deren Merchant ID oder API-Passwort ist nicht eingetragen. Geben Sie sie ein und versuchen Sie es erneut.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Datatrans Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Modul-Einstellungen und das Protokoll entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Datatrans-Transaktionen und -Erstattungen sowie der Bestellstatus Datatrans payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet oder erfasst werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Datatrans ist eine Marke des jeweiligen Inhabers. Dieses Modul ist weder mit Datatrans verbunden noch wird es von Datatrans unterstützt.