Skip to content

JTL-Shop 5 Integration

Accept online payments in JTL-Shop 5 using the official SecPaid Payment plugin. This guide is for shop owners and integrators who are new to JTL or SecPaid.

Overview

System Role
JTL-Shop Your online store — products, checkout, orders
SecPaid Payment provider — customer pays on a SecPaid-hosted page
SecPaid Payment plugin Connects both systems — redirect, webhooks, order status

The plugin is maintained by SPACEPITCH and supports JTL-Shop 5.2.0+ (plugin v3.0.0+).

Download

Get the plugin from GitHub Releases (SecPaidPayment-3.0.0.zip).

How payment works

sequenceDiagram
    participant Customer
    participant JTL as JTL-Shop
    participant SecPaid

    Customer->>JTL: Checkout — select SecPaid
    JTL->>JTL: Create order (unpaid)
    JTL->>SecPaid: createLink API
    JTL->>Customer: Redirect to SecPaid
    Customer->>SecPaid: Pay
    SecPaid->>JTL: Webhook POST /secpaid/webhook
    JTL->>JTL: Mark order paid
    SecPaid->>Customer: Redirect /secpaid/callback
    Customer->>JTL: Order confirmation page

Callback vs webhook

This follows the same pattern described in Webhooks & Callbacks:

URL Type Purpose
https://YOUR-SHOP/secpaid/callback Browser redirect Send customer to order confirmation
https://YOUR-SHOP/secpaid/webhook Server POST Authoritative payment confirmation

Never skip the webhook

The callback only improves customer experience. Order fulfillment must rely on the webhook — the plugin marks orders paid when the webhook is received.

Requirements

  • JTL-Shop 5.2.0+
  • PHP 8.0+ with cURL
  • Valid HTTPS on your shop domain
  • Shop reachable from the internet (SecPaid must POST webhooks)
  • SecPaid account (sandbox and/or production)

Step 1 — Install the plugin

  1. Download SecPaidPayment-3.0.0.zip from GitHub Releases
  2. Extract the SecPaidPayment folder to: 
    shop/plugins/SecPaidPayment/
  3. In JTL admin: Plugins → Plugin-Verwaltung
  4. Install or upgrade SecPaid Payment (runs database migration automatically)

Step 2 — Configure JTL-Shop

Payment method settings

  1. Go to Administration → Zahlungsarten
  2. Open SecPaid Payment
  3. Configure:
Setting Description
API Key Your SecPaid API token (Authentication)
Environment Sandbox → app.dev.secpaid.com · Production → app.secpaid.com
  1. Save and activate the payment method for your customer groups

Copy integration URLs

Open Plugins → SecPaid Payment → SecPaid Status. Copy:

Label Example
Callback URL https://shop.example.com/secpaid/callback
Webhook URL https://shop.example.com/secpaid/webhook

Use these exact URLs in your SecPaid account (next step).

Step 3 — Configure SecPaid

Log in to the SecPaid dashboard:

Integration URLs

SecPaid setting Value
Callback URL https://YOUR-SHOP-DOMAIN/secpaid/callback
Webhook URL / Payment endpoint https://YOUR-SHOP-DOMAIN/secpaid/webhook

Domain must match

The shop domain must match JTL global settings (Shop-URL). Use HTTPS only.

API key

Create or copy an API token in SecPaid and paste it into JTL Zahlungsarten → SecPaid Payment → API Key.

Use a sandbox token when Environment is set to Sandbox.

Step 4 — Test in sandbox

Ready-to-use demo store

A JTL-Shop 5 test store with the SecPaid Payment plugin pre-installed is available at jtl.dev.secpaid.com. Use it to try the checkout and webhook flow against the SecPaid sandbox before installing the plugin on your own shop.

  1. Set JTL Environment to Sandbox
  2. Place a test order and select SecPaid Payment
  3. Complete payment on app.dev.secpaid.com
  4. Verify:
Check Expected
Customer redirect JTL order confirmation (Bestellabschluss)
JTL admin → Orders Status paid / bezahlt
SecPaid dashboard Payment successful

Quick endpoint test

curl -X POST "https://YOUR-SHOP/secpaid/webhook" \
  -H "Content-Type: application/json" \
  -d '{"pay_id":"test","status":"success","ResponseCode":1}'

Expected response: {"success":true} (no order updated for fake pay_id — that is normal).

Go-live checklist

  • Switch JTL Environment to Production
  • Use production SecPaid API key
  • Update Callback and Webhook URLs to production shop domain
  • Confirm valid SSL certificate
  • Run one real test order
  • Confirm JTL-Wawi sync if applicable

Troubleshooting

Customer lands on cart with payment error

Cause Fix
Callback URL not set in SecPaid Add /secpaid/callback
Wrong shop URL in JTL Fix global Shop-URL
Plugin older than v3.0.0 Upgrade — v3 fixes HTML-encoded callback parameters

Order stays unpaid after payment

Cause Fix
Webhook URL missing Set https://YOUR-SHOP/secpaid/webhook in SecPaid
Shop blocks POST requests Allow /secpaid/webhook through firewall / ingress
Wrong API key environment Match sandbox/production key with JTL Environment

Payment method not shown at checkout

  • Plugin not activated in Plugin-Verwaltung
  • API key empty in Zahlungsarten
  • Payment method restricted by customer group or shipping method

Technical reference

Topic Detail
Plugin repository SPACEPITCH/SP-JTL-Plugin
Detailed setup guide docs in plugin repo
PostOrder mode Order created before redirect to SecPaid
Wawi sync Uses JTL addIncomingPayment() + setOrderStatusToPaid()

Support