Paddle ist der Merchant-of-Record-Zahlungsanbieter, den viele EU-SaaS-Unternehmen nutzen — Paddle übernimmt EU-Mehrwertsteuer, US-Umsatzsteuer, Rückerstattungen, Rückbuchungen und die globale Compliance in Ihrem Namen und überweist Ihnen den Nettobetrag.

Wenn Sie Paddle mit Zenovay verbinden, können Sie Paddle-Umsätze neben Ihren Traffic-Daten sehen — welche Kampagnen den Abschluss bringen, welche Seiten konvertieren, welche Quellen den besten LTV haben.

Sie benötigen nur EINE Sache: einen Paddle API-Schlüssel mit Schreibberechtigung. Zenovay erstellt das Webhook-Ziel in Ihrem Namen, erfasst das Signing-Secret über Paddle's API und speichert beides — verschlüsselt. Derselbe Ablauf gilt sowohl für Sandbox als auch für Live; Sie wählen einfach die Umgebung mit dem Schalter Sandbox/Live auf dem Formular.

Einrichtung (2 Minuten)

1
API-Schlüssel mit Schreibberechtigung in Paddle generieren
- Live: vendors.paddle.com/authentication-v2
- Sandbox: sandbox-vendors.paddle.com/authentication-v2
Klicken Sie auf New API key → benennen Sie ihn "Zenovay analytics" → Berechtigung: Write → Create.
Paddle zeigt den Schlüssel NUR EINMAL an. Kopieren Sie ihn jetzt. Live-Schlüssel beginnen mit pdl_live_apikey_…; Sandbox-Schlüssel beginnen mit pdl_sdbx_apikey_….
2
Schlüssel in Zenovay einfügen und auf Speichern klicken
1. Gehen Sie in app.zenovay.com zu Ihrer Website unter Domains, klicken Sie auf Settings und wählen Sie den Revenue-Tab.
2. Klicken Sie auf die Paddle-Karte.
3. Fügen Sie den API-Schlüssel ein und stellen Sie den Schalter Sandbox/Live entsprechend ein (pdl_sdbx_apikey_…-Schlüssel sind Sandbox; pdl_live_apikey_…-Schlüssel sind Live). Wenn Schalter und Schlüsselpräfix nicht übereinstimmen, wird die Verbindung mit einer klaren Fehlermeldung abgelehnt.
4. Klicken Sie auf Save Configuration.

Das war es. Im Hintergrund führt Zenovay folgende Schritte aus:

Validiert den Schlüssel gegen Paddle's /event-types-Endpunkt.
Ruft POST /notification-settings auf, um ein Webhook-Ziel unter https://api.zenovay.com/api/webhooks/paddle/<your-website-id> zu erstellen, das die vier kanonischen Ereignisse abonniert (transaction.completed, subscription.created, subscription.updated, subscription.canceled).
Erfasst endpoint_secret_key aus Paddle's Antwort und speichert es verschlüsselt.
Schaltet die Karte auf Connected.

Sie berühren das Paddle-Dashboard nie. Sie sehen oder kopieren nie ein Signing-Secret. Jeder Webhook von Paddle wird mit dem gespeicherten Secret verifiziert, bevor etwas in die Datenbank geschrieben wird.

„Wo finde ich mein Signing-Secret in Paddle?" — kurze Antwort: Das müssen Sie nicht

Dies ist die häufigste Verwirrung. Paddle verbirgt das Signing-Secret im Dashboard absichtlich, nachdem das Ziel erstellt wurde. Es gibt keine „Anzeigen"-Schaltfläche, keinen „Anzeigen"-Link — nur Rotate Secret (das den alten ungültig macht und einen neuen ausgibt). Bei Konten, die das Secret bei der Erstellung anzeigen, haben Sie nur kurz Zeit, es zu kopieren, bevor es verschwindet.

Dies ist normales Paddle-Verhalten, kein Fehler. Es existiert aus einem Sicherheitsgrund: Secrets in Benutzeroberflächen gelangen über Screenshots, Support-Tickets und neugierige Blicke nach außen.

Genau deshalb erfordert Zenovay's Connect-Flow nicht, dass Sie es finden. Wir nutzen Paddle's API (die das Secret programmatisch für Ihre eigenen Ziele zugänglich macht), um es automatisch abzurufen. Sie berühren es nie.

Was ist, wenn ich das Ziel bereits manuell erstellt habe?

Das ist in Ordnung. Wenn Sie die Paddle-Karte in Zenovay speichern:

Falls bereits ein Ziel unter unserer URL existiert, verwendet Zenovay es weiter und ruft das Secret über die API ab.
Falls es derzeit inaktiv ist (z. B. weil jemand es in der Paddle-UI deaktiviert hat), reaktiviert Zenovay es.
Keine doppelten Ziele, keine manuelle Bereinigung.

Was ist, wenn ich es dennoch manuell einrichten möchte?

Das ist möglich, aber mit Aufwand ohne Nutzen verbunden. Falls Sie darauf bestehen:

Manuelle Einrichtungsschritte (nicht empfohlen)

In Paddle → Notifications → Destinations → New destination → Webhook.
URL: https://api.zenovay.com/api/webhooks/paddle/YOUR_WEBSITE_ID (Ihre Website-ID ist die UUID in der Seiten-URL, wenn Sie die Website unter Domains öffnen, oder oben im Revenue-Einstellungs-Tab).
Abonnieren Sie All-Ereignisse (Zenovay ignoriert alles, was es nicht verarbeitet, stillschweigend).
Speichern Sie das Ziel.
Hier scheitern die meisten: Paddle zeigt das Signing-Secret möglicherweise auf dem nächsten Bildschirm an oder auch nicht. Falls nicht:
- Option A: Rotieren Sie das Secret (Paddle → Destinations → auf Ihr Ziel klicken → Rotate Secret). Kopieren Sie den neuen Wert.
- Option B: Löschen Sie dieses Ziel und verwenden Sie stattdessen Zenovay's Connect-Flow (Zenovay erstellt es neu und ruft das Secret über die API ab).
In Zenovay → Paddle-Karte → öffnen Sie den Abschnitt Advanced (optional) nach dem Einfügen Ihres API-Schlüssels → fügen Sie das pdl_ntfset_…-Signing-Secret in das Feld „Webhook Secret" ein.
Speichern.

Für 99 % der Nutzer reicht der Connect-Flow oben aus — überspringen Sie diesen Abschnitt.

Transaktionen mit der Besucher-ID taggen (empfohlen)

Damit die Zuordnung von Zahlung zu Traffic-Quelle möglichst präzise funktioniert, setzen Sie die anonyme Zenovay-ID des Besuchers als custom_data, wenn Sie die Paddle-Transaktion oder den Checkout auf Ihrem Server erstellen:

// Node.js example using Paddle's API directly
const visitorId = req.cookies['zv_visitor_id']; // however your client passes it

await fetch('https://api.paddle.com/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PADDLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ price_id: 'pri_01h…', quantity: 1 }],
    customer_id: paddleCustomerId,
    custom_data: { zenovay_visitor_id: visitorId },
  }),
});

Wenn die Transaktion abgeschlossen wird, liest Zenovay data.custom_data.zenovay_visitor_id und verknüpft die Zahlung mit der Besuchersitzung — einschließlich der Quelle, Kampagne und der besuchten Seiten vor dem Kauf.

Wenn Sie custom_data nicht setzen, funktioniert die Zuordnung dennoch über die E-Mail-Adresse des Kunden (sofern im Ereignis vorhanden), ist aber weniger präzise — sie greift nur, wenn der Besucher sich zuvor mit derselben E-Mail-Adresse identifiziert hat.

Welches Attributionsmodell wird verwendet

Zenovay unterstützt zwei Attributionsfenster:

First-touch — die Gutschrift geht an die Quelle, von der der Besucher bei seiner ersten Sitzung gekommen ist.
Last-touch — die Gutschrift geht an die Quelle, von der er in der Sitzung mit der Zahlung gekommen ist.

Beide werden berechnet und nebeneinander im Revenue-Tab angezeigt.

Schritt 5: Sandbox-Tests

Der richtige Weg, um Ihre Sandbox-Integration zu überprüfen, ist ein echter Test-Checkout:

Erstellen Sie im Paddle-Sandbox-Dashboard ein Testprodukt und einen Preis.
Verwenden Sie ein Checkout-Overlay oder eine gehostete Checkout-URL auf einer Testseite, die Ihr Zenovay Tracking-Skript lädt.
Schließen Sie den Checkout mit einer der Testkartennummern von Paddle ab.
Innerhalb von ~10 Sekunden sendet Paddle ein echtes, signiertes transaction.completed-Ereignis an Zenovay. Überprüfen Sie den Eingang, indem Sie den Revenue-Tab in Zenovay öffnen — die Erfassung sollte mit der E-Mail und dem Betrag des Käufers erscheinen.

Falls die Erfassung nach ~30 Sekunden nicht erscheint:

Prüfen Sie das Verification status-Badge auf der Paddle-Karte in den Zenovay-Einstellungen.
Stellen Sie sicher, dass der Sandbox- bzw. Live-Modus auf beiden Seiten übereinstimmt. Ein Paddle-Dashboard in der Sandbox-Umgebung sendet Ereignisse von sandbox-api.paddle.com; wenn Zenovay auf Live-Modus eingestellt ist, schlägt die Signaturprüfung fehl.
Stellen Sie sicher, dass das Benachrichtigungsziel in Paddle noch aktiviert ist (Paddle deaktiviert Ziele automatisch nach 5 aufeinanderfolgenden 5xx-Antworten; falls Zenovay während Ihres Tests deployt wurde, aktivieren Sie es erneut).

Währungsunterstützung

Paddle gibt Transaktionsbeträge in der kleinsten Einheit der jeweiligen Währung zurück (z. B. "4999" für $49,99 USD). Zenovay konvertiert dies korrekt gemäß ISO 4217:

Dezimalwährungen (USD, EUR, GBP, …): durch 100 teilen → 4999 wird zu 49.99.
Null-Dezimal-Währungen (JPY, KRW, VND, …): Wert unverändert verwenden → 5000 JPY bleibt 5000.
Drei-Dezimal-Währungen (BHD, KWD, OMR, …): durch 1000 teilen → 1500 BHD wird zu 1.500.

Sie müssen nichts konfigurieren — Zenovay erledigt dies automatisch anhand des currency_code im Ereignis.

Wechsel von Sandbox zu Live

Wenn Sie bereit für den Produktionsbetrieb sind:

Wiederholen Sie im Paddle-Live-Dashboard (vendors.paddle.com, nicht sandbox-vendors) Schritt 1 und Schritt 2, um ein Live-Benachrichtigungsziel und einen Live-API-Schlüssel zu erstellen.
Klicken Sie in Zenovay auf die Paddle-Karte → Disconnect (der Verlauf bleibt erhalten) → erneut klicken, um die Verbindung wiederherzustellen → die Live-Zugangsdaten einfügen → den Schalter auf Live umstellen → Speichern.

Dieselbe Zenovay-Webhook-URL funktioniert für beide Umgebungen; Paddle sendet die Ereignisse an das Ziel, das Ihrem aktiven API-Schlüssel entspricht.

Verbindung trennen

Öffnen Sie Ihre Website unter Domains → Settings → der Revenue-Tab → klicken Sie auf die Paddle-Karte → Disconnect.

Standardmäßig entfernt das Trennen der Verbindung nur Ihre Paddle-Zugangsdaten. Ihre bestehenden Zahlungsaufzeichnungen, der Attributionsverlauf und die Revenue-Dashboard-Daten bleiben erhalten (vorbehaltlich des Datenaufbewahrungsfensters Ihres Tarifs). Sie können die Verbindung jederzeit wiederherstellen und dort weitermachen, wo Sie aufgehört haben.

Optional: historische Paddle-Daten ebenfalls löschen

Der Trennungs-Dialog enthält ein Kontrollkästchen: „N Paddle-Datensätze auch dauerhaft löschen (insgesamt $X)". Aktivieren Sie es nur, wenn Sie einen Neustart wünschen — z. B. beim Stilllegen einer Testintegration oder für Datenschutz-Housekeeping.

Wenn aktiviert, führt Zenovay folgende Aktionen aus:

Löscht alle Paddle-Payment-Ereignisse für diese Website
Löscht alle Paddle-Payment-Datensätze für diese Website
Löscht das Paddle-Kunden-ID-Feld bei jedem identifizierten Nutzer (der Nutzerdatensatz selbst bleibt erhalten — seine Stripe-ID usw. bleiben bestehen)

Die Löschung erfolgt in einer einzigen Transaktion — falls ein Schritt fehlschlägt, werden alle drei zurückgerollt, sodass kein halbgelöschter Zustand entsteht. Die Aktion ist nicht umkehrbar.

Vergessen Sie nicht, das Paddle-seitige Benachrichtigungsziel zu deaktivieren

Das Trennen der Verbindung in Zenovay stoppt nur, dass Zenovay Ereignisse akzeptiert. Paddle sendet weiterhin das Ziel an unser Endpunkt, bis Sie es in Ihrem Paddle-Dashboard deaktivieren:

Öffnen Sie Paddle → Notifications → Destinations.
Suchen Sie das Ziel, das auf https://api.zenovay.com/api/webhooks/paddle/{your-website-id} zeigt.
Klicken Sie darauf → schalten Sie Disabled um (oder Delete).

Bis dahin antwortet unser Endpunkt mit 400 "Webhook not configured for this website" auf jede Anfrage. Paddle deaktiviert das Ziel nach ausreichend vielen Fehlern automatisch — aber eine explizite Entfernung ist sauberer und verhindert, dass das Ziel Ihr Dashboard belastet.

Einschränkungen (V1)

Rückerstattungsereignisse werden noch nicht dargestellt. Abonnieren Sie adjustment.created / adjustment.updated in Ihrem Ziel trotzdem — Zenovay ignoriert sie heute stillschweigend und wird sie darstellen, sobald V2 veröffentlicht wird.
subscription.past_due- und subscription.paused-Ereignisse werden empfangen und dedupliziert gespeichert, aber noch nicht im Dashboard dargestellt. Der Abonnementstatus wechselt korrekt auf past_due, aber Sie erhalten keine dedizierte Vorfallansicht.
Ein Paddle-Konto pro Zenovay-Website. Wenn Sie Zahlungen über mehrere Paddle-Konten akzeptieren (z. B. eines pro geografischer Tochtergesellschaft), konfigurieren Sie jedes auf einer eigenen Zenovay-Website.
OAuth-Redirect-Verbindung wird nicht unterstützt. Nur manuelle Zugangsdateneingabe.

Fehlerbehebung

„Invalid Paddle API key" beim Speichern

Drei übliche Ursachen:

Falsche Umgebung. Ein pdl_sdbx_apikey_…-Schlüssel mit eingeschaltetem Live-Schalter (oder umgekehrt) schlägt bei der Validierung fehl. Zenovay zeigt eine spezifische Fehlermeldung — passen Sie den Schalter an das Präfix an.
Der Schlüssel muss Schreibberechtigung haben UND nicht widerrufen sein. Schreibgeschützte Schlüssel bestehen die Validierung, schlagen aber fehl, wenn Zenovay versucht, das Ziel zu erstellen (403). Widerrufene Schlüssel schlagen die Validierung direkt fehl (401). Generieren Sie einen neuen Schlüssel mit Schreibbereich.
Der Schlüssel gehört zu einem anderen Team / Konto. Paddle API-Schlüssel sind auf ein einzelnes Paddle-Konto beschränkt; das Einfügen eines Schlüssels von einem anderen Konto schlägt sofort fehl.

„Webhook not configured for this website"

Entweder haben Sie noch keine Paddle-Zugangsdaten in Zenovay gespeichert, oder Sie testen die falsche Webhook-URL. Die URL muss die genaue YOUR_WEBSITE_ID für die Website, die Sie verbunden haben, enthalten (die UUID in der Seiten-URL, wenn Sie die Website unter Domains in app.zenovay.com öffnen).

„Signature verification failed: replay_window_exceeded"

Zenovay lehnt Webhook-Ereignisse mit Zeitstempeln ab, die mehr als 5 Minuten von der aktuellen Zeit abweichen. Dies bedeutet normalerweise eine Zeitabweichung auf Ihrer oder Paddle's Seite. Falls Sie dies bei einem frischen Test sehen:

Starten Sie Ihren Server neu (Zeitdrift ist ungewöhnlich, aber passiert nach langer Betriebszeit).
Triggern Sie den Webhook erneut über das Paddle-Dashboard (Notifications → Deliveries → Resend).

Verifizierter Webhook kommt an, aber die Transaktion fehlt im Revenue-Tab

Paddle-Webhooks kommen in 3 verschiedenen Strukturen an, je nachdem, ob der Kunde eigenständig oder als Teil eines Checkouts erstellt wurde. Zenovay's Parser ist defensiv ausgelegt, aber wenn Sie eine verifizierte Zustellung in Ihren Logs sehen und nichts unter Revenue erscheint:

Stellen Sie sicher, dass die Zustellung in Paddle's Zustellungsprotokoll 2xx zurückgegeben hat. Ein Signatur- oder Umgebungsabweichung zeigt sich dort als 4xx.
Falls die E-Mail des Käufers im Ereignis fehlt, fiel Zenovay auf Abgleich nach der Paddle-Kundennummer zurück. Die Transaktion ist aufgezeichnet, erscheint aber nicht in identifizierten Nutzeransichten, bis derselbe Kunde zukünftig verknüpft wird.
Falls es immer noch nicht erscheint, wenden Sie sich unter [email protected] mit der Paddle-Zustellungs-ID an den Support, damit wir es nachverfolgbar machen können.

Wie integriere ich Paddle für Umsatztracking?

Einrichtung (2 Minuten)

API-Schlüssel mit Schreibberechtigung in Paddle generieren

Schlüssel in Zenovay einfügen und auf Speichern klicken