OXID esales Dokumentation

Transkript

1 OXID esales Dokumentation Neuinstallation des heidelpay Moduls für OXID efire Version 1.4.2

2 Copyright Copyright 2010 OXID esales AG, Deutschland Die Vervielfältigung dieses Dokuments oder Teilen davon, insbesondere die Verwendung von Texten oder Textteilen bedarf der ausdrücklichen vorherigen Zustimmung der OXID esales AG. Eine Dekompilierung des Quellcodes, unerlaubte Vervielfältigung sowie die Weitergabe an Dritte ist nicht gestattet. Zuwiderhandlungen werden ausnahmslos zur Anzeige gebracht und strafrechtlich verfolgt. Die alleinigen Rechte an der Software sowie an diesem Dokument liegen ausschließlich bei der OXID esales AG. Die in diesem Dokument bereit gestellten Informationen wurden nach aktuellem Stand der Technik verfasst. Die OXID esales AG übernimmt jedoch keine Haftung oder Garantie für die Aktualität, Richtigkeit und Vollständigkeit der bereit gestellten Informationen. Da sich Fehler, trotz aller Bemühungen nie vollständig vermeiden lassen, sind wir für Hinweise jederzeit dankbar. Konventionen In diesem Dokument werden die folgenden typographischen Konventionen verwendet: Grau hinterlegte Proportionalschrift Für Benutzereingaben, Quellcode und URLs Graue Kursivschrift Für Dateinamen und Pfade und sonstige kursive Auszeichnungen Fettschrift Für Eingabefelder und Navigationsschritte Fettschrift dunkelrot Für Warnungen und wichtige Hinweise Impressum OXID esales AG Bertoldstraße Freiburg Deutschland Fon: +49 (761) Fax: +49 (761) Vorstand: Roland Fesenmayr (Vorsitzender), Andrea Seeger Aufsichtsrat: Harald Fuchs (Vorsitzender) Sitz: Freiburg Amtsgericht Freiburg i. Brg. HRB /14

3 Inhaltsverzeichnis Copyright...2 Konventionen...2 Impressum...2 Inhaltsverzeichnis...3 Diese Installationsanleitung benutzen...4 Systemvoraussetzungen...4 Upgrade einer bereits bestehenden Heidelpay Installation Zahlungsarten konfigurieren Dateien kopieren Sicherheitseinstellungen vornehmen config.in.php bearbeiten cronjob-sicherheitspasswort eintragen Externen Transaktions Login eintragen SQL Befehle ausführen Modul eintragen Templates anpassen Cronjob einrichten Aufrufen des Cronjobs Aufrufen per URL Zeitraum einschränken Weitere Hinweise zur Arbeitsweise von "automatische Vorkasse" tmp-verzeichnis leeren Vollständige Installation prüfen Mit der Aktivierung des Moduls in OXID efire fortfahren Die Zahlungsarten den entsprechenden Benutzergruppen zur Verfügung stellen Integration des 3D Secure Logos Anhang 1: Beschreibung der zusätzlichen Templates Anzang 2: Einbindung anderer Zahlungsarten in den Bestellschritt3: (z.b. PayPal) /14

4 Diese Installationsanleitung benutzen Diese Installationsanleitung ist beschreibt die Neuinstallation des Heidelpay Moduls für die OXID eshop Enterprise Edition ab Version Installieren Sie diese Modulversion nicht, wenn Sie eine ältere Shopversion einsetzen! Melden Sie sich in diesem Fall bei unserem Support, um eine passende Modulversion zu erhalten. Befolgen Sie die Anleitung Schritt für Schritt. Für die Nutzung der Zahlungsart automatische Vorkasse über Heidelpay sind einige zusätzliche Installationsschritte nötig. Diese werden im Folgenden in den einzelnen Kapiteln gesondert gezeigt. Sofern Sie automatische Vorkasse nicht nutzen, überspringen Sie die jeweiligen Installationsschritte. Nach der Installation des Moduls kontrollieren Sie bitte mit Hilfe der am Ende dieser Anleitung stehenden Checkliste, ob alle Schritte durchgeführt wurden. Für weitere Fragen stehen wir Ihnen gerne zur Verfügung. Nutzen Sie dazu das Kontaktformular in OXID efire. Systemvoraussetzungen CURL-Modul für PHP Zend Optimizer Um die Systemvoraussetzungen zu prüfen, kopieren Sie die Datei check_sytem_requirements.php aus dem Installationspaket in das Hauptverzeichnis Ihres Shops (das Verzeichnis, in dem auch die Datei config.inc.php liegt) und rufen in Ihrem Browser folgende URL auf: Ersetzen Sie durch Ihre eigene Shop-Adresse. Ihnen wird dann angezeigt, ob die Systemvoraussetzungen erfüllt sind oder ob noch weitere Maßnahmen nötig sind. Upgrade einer bereits bestehenden Heidelpay Installation Sofern Sie eine bereits bestehende Installation des Heidelpay Moduls erstmals mit OXID efire verbinden möchten, setzen Sie sich bitte mit unserem Support in Verbindung. Nutzen Sie dazu das Kontaktformular in OXID efire. 4/14

5 1 Zahlungsarten konfigurieren Das efire Heidelpay Modul ermöglicht den Einsatz folgender Zahlungsarten: Kreditkarte, Bankeinzug, Debitkarte, automatische Vorkasse, Sofortüberweisung und ideal. Die Zahlungsarten, die über Heidelpay abgewickelt werden, sollen sollten während der Installation nur der Benutzergruppe Shop-Admin zur Verfügung stehen. Damit wird sichergestellt, dass normale Kunden während der Einrichtungsphase keine Bestellungen über diese Zahlungsarten vornehmen. Gehen Sie zu Shopeinstellungen => Zahlungsarten. Ordnen Sie den entsprechenden Zahlungsarten nur die Benutzergruppe Shop-Admin zu. Aktivieren Sie die Zahlungsarten, für die Sie mit Heidelpay einen Vertrag haben und richten Sie sie entsprechend ein. Wie Sie Zahlungsarten einrichten, erfahren Sie im eshop Handbuch auf der OXID esales Website. 2 Dateien kopieren Kopieren Sie mit einem FTP-Programm den Inhalt des Ordners copy_this aus dem Installationspaket in das Hauptverzeichnis Ihres Shops. In diesem Verzeichnis liegt auch die Datei config.inc.php. Sollten Sie die Zahlungsart "automatische Vorkasse" NICHT nutzen wollen, so entfernen Sie aus Sicherheitsgründen die beiden Dateien cron_heidelpay_pp.php und cron_heidelpay_pp.sh wieder aus dem Shopverzeichnis. Kopieren Sie alle Dateien unbedingt im binären Modus! 3 Sicherheitseinstellungen vornehmen 3.1 config.in.php bearbeiten Öffnen Sie die Datei config.inc.php mit einem Texteditor. Sie befindet sich im Hauptverzeichnis Ihres eshops. Fügen Sie folgenden Eintrag ganz ans Ende der config.inc.php hinzu: $this->atrustedips = array( " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", 5/14

6 ); " ", " ", " ", " ", Entfernen Sie den gegebenenfalls vorhandenen Eintrag $this->bldisablecookiecheck = 1; ersatzlos. Hinweis für Updatekunden: Sollten für Heidelpay bereits IP-Adressen eingetragen sein, so beachten Sie, das mit dieser Version sechs zusätzliche IP-Adressen (217...) hinzu gekommen sind. Diese müssen Sie somit nachtragen! 3.2 cronjob-sicherheitspasswort eintragen Dieses Kapitel ist ausschließlich relevant, falls Sie die Zahlungsart automatische Vorkasse verwenden $this->cfgheidelpay_saccesskey = "Sicherheitspasswort"; Ändern Sie das "Sicherheitspasswort" in ein nur Ihnen bekanntes sicheres Zugriffspasswort. Details zum Zweck des Passwortes finden Sie im Kapitel 8. 4 Externen Transaktions Login eintragen Loggen Sie sich in den Administrationsbereich des eshops ein. Gehen Sie zu OXID efire => Shop-Connector Tragen Sie Ihren Externern Transaktions Login und Externes Transaktions Passwort ein, falls noch nicht vorhanden. Aktivieren Sie die Einstellung Einstellungen für zukünftige Verbindungen zu OXID efire speichern. Klicken Sie auf Daten absenden. Der Login und das Passwort müssen der gleiche Login und das gleiche Passwort sein, die Sie in OXID efire unter Einstellungen => Zugangsdaten => Externer Transaktions Login vergeben haben. 5 SQL Befehle ausführen Als nächstes müssen Datenbankänderungen eingespielt werden. Diese befinden sich in der Datei install.sql. Hinweis für Updatekunden: Sollten Sie das Modul von einer älteren Version aktualisieren, so führen Sie statt der install.sql die update.sql aus! 6/14

7 Führen Sie diese Befehle auf der Datenbank ihres OXID eshops aus. Viele Provider stellen phpmyadmin zur Verfügung, um die Datenbank zu verwalten. In phpmyadmin können Sie die Import-Funktion benutzen, um die Befehle auszuführen. Folgender Hinweis ist ausschließlich relevant, falls Sie die Zahlungsart automatische Vorkasse verwenden Für die Zahlart automatische Vorkasse sind einige neue CMS-Texte nötig, die über die Datei install_vorkasse.sql in den Shop eingespielt werden müssen. 6 Modul eintragen Das Heidelpay Modul muss im OXID eshop registriert werden. Wanung: Falls Sie noch weitere Module in Ihrem OXID eshop einsetzen und nicht mit der Schreibweise in diesem Feld Installierte Module in Ihrem Shop vertraut sind, fragen Sie Ihren Partner oder den OXID esales Support, bevor Sie versehentlich ein bereits vorhandenes Modul deaktivieren. Fügen Sie folgende Zeilen im Administrationsbereich unter Stammdaten => Grundeinstellungen => System => Module in das Feld Installierte Module in Ihrem Shop hinzu: oxinputvalidator => efiheidelpay/core/d3_oxinputvalidator_heidelpay oxpaymentgateway => efiheidelpay/core/d3_oxpaymentgateway_heidelpay order => efiheidelpay/views/d3_order_heidelpay payment => efiheidelpay/views/d3_payment_heidelpay Wenn Sie die Klassen bereits mit einem Modul überladen haben erweitern Sie den Eintrag wie folgt: oxinputvalidator => mymodule/mymodule&efiheidelpay/core/d3_oxinputvalidator_heidelpay oxpaymentgateway => mymodule/mymodule&efiheidelpay/core/d3_oxpaymentgateway_heidelpay order => mymodule/mymodule&efiheidelpay/views/d3_order_heidelpay payment => mymodule/mymodule&efiheidelpay/views/d3_payment_heidelpay Folgender Hinweis ist ausschließlich relevant, falls Sie die Zahlungsart automatische Vorkasse verwenden Ergänzen Sie die Moduleinträge: oxinputvalidox => efiheidelpay/core/d3_ox _heidelpay oxorder => efiheidelpay/core/d3_oxorder_heidelpay 7/14

8 7 Templates anpassen Dieses Kapitel ist ausschließlich relevant, falls Sie die Zahlungsart automatische Vorkasse verwenden Im Verzeichnis changed_full finden Sie drei angepasste Shop-Templates. Diese zeigen dem Kunden die nötigen Überweisungsdaten im letzten Bestellschritt und der Bestellbestätigungsmail. Sollten Sie die Änderungen selbst in Ihre vorhandenen Templates einfügen wollen, so suchen Sie nach "INCLUDE DATA FOR HEIDELPAY PAYADVANCE" und kopieren den Bereich in Ihre Templates. Hinweis: In den beiden Bestellbestätigungsmail-Templates wurde zudem der alte Bereich zur Anzeige der Shop-Bankdaten deaktiviert. Er ist mit disabled markiert. 8 Cronjob einrichten Dieses Kapitel ist ausschließlich relevant, falls Sie die Zahlungsart automatische Vorkasse verwenden Für die Zahlungsart "automatische Vorkasse" ist die Einrichtung eines sog. Cronjobs nötig. Dieser sorgt dafür, dass täglich mehrmals ein Abgleich eingegangener Zahlungen zwischen Shop und Heidelpay erfolgt. Wir empfehlen das Starten des Jobs 2-3x pro Tag. z.b. vormittags, nachmittags und abends. Die Details zur Einrichtung von Cronjobs sind von Provider zu Provider unterschiedlich. Technische Nachfragen richten Sie bitte direkt an den Support Ihres Providers. 8.1 Aufrufen des Cronjobs Der Cronjob muss die Datei cron_heidelpay_pp.sh im Shop-Hauptverzeichnis aufrufen. Passen Sie die Datei bei Bedarf gemäß der Angaben Ihres Providers an. Die sh-datei bitte mit einem txt-editor öffnen und den Pfad zur startenden php-datei anpassen. Dazu ist der Bereich "/ihr/serverpfad/zum/shop/" mit dem absoluten Pfad zum Shop-Hauptverzeichnis zu tauschen. Hinweis: Dieser Pfad ist mit dem Inhalt der Variable $this->sshopdir in der config.inc.php des Shops identisch und kann von dort kopiert werden. Nach der Änderung des Pfads muss die Datei cron_heidelpay_pp.sh ins Hauptverzeichnis des Shops gelegt werden. 8.2 Aufrufen per URL Sollte Ihr Provider den Aufruf einer sh-datei per Cronjob nicht unterstützen, so können Sie alternativ die Datei cron_heidelpay_pp.php per URL im Cronjob aufrufen lassen: 8/14

9 Hier kommt nun das unter Kapitel cronjob-sicherheitspasswort vergebene Passwort ins Spiel. Ohne den richtigen "key" verweigert die php-datei ihre Arbeit. Hinweis: Sollten Sie den Aufruf wie unter 8.1 beschrieben per sh-datei durchführen, ist das Sicherheitspasswort in der config.inc.php trotzdem zu setzen. Damit wird ein Aufruf der Datei per Browser durch Dritte verhindert. 8.3 Zeitraum einschränken Der cronjob fragt jeweils für den aktuellen Tag etwaige Zahlungseingänge bei Heidelpay ab. Somit ist zwingend nötig, das der cronjob wirklich jeden Tag (mehrmals) aufgerufen wird. Sollten Sie trotzdem einmal ältere Eingänge erneut abrufen wollen, steht Ihnen ein weiterer Parameter date zur Verfügung. Die Syntax ist "YYYY-MM-DD" Der Aufruf per Browser: Bei Nutzung der.sh-datei ist der Parameter ebenfalls nutzbar. Die Art des Eintrags ist von Ihrem Provider abhängig. Nur für Nutzer der OXID eshop Enterprise Edition relevant Bei eventuell vorhandenen Subshops muss jeder Shop einzeln per Cronjob angesprochen werden. Hierzu können Sie einen Parameter shp nutzen. Beispiel &shp=1 für den ersten Shop im Mall-System. Wichtiger Sicherheitshinweis Ebenfalls sollten Sie unbedingt den Aufruf von.sh-dateien per Browser unterbinden. So das kein Dritter die Datei von außen aufrufen kann. Dazu können Sie z.b. die.htaccess Datei im Hauptverzeichnis um folgende Zeilen erweitern: <Files *.sh> order allow,deny deny from all </Files> 8.4 Weitere Hinweise zur Arbeitsweise von "automatische Vorkasse" Bei Nutzung der Zahlungsart prüft der o.g. Cronjob täglich eventuell vorhandene Zahlungseingänge bei Heidelpay. Sind diese vorhanden, werden sie mit den gespeicherten Bestellungen abgeglichen. Eine "Vorkasse"-Bestellung wird zum Zeitpunkt der Bestellung auf den Status "WAITING" für "warten" gestellt 9/14

10 (Datenfeld oxtransstatus). Wird einige Tage später eine korrekte Zahlung ermittelt, so wird dieser Wert auf "OK" geändert und das Feld oxpaid mit dem Zeitpunkt (Datum/Uhrzeit) der Bezahlung gefüllt. Weiterhin wird an den Kunden, sowie den Shopinhaber, eine Informations- über den Erhalt der Zahlung geschickt. Für die Formatierung der Mails stehen die Templates d3_ _hpppinfo_cust_*.tpl, sowie d3_ _hpppinfo_owner_*.tpl und die darin enthaltenen CMS-Texte (siehe Kapitel SQL-Befehle ausführen ) zur Verfügung. Hinweis: Sollte die Höhe der Zahlung NICHT dem Bestellwert entsprechen, werden folgende Schritte durchgeführt: Der Status der Bestellung wird auf "ERROR" gestellt (Datenfeld oxtransstatus) oxpaid wird nicht mit der Bezahlzeit gefüllt Dennoch werden o.g. s an Kunde und Shopinhaber gesandt. Die entsprechenden CMS-Texte enthalten jedoch einen zusätzlichen if-passus, der auf die fehlerhafte Zahlung hinweist. 9 /tmp-verzeichnis leeren Entfernen Sie zum Schluss alle Dateien aus dem Shopverzeichnis tmp, mit Ausnahme der.htaccess. 10 Vollständige Installation prüfen Überprüfen Sie, ob alle notwendigen Schritte durchgeführt worden sind: Die Systemvoraussetzungen wurden geprüft und sind erfüllt (Systemvoraussetzungen)? Die über Heidelpay abgewickelten Zahlungsarten wurden vorübergehend nur der Benutzergruppe Shop-Admin zugewiesen (Kapitel 1)? Die über Heidelpay abgewickelten Zahlungsarten sind aktiviert (Kapitel 1)? Die Dateien wurden im Binärmodus kopiert (Kapitel 2)? Die install.sql wurde in die OXID eshop-datenbank eingepflegt? (Kapitel 5)? Das Modul wurde im OXID eshop eingetragen (Kapitel 6)? Der Externe Transaktions Login ist in OXID efire eingetragen (Kapitel 4)? Wenn Sie alle Schritte durchgeführt haben, ist das Modul vollständig installiert. 11 Mit der Aktivierung des Moduls in OXID efire fortfahren Nachdem das Modul für den OXID eshop installiert ist, können Sie mit der Aktivierung von Heidelpay in OXID efire fortfahren. 10/14

11 12 Die Zahlungsarten den entsprechenden Benutzergruppen zur Verfügung stellen Wenn Sie die Aktivierung in OXID efire erfolgreich abgeschlossen haben, können Sie die über Heidelpay abzuwickelnden Zahlungsarten wieder Ihren Kunden zur Verfügung stellen. Passen Sie die Benutzergruppen-Zuordnungen der Zahlungsarten entsprechend an. 13 Integration des 3D Secure Logos Wenn Sie Visa und Mastercard mit 3D Secure anbieten sind Sie verpflichtet ein separates 3D Secure Logo zu führen. Die notwendigen Grafiken finden Sie unter: ml 11/14

12 Anhang 1: Beschreibung der zusätzlichen Templates payment_ext.tpl Dieses Template wird bei Aktivierung des Heidelpay-Moduls anstatt der originalen payment.tpl genutzt und beinhaltet einige technische Änderungen gegenüber dem Original. Es zeigt ansonsten dieselbe Optik wie payment.tpl. Warum Dann ein neues Template? Die ursprüngliche payment.tpl nutzt ein großes Formular mit allen Zahlungsarten zur Auswahl. Da jedoch einige Heidelpayzahltypen eigene Formulare benötigen (die als "action" auf den Heidelpayserver zeigen), muss ein eigenes Template genutzt werden. Dies ist wichtig, damit Kreditkartendaten nicht von Ihrem Server verarbeitet werden. Sollten Sie bereits den normalen Bestellschritt3 payment.tpl Ihres Shops angepasst haben, so empfiehlt es sich diese in die payment_ext.tpl nachzuziehen. payment_ext_inc.tpl Definiert die hidden-felder für die Übertragung an den Heidelpay-Server in Schritt 3. Optische Anpassungen sind nur ggf. im noscript-bereich nötig. payment_ext_afterstep4_info.tpl Wenn die Option "Eingabe Kreditkartendaten nach Schritt 4" aktiviert ist, wird in der payment_ext.tpl anstatt der Eingabefelder an "Kreditkarte" oder "Debitkarte" eine Info eingeblendet, dass der Konsument seine Kartendaten erst nach Schritt4 eingeben muss. Diese Info wird von diesem Template bereitgestellt. payment_ext_otpay.tpl Liefert die speziellen Eingabefelder für die beiden neuen Onlinetransfer-Zahlungsarten Sofortüberweisung und ideal. payment_ext_storeduid.tpl Liefert den speziellen Bereich für Bestandskunden: "Möchten Sie mit den vorliegenden Kartendaten erneut bestellen?" /inc/steps_item_ext.tpl Wird von der payment_ext.tpl anstatt der originalen steps_item.tpl genutzt. Der einzige Unterschied besteht in einer technischen Änderung de <a>-tags der "Schritt4"-Box. 12/14

13 Die folgenden Templates werden ausschließlich bei "Eingabe Kreditkartendaten nach Schritt 4" oder im Falle einer 3DSecure-Kreditkarte (3DS) genutzt: heidelpay_order_3ds.tpl Wird bei einer 3DS-Karte nach Schritt4 gezeigt, um die 3DS-Code-Eingabe dem Kunden auszugeben. heidelpay_cc_input.tpl Template für den Fall "Eingabe Kreditkartendaten nach Schritt 4" heidelpay_order_3ds_iframe.tpl Erstellt die iframe-seite für 3D-Secure-Kartenzahlung d3_ _hpppinfo...tpl Diese Templates werden für die Information des Kunden und des Shopinhabers über erfolgte Zahleingänge für "automatische Vorkasse" genutzt. Der Inhalt kann über mehrere CMS-Texte gesteuert werden. Zu finden im Admin-CMS-Bereich, Idents d3_hp_vorkass /14

14 Anzang 2: Einbindung anderer Zahlungsarten in den Bestellschritt3: (z.b. PayPal) Da mit der Nutzung von Heidelpay eine eigene payment_ext.tpl verwendet wird (siehe Erklärung unter "Beschreibung der Templates"), müssen dort auch ggf. andere Zahlungsarten anstatt in die payment.tpl eingebunden werden. Der Einbau erfolgt leicht modifiziert, als im Original. Hier ein Beispiel für die Zahlungsart "PayPal": <!-- Paypal payment start --> [{elseif $spaymentid == "oxidpaypal"}] [{include file="payment_ext_inc.tpl" payment=$paymentmethod}] <tr onclick="selectpayment([{$inptcounter}]);"> <td><input id="test_payment_[{$spaymentid}]" type="radio" name="paymentid" value="[{$spaymentid}]" [{if $oview->getcheckedpaymentid() == $paymentmethod->oxpayments oxid->value}]checked[{/if}]></td> <td>[{ $paymentmethod->oxpayments oxdesc->value}] [{ if $paymentmethod->faddpaymentsum }]([{ $paymentmethod->faddpaymentsum }] [{ $currency->sign}])[{/if}] <a href="#" onclick="javascript:window.open(' location=no, directories=no, status=no, menubar=no, scrollbars=yes, resizable=yes, width=400, height=350');"><img src="[{$oviewconf->getimageurl()}]/paypallockbox_80x35.gif" border="0" alt="paypal-bezahlmethoden-logo" /></a> </td> </tr> [{include file="payment_ext_inc.tpl" blshownoscript=1}] [{if $inptcounter > -1 }]</form>[{/if}] <!-- Paypal payment end --> Direkt nach dem "elseif" muss ein include auf die payment_ext_inc.tpl durchgeführt werden, um das <form> für die Zahlungsart zu erstellen. Danach folgt der gewöhnliche html-code der Zahlungsart. Hierbei ist nur zu beachten, dass der <tr>-tag ein 'onclick="selectpayment([{$inptcounter}]);" erhält. Vor dem Ende der aktuellen Zahlungsart kommt noch ein weiteres include und ein schließendes </form> wie im Beispiel gezeigt. 14/14