Zum Inhalt

JTL-Shop 5 Integration

Nehmen Sie Online-Zahlungen in JTL-Shop 5 mit dem SecPaid Payment Plugin entgegen. Diese Anleitung richtet sich an Shop-Betreiber und Integratoren ohne Vorkenntnisse in JTL oder SecPaid.

Übersicht

System Rolle
JTL-Shop Ihr Onlineshop — Produkte, Checkout, Bestellungen
SecPaid Zahlungsanbieter — Kunde zahlt auf der SecPaid-Seite
SecPaid Payment Plugin Verbindet beide Systeme — Weiterleitung, Webhooks, Bestellstatus

Das Plugin wird von SPACEPITCH gepflegt und unterstützt JTL-Shop 5.2.0+ (Plugin v3.0.0+).

Download

Plugin ab GitHub Releases herunterladen (SecPaidPayment-3.0.0.zip).

So funktioniert die Zahlung

sequenceDiagram
    participant Kunde
    participant JTL as JTL-Shop
    participant SecPaid

    Kunde->>JTL: Checkout — SecPaid wählen
    JTL->>JTL: Bestellung anlegen (unbezahlt)
    JTL->>SecPaid: createLink API
    JTL->>Kunde: Weiterleitung zu SecPaid
    Kunde->>SecPaid: Zahlung abschließen
    SecPaid->>JTL: Webhook POST /secpaid/webhook
    JTL->>JTL: Bestellung als bezahlt markieren
    SecPaid->>Kunde: Redirect /secpaid/callback
    Kunde->>JTL: Bestellbestätigungsseite

Callback vs. Webhook

Entspricht dem Muster in Webhooks & Callbacks:

URL Typ Zweck
https://IHR-SHOP/secpaid/callback Browser-Redirect Kunde zur Bestellbestätigung leiten
https://IHR-SHOP/secpaid/webhook Server-POST Verbindliche Zahlungsbestätigung

Webhook nicht weglassen

Der Callback verbessert nur die Kundenerfahrung. Die Bestellabwicklung muss auf dem Webhook basieren — das Plugin markiert Bestellungen als bezahlt, wenn der Webhook eintrifft.

Voraussetzungen

  • JTL-Shop 5.2.0+
  • PHP 8.0+ mit cURL
  • Gültiges HTTPS auf Ihrer Shop-Domain
  • Shop aus dem Internet erreichbar (SecPaid muss Webhooks senden können)
  • SecPaid-Konto (Sandbox und/oder Produktion)

Schritt 1 — Plugin installieren

  1. SecPaidPayment-3.0.0.zip von GitHub Releases laden
  2. Ordner SecPaidPayment nach shop/plugins/SecPaidPayment/ entpacken
  3. JTL-Admin: Plugins → Plugin-Verwaltung
  4. SecPaid Payment installieren oder aktualisieren (Datenbank-Migration läuft automatisch)

Schritt 2 — JTL-Shop konfigurieren

Zahlungsart-Einstellungen

  1. Administration → Zahlungsarten
  2. SecPaid Payment öffnen
  3. Einstellungen:
Einstellung Beschreibung
API Key SecPaid API-Token (Authentifizierung)
Environment Sandbox → app.dev.secpaid.com · Production → app.secpaid.com
  1. Speichern und Zahlungsart für Kundengruppen aktivieren

Integrations-URLs kopieren

Plugins → SecPaid Payment → SecPaid Status öffnen und kopieren:

Bezeichnung Beispiel
Callback URL https://shop.beispiel.de/secpaid/callback
Webhook URL https://shop.beispiel.de/secpaid/webhook

Diese URLs im SecPaid-Konto eintragen (nächster Schritt).

Schritt 3 — SecPaid konfigurieren

Anmeldung im SecPaid-Dashboard:

Integrations-URLs

SecPaid-Einstellung Wert
Callback URL https://IHRE-SHOP-DOMAIN/secpaid/callback
Webhook URL / Payment endpoint https://IHRE-SHOP-DOMAIN/secpaid/webhook

Domain muss übereinstimmen

Die Domain muss der JTL Shop-URL entsprechen. Nur HTTPS verwenden.

API-Key

API-Token in SecPaid erstellen und in JTL unter Zahlungsarten → SecPaid Payment → API Key eintragen.

Bei Sandbox-Umgebung einen Sandbox-Token verwenden.

Schritt 4 — Sandbox testen

Fertiger Demo-Shop

Ein JTL-Shop 5 Test-Shop mit vorinstalliertem SecPaid Payment Plugin steht unter jtl.dev.secpaid.com bereit. Damit können Sie den Checkout- und Webhook-Ablauf gegen die SecPaid-Sandbox ausprobieren, bevor Sie das Plugin in Ihrem eigenen Shop installieren.

  1. JTL Environment auf Sandbox stellen
  2. Testbestellung mit SecPaid Payment aufgeben
  3. Zahlung auf app.dev.secpaid.com abschließen
  4. Prüfen:
Prüfung Erwartet
Kunden-Redirect JTL Bestellabschluss
JTL-Admin → Bestellungen Status bezahlt
SecPaid-Dashboard Zahlung erfolgreich

Live-Gang Checkliste

  • JTL Environment auf Production
  • Produktions-API-Key in SecPaid und JTL
  • Callback- und Webhook-URLs auf Produktions-Domain
  • Gültiges SSL-Zertifikat
  • Eine echte Testbestellung
  • JTL-Wawi-Sync prüfen falls vorhanden

Fehlerbehebung

Kunde landet im Warenkorb mit Zahlungsfehler

Ursache Lösung
Callback URL fehlt in SecPaid /secpaid/callback eintragen
Falsche Shop-URL in JTL Globale Shop-URL korrigieren
Plugin älter als v3.0.0 Upgrade — v3 behebt HTML-kodierte Callback-Parameter

Bestellung bleibt unbezahlt

Ursache Lösung
Webhook URL fehlt https://IHR-SHOP/secpaid/webhook in SecPaid setzen
POST blockiert Firewall/Ingress für /secpaid/webhook öffnen
Falscher API-Key Sandbox/Produktion mit Environment abgleichen

Zahlungsart nicht im Checkout sichtbar

  • Plugin in Plugin-Verwaltung aktivieren
  • API-Key in Zahlungsarten prüfen
  • Sichtbarkeit nach Kundengruppe / Versandart prüfen

Technische Referenz

Thema Detail
Plugin-Repository SPACEPITCH/SP-JTL-Plugin
Ausführliche Anleitung Docs im Plugin-Repo
PostOrder-Modus Bestellung vor Redirect angelegt
Wawi-Sync JTL addIncomingPayment() + setOrderStatusToPaid()

Support