Wichtige Hinweise

Kundenservice und Support

Bei Fragen oder Problemen stehen Ihnen wir Ihnen gern als Ansprechpartner zur Verfügung!

secupay AG
Support/HelpDesk

Telefon +49 (0)35955 7550-0

E-Mail info@secupay.com

Unsere Servicezeiten: Montag bis Freitag 9:00 bis 17:00 Uhr

Sicherheitshinweise

Hinweise zur Inbetriebnahme

Hinweise zum Update älterer Versionen

Wenn Sie eine Plugin-Version älter als 5.0.6 installiert hatten, beachten Sie bitte folgende Hinweise:

Software License

The MIT license

Copyright (c) 2022 - 2024 secupay AG, Pulsnitz, Germany

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Installation des Plugins

Systemvoraussetzungen

Das Plugin in Version 7.1.1 unterstützt:

• JTL Shop 5.1.1 - 5.4.0
• PHP 8.0 - 8.4
• JTL Wawi 1.8 - 1.9 (grundsätzlich sollten auch ältere Wawi-Versionen ab 1.5 funktionieren)

Weitere Informationen s. Release Notes für secupay Payments for JTL Shop 5

Installation über den JTL Extension Store

Sie können secupay Payments für JTL Shop 5 über den JTL Extension Store installieren und aktuell halten. Voraussetzung ist lediglich, dass Sie Ihren Shop im JTL Extension Store registriert haben.

Direktlink: https://www.jtl-software.de/extension-store/secupay-payments-jtl-shop-5

Unser Plugin ist für Sie kostenfrei installierbar:

Zur Inbetriebnahme benötigen Sie weiterhin Anmeldedaten für unseren Server. Diese erhalten Sie von unserem Kundendienst bei Ihrer Registrierung.

Installation per ZIP-Datei

Bei Ihrer Registrierung erhalten Sie eine ZIP-Datei mit einem vorkonfigurierten Plugin.

Speichern Sie die erhaltene ZIP-Datei lokal auf Ihrem PC. Melden Sie sich am JTL-Backend (Shop-Admin) an und navigieren Sie zu „Plugins“ » „Plugin-Manager“. Klicken Sie dort auf den Button „Upload“ und wählen Sie die gespeicherte ZIP-Datei auf Ihrem PC aus und laden diese hoch:

Es erscheint eine Meldung „Plugin erfolgreich hochgeladen“.

Im Anschluss gehen Sie zum Tab „Vorhanden“ und wählen dort das Plugin „secupay Payments“ aus. Klicken Sie nun den Button „Installieren“:

Dabei werden Sie zur Bestätigung der Lizenz aufgefordert. Unser Plugin wird wie JTL Shop 5 selbst unter der MIT-Lizenz veröffentlicht.

Nachdem das Plug-in installiert wurde, finden Sie es im Tab „Aktiviert“ wieder:

Damit ist das Plugin installiert und aktiv.

Für die Annahme von Zahlungen und für das Zusammenspiel mit der JTL Wawi sind nun einige Einstellungen erforderlich.

Update des Plugins

Updates werden Ihnen automatisch im Plugin-Manager von JTL Shop 5 angeboten.

Zum Update des per ZIP-Datei installierten Plugins gehen Sie genauso vor wie bei der Installation per ZIP-Datei.

Konfiguration des Plugins in JTL Shop

Verbindung und weitere allgemeine Einstellungen

Für den Betrieb muss das Plugin sich an der secuconnect API mit Anmeldedaten (Client ID, Client Secret) und Vertrags-ID authentifizieren. Diese Einstellungen sind für den Betrieb notwendig.

Sie finden diese Einstellungen im Shop-Admin unter Plugins » Installierte Plugins » secupay Payments (oder alternativ: Plugins » Plugin-Manager » Einstellungen (Zahnrad-Symbol) bei secupay Payments » Einstellungen):

Weiterhin haben Sie hier die Möglichkeit eine Kurzform für den Shopnamen festzulegen. Er wird für den Verwendungszweck genutzt.

Ihre Einstellungen werden mit den Klick auf Speichern übernommen.

Zahlungsarten aktivieren und einrichten

Bei JTL Shop werden die Zahlungsarten pro Versandart aktiviert. Sobald eine Zahlungsart einer Versandart zugeordnet wurde, ist sie für diese aktiv.

Sie finden diese Einstellung unter Administration » Versand » Versandarten:

Anschließend können Sie im Bereich Zahlungsarten die Zahlungsarten von secupay aktivieren. Betätigen Sie wiederum Speichern, um die Änderungen zu übernehmen.

Für jede Zahlungsart sind weitere Einstellungen möglich. Sie finde diese unter Administration » Zahlungsarten » Bearbeiten (Notizblock-Symbol):

Hier können Sie Texte und Bedingungen für die Zahlungsart einstellen:

Die meisten Einstellungen sind für alle Zahlungsarten gleich. Besonders sind u. a. die Farbe des Google Pay Buttons (Empfehlung: schwarz für helle Hintergründe, weiß für dunkle Hintergründe), die Variante des Kreditkartenformulars und ein abweichender Verwendungszweck bei Lastschriftzahlungen.

Vergessen Sie wiederum nicht, Ihre Änderungen mit Klick auf Speichern zu übernehmen.

E-Mails und Dialogtexte anpassen (optional)

Die Texte der E-Mails und die meisten Texte im Kundendialog können von Ihnen angepasst und auch wieder auf den ursprünglichen Zustand zurückgesetzt werden.

Die Einstellungen für die E-Mails finden Sie unter Administration » E-Mail » Vorlagen:

Die Einstellungen für die Dialogtexte finden Sie unter Plugins » Plugin-Manager » Sprachvariablen bearbeiten (Notizbock-Symbol) bei secupay Payments:

Die Einstellungen sind für erfahrene Benutzer jeweils selbsterklärend.

Vergessen Sie wiederum nicht, Ihre Änderungen mit Klick auf Speichern zu übernehmen.

Konfiguration der JTL Wawi

Folgende Einstellungen sind für einen ordnungsgemäßen Betrieb notwendig:

• Zahlungsarten in Wawi einrichten
• Zahlungsinformationen auf Rechnung darstellen (nur Rechnungskauf)

Für vollständig integrierte Abläufe sind weiterhin sinnvoll, aber optional:

• Auftragsattribute für Transaktions-IDs
• Workflows für automatische Liefermeldung, Übertragung der Rechnungsnummer, Betragsanpassung, Storno oder Erstattung

Zahlungsarten einrichten

Für die korrekte Anzeige und Funktion der Zahlungsarten müssen diese in der Wawi angelegt sein. Die Schreibweise muss mit der in JTL Shop exakt übereinstimmen. Für Tests über die Sandbox bzw. mit Demo-Transaktionen muss ergänzend eine Zahlungsart wie „Kreditkarte (Test oder Demo Transaktion)“ angelegt sein. Bei Rechnungskauf muss die Option Auslieferung vor Zahlungseingang möglich angewählt sein.

Schritt-für-Schritt-Anleitung:

1. Öffnen Sie den Dialog Zahlungen » Zahlungsarten.
2. Für jede Zahlungsart im JTL Shop legen Sie eine entsprechend Zahlungsart in der Wawi an:
   • bei Drucktexte » Deutsch » Name: Schreibweise wie in Shop, z. B. „Kreditkarte“
   • bei Drucktexte » Englisch » Name: Schreibweise wie in Shop, z. B. „Credit card“
   • nur Rechnungskauf: Option Auslieferung vor Zahlungseingang möglich anhaken
3. Auch für jede Test-Zahlungsart im JTL Shop legen Sie eine entsprechende Zahlungsart in der Wawi an:
   • bei Drucktexte » Deutsch » Name: Schreibweise z. B. „Kreditkarte (Test oder Demo Transaktion)“
   • bei Drucktexte » Englisch » Name: Schreibweise z. B. „Credit card (Test oder Demo Transaktion)“
   • nur Rechnungskauf: Option Auslieferung vor Zahlungseingang möglich anhaken
4. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Zahlungsinformationen auf Rechnung darstellen (nur Rechnungskauf)

Zum Darstellen der Zahlungsinformationen auf der Rechnung muss das Feld Zahlungsinfo im Layout für den Rechnungsdruck eingefügt werden. Weiterhin muss der Shop so konfiguriert sein, dass die Zahlungsinformationen im Feld Zahlungsinfo erscheinen und nicht im Kundenkommentar.

Schritt-für-Schritt-Anleitung:

1. Wählen Sie in JTL Shop unter Zahlungsarten » Rechnungskauf secupay AG bei Feld Zahlungsdaten die Option Rechungskauf-Text. (Wird bald obsolet.)
2. Öffnen Sie in der JTL Wawi den Layout-Editor über den Menüpunkt Admin » Druck- / E-Mail- /Exportvorlagen.
3. Wählen Sie das Vorlagenset für Rechnungen: Root » Beleg Verkauf » Rechnung usw.
4. Klicken Sie Bearbeiten…, um den Vorlageneditor zu öffnen.
5. Fügen Sie unten einen Absatz mit folgendem Datenobjekt hinzu: „Vorgang.Auftrag.Rechnungskauftext“
6. Abschließend übernehmen Sie mit Datei » Speichern ihre Änderungen.

Auftragsattribute für Transaktions-IDs (optional)

Mit den Auftragsattributen können Sie die Transaktions-IDs von secupay am Auftrag einsehen. Weiterhin werden diese IDs als Parameter für automatisierte Workflows genutzt, und sind damit Voraussetzung für deren Einrichtung.

Schritt-für-Schritt-Anleitung:

1. Öffnen Sie den Dialog über den Menüpunkt Admin » Eigene Felder.
2. Wählen Sie links oben den Bereich Angebot/Auftrag/Abonnements.
3. Legen Sie eine Gruppe secupay an. Klicken Sie dazu auf die Schaltfläche Gruppe anlegen und tragen Sie als Namen „secupay“ ein.
4. Legen Sie ein Kurztext-Feld secupay_trans_id an. Wählen Sie dazu die neue Gruppe secupay aus und klicken Sie auf die Schaltfläche Feld anlegen. Tragen Sie als Namen „secupay_trans_id“ ein und wählen Sie den Datentyp Kurztext.
5. Legen Sie ein Kurztext-Feld secupay_pci an. Wählen Sie dazu die neue Gruppe secupay aus und klicken Sie auf die Schaltfläche Feld anlegen. Tragen Sie den Namen „secupay_pci“ ein und wählen Sie wiederum den Datentyp Kurztext.
6. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Workflow-Grundlagen (optional)

Damit Liefermeldungen, die Übertragung der Rechnungsnummern, Betragsanpassungen, Stornos oder Erstattungen automatisch erfolgen, müssen Workflows eingerichtet werden. Falls Sie bisher nicht mit Workflows gearbeitet haben, gibt es hier weitere Informationen und eine Anleitung: https://guide.jtl-software.de/jtl-wawi/jtl-workflows/

Die Workflows senden Web-Requests an das secupay-Plugin im JTL Shop. Zur Sicherheit wird ein individueller Zugriffsschlüssel (Parameter accesskey) übergeben, der bei der Plugin-Installation erzeugt wird.

Die Workflows verwalten sie im Workflow-Dialog, den sie über den Menüpunkt Admin » JTL-Workflows erreichen:

Workflow für Versandmeldung (optional)

Die Versandmeldung ist notwendig, damit Rechnungskauf-Transaktionen fällig werden. Mit diesem Workflow automatisieren Sie die Versandmeldung.

1. Öffnen Sie den Workflow-Dialog über den Menüpunkt Admin » JTL-Workflows.
2. Klicken Sie im Workflow-Dialog auf den Reiter Aufträge.
3. Navigieren Sie nun auf der linken Seite Seite unter Auslösende Ereignisse zu Auftrag » Ausgeliefert.
4. Legen Sie das neue Ereignis an, indem Sie auf den Button Workflow anlegen klicken.
5. Vergeben Sie für den neuen Workflow einen aussagekräftigen Namen, z.B. „Versand melden (secupay)“.
6. Als Aktion wählen Sie Web-Request aus.
7. Tragen Sie diese Request-Details ein:
   • Method: POST
   • URL: https://83.sm.secuconnect.com/testing/JTL/5.4/secupay_update
   • Header: Content-Type:application/x-www-form-urlencoded
8. Tragen Sie den Request-Body ein. Klicken Sie dazu hinter dem Feld Body auf den Button mit den drei Punkten. Kopieren Sie den untenstehenden Code und fügen Sie diesen in das Feld ein.
9. Setzen Sie einen Haken bei Bei Fehler Workflow abbrechen.
10. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Workflow für Rechnungsnummer (optional)

Bei Rückfragen eines Käufers by secupay kann eine aktuelle Rechnungsnummer hilfreich sein. Mit diesem Workflow automatisieren Sie die Hinterlegung dieser Daten.

1. Öffnen Sie den Workflow-Dialog über den Menüpunkt Admin » JTL-Workflows.
2. Klicken Sie im Workflow-Dialog auf den Reiter Versand.
3. Navigieren Sie nun auf der linken Seite Seite unter Auslösende Ereignisse zu Lieferscheine » Versendet.
4. Legen Sie das neue Ereignis an, indem Sie auf den Button Workflow anlegen klicken.
5. Vergeben Sie für den neuen Workflow einen aussagekräftigen Namen, z.B. „Rechnungsnummer übermitteln (secupay)“.
6. Als Aktion wählen Sie Web-Request aus.
7. Tragen Sie diese Request-Details ein:
   • Method: POST
   • URL: https://83.sm.secuconnect.com/testing/JTL/5.4/secupay_update
   • Header: Content-Type:application/x-www-form-urlencoded
8. Tragen Sie den Request-Body ein. Klicken Sie dazu hinter dem Feld Body auf den Button mit den drei Punkten. Kopieren Sie den untenstehenden Code und fügen Sie diesen in das Feld ein.
9. Setzen Sie einen Haken bei Bei Fehler Workflow abbrechen.
10. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Workflow bei Auftragsänderung (optional)

Mit einer Änderung des Auftrags muss häfig ein Teilstorno bzw. eine Teilerstattung der Zahlung einhergehen. Mit diesem Workflow automatisieren Sie diesen Vorgang.

1. Öffnen Sie den Workflow-Dialog über den Menüpunkt Admin » JTL-Workflows.
2. Klicken Sie im Workflow-Dialog auf den Reiter Aufträge.
3. Navigieren Sie nun auf der linken Seite Seite unter Auslösende Ereignisse zu Auftrag » Geändert.
4. Legen Sie das neue Ereignis an, indem Sie auf den Button Workflow anlegen klicken.
5. Vergeben Sie für den neuen Workflow einen aussagekräftigen Namen, z.B. „Betragsanpassung (secupay)“.
6. Als Aktion wählen Sie Web-Request aus.
7. Tragen Sie diese Request-Details ein:
   • Method: POST
   • URL: https://83.sm.secuconnect.com/testing/JTL/5.4/secupay_update
   • Header: Content-Type:application/x-www-form-urlencoded
8. Tragen Sie den Request-Body ein. Klicken Sie dazu hinter dem Feld Body auf den Button mit den drei Punkten. Kopieren Sie den untenstehenden Code und fügen Sie diesen in das Feld ein.
9. Setzen Sie einen Haken bei Bei Fehler Workflow abbrechen.
10. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Workflow bei Auftragsstorno (optional)

Mit einem Auftragsstorno muss ein Storno bzw. die Erstattung der Zahlung einhergehen. Mit diesem Workflow automatisieren Sie diesen Vorgang.

1. Öffnen Sie den Workflow-Dialog über den Menüpunkt Admin » JTL-Workflows.
2. Klicken Sie im Workflow-Dialog auf den Reiter Aufträge.
3. Navigieren Sie nun auf der linken Seite Seite unter Auslösende Ereignisse zu Auftrag » Storniert.
4. Legen Sie das neue Ereignis an, indem Sie auf den Button Workflow anlegen klicken.
5. Vergeben Sie für den neuen Workflow einen aussagekräftigen Namen, z.B. „Zahlung stornieren (secupay)“.
6. Als Aktion wählen Sie Web-Request aus.
7. Tragen Sie diese Request-Details ein:
   • Method: POST
   • URL: https://83.sm.secuconnect.com/testing/JTL/5.4/secupay_update
   • Header: Content-Type:application/x-www-form-urlencoded
8. Tragen Sie den Request-Body ein. Klicken Sie dazu hinter dem Feld Body auf den Button mit den drei Punkten. Kopieren Sie den untenstehenden Code und fügen Sie diesen in das Feld ein.
9. Setzen Sie einen Haken bei Bei Fehler Workflow abbrechen.
10. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Workflow bei Rechnungskorrektur (optional)

Mit einer Rechnungskorrektur muss ein teilweises oder komplettes Storno bzw. eine Erstattung der Zahlung einhergehen. Mit diesem Workflow automatisieren Sie diesen Vorgang.

1. Öffnen Sie den Workflow-Dialog über den Menüpunkt Admin » JTL-Workflows.
2. Klicken Sie im Workflow-Dialog auf den Reiter Rechnungen.
3. Navigieren Sie nun auf der linken Seite Seite unter Auslösende Ereignisse zu Rechnungskorrektur » Erstellt / Festgeschrieben.
4. Legen Sie das neue Ereignis an, indem Sie auf den Button Workflow anlegen klicken.
5. Vergeben Sie für den neuen Workflow einen aussagekräftigen Namen, z.B. „Zahlung erstatten (secupay)“.
6. Als Aktion wählen Sie Web-Request aus.
7. Tragen Sie diese Request-Details ein:
   • Method: POST
   • URL: https://83.sm.secuconnect.com/testing/JTL/5.4/secupay_update
   • Header: Content-Type:application/x-www-form-urlencoded
8. Tragen Sie den Request-Body ein. Klicken Sie dazu hinter dem Feld Body auf den Button mit den drei Punkten. Kopieren Sie den untenstehenden Code und fügen Sie diesen in das Feld ein.
9. Setzen Sie einen Haken bei Bei Fehler Workflow abbrechen.
10. Abschließend übernehmen Sie mit Speichern die neuen Einstellungen.

Problemlösung

Probleme beim Update

Sollte das Update aus irgendeinem Grund scheitern, können Sie das Plugin deinstallieren und erneut installieren.

Gehen Sie im Plugin-Manager zum Tab Aktiviert. Dort wählen Sie das Plugin („secupay Payments“) aus. Anschließend klicken Sie den Button „Deinstallieren“:

Falls das Plugin bereits deaktiviert ist, können Sie den gleichen Vorgang im Tab „Deaktiviert“ ausführen.

Egal welchen Ausgangspunkt Sie genommen haben, erscheint nun ein Dialog. Wählen Sie bitte weder das Löschen der Datenbanktabellen noch der Dateien, die zum Plugin gehören. Klicken Sie anschließend auf den Button „Plugin mit den gewählten Einstellungen deinstallieren“:

Anschließend sollte Ihnen die Deinstallation des Plugins bestätigt werden.

Nun können Sie das Plugin in der gewünschten Version neu installieren.

Zahlungsarten nach Update nicht mehr in Wawi findbar

Beim Update von einer Plugin-Version kleiner 5.0.6 muss in der JTL Wawi aus den Namen der Zahlungsarten „secupay AG“ entfernt werden. Die Voreinstellung können Sie den Zahlungsarten im Administrations-Backend von JTL Shop 5 entnehmen.

Die Zahlungsarten lauten nun per Standard: Kreditkarte, Lastschrift, Rechnungskauf, Vorkasse, PayPal, Sofort

Englische Übersetzung: Credit Card, Direct Debit, Invoice, Advance Payment, PayPal, Sofort