Wie integriere ich PayPal für Umsatztracking?

Wenn Sie PayPal verbinden, kann Zenovay Umsätze neben Ihren Traffic-Daten anzeigen — welche Marketing-Quelle den zahlenden Kunden gebracht hat, auf welcher Seite er konvertiert hat, welche Kampagne das Geschäft abgeschlossen hat.

Sie benötigen drei Dinge aus Ihrem PayPal-Developer-Konto: eine Client ID, ein Client Secret und eine Webhook ID. Sie erstellen den Webhook in Ihrem PayPal-Dashboard (Zenovay zeigt Ihnen die genaue URL zum Einfügen) und kopieren seine ID zurück in Zenovay. Wir empfehlen, zuerst die Sandbox einzurichten, um zu prüfen, dass alles funktioniert, und dann auf Live umzustellen.

⚠️ Wichtig — Testhinweis, den Sie zuerst lesen sollten

Der Webhooks Simulator von PayPal (die Schaltfläche „Send Test" im PayPal Developer Dashboard) sendet Mock-Events, die per Design nicht signaturverifizierbar sind. Dies ist dokumentiertes PayPal-Verhalten — der Simulator bindet Signaturen an eine Platzhalter-WEBHOOK_ID und nicht an Ihre echte Webhook-ID, sodass die Verifizierungs-API für Simulator-Events immer FAILURE zurückgibt.

Um zu prüfen, dass Ihre Integration tatsächlich funktioniert, führen Sie einen echten Sandbox-Checkout durch (Schritt 5 unten) — dieser erzeugt ein korrekt signiertes Event, das Zenovay verifizieren kann.

Schritt 1: Eine PayPal-REST-API-App erstellen — und die Webhooks-Funktion aktivieren

⚠️ Aktivieren Sie die Webhooks-Funktion auf Ihrer App.

Neue PayPal-REST-API-Apps sind standardmäßig auf „Accept payments only" eingestellt. Ihre App benötigt die Webhooks-Funktion aktiviert, damit sie Webhooks erstellen und verifizieren kann. Dies ist eine einmalige Einrichtung von 30 Sekunden.

1. 1

   Bei PayPal Developer anmelden

   Gehen Sie zu developer.paypal.com und melden Sie sich mit Ihrem PayPal-Business-Konto an. Kostenlos; dauert etwa eine Minute.

2. 2

   Apps & Credentials öffnen

   Klicken Sie im Dashboard auf Apps & Credentials. Wechseln Sie zu Sandbox für Tests oder Live für Produktion.

3. 3

   Eine neue App erstellen

   Klicken Sie auf Create App. Geben Sie ihr einen Namen wie „Zenovay Analytics". Wählen Sie Merchant als App-Typ. Klicken Sie auf Create App.

4. 4

   Client ID und Secret kopieren

   PayPal zeigt Ihre Client ID (lange alphanumerische Zeichenkette) und Ihr Secret (klicken Sie auf Show, um es einzublenden) an. Lassen Sie diesen Tab offen — Sie werden diese Werte in Schritt 3 in Zenovay einfügen.

5. 5

   Die Webhooks-Funktion ankreuzen

   Scrollen Sie weiterhin auf der Einstellungsseite Ihrer App nach unten zum Abschnitt Features (manchmal als App settings bezeichnet). Sie sehen Kontrollkästchen wie Accept payments, Vault, Payouts, Subscriptions, Log in with PayPal und Webhooks.

   Aktivieren Sie das Kontrollkästchen Webhooks und klicken Sie dann am Ende der Seite auf Save Changes.

   Es ist nicht nötig, Ihr Client Secret neu zu generieren — die neue Berechtigung gilt unmittelbar für frische OAuth-Tokens.

Schritt 2: Den Webhook in PayPal erstellen und seine Webhook ID kopieren

Öffnen Sie die Einstellungen Ihrer Website in Zenovay und gehen Sie zum Tab Revenue (unter dem Bereich Analytics), dann klicken Sie auf die PayPal-Karte. Das Formular zeigt eine kopierbare Webhook-URL, die bereits Ihre Website-ID enthält — kopieren Sie sie und registrieren Sie den Webhook auf PayPals Seite.

1. 1

   Ihre Zenovay-Webhook-URL kopieren

   In der PayPal-Karte in Zenovay kopieren Sie die Webhook-URL, die oben im Formular angezeigt wird. Sie sieht wie folgt aus:

   https://api.zenovay.com/api/webhooks/paypal/YOUR_WEBSITE_ID
   

   Die URL ist bereits mit Ihrer Website-ID gefüllt — Sie müssen sie nicht selbst konstruieren.

2. 2

   Den Webhook in PayPal hinzufügen

   Zurück in PayPal Developer, innerhalb der Einstellungen Ihrer App, scrollen Sie zu Sandbox Webhooks (oder Live Webhooks). Klicken Sie auf Add Webhook und fügen Sie die URL ein, die Sie kopiert haben.

3. 3

   Die richtigen Events abonnieren

   Aktivieren Sie mindestens:

   • Payment capture completed
   • Payment capture refunded
   • Checkout order approved (optional; wird für Beobachtbarkeit protokolliert)

   Klicken Sie auf Save. PayPal generiert eine Webhook ID — notieren Sie sie sich für Schritt 3.

Schritt 3: In Zenovay verbinden

Immer noch auf der PayPal-Karte im Tab Revenue Ihrer Website-Einstellungen:

1. 1

   Ihre drei Zugangsdaten einfügen

   • Client ID — aus Schritt 1
   • Client Secret (dies ist das API-Key-Feld) — aus Schritt 1
   • Webhook ID — die ID, die PayPal in Schritt 2 generiert hat (erforderlich)
2. 2

   Sandbox oder Live wählen

   Stimmt mit der Umgebung überein, die Sie in Schritt 1 eingerichtet haben. Sandbox verwendet api-m.sandbox.paypal.com; Live verwendet api-m.paypal.com. Wenn Sie die Modi mischen, schlägt die Signaturprüfung fehl.

3. 3

   Auf Save klicken

   Zenovay validiert Ihre Zugangsdaten, indem es ein OAuth2-Access-Token abruft, und prüft dann die Webhook ID gegen PayPal. Die Karte wechselt auf Connected.

Schritt 4: Bestellungen mit der Besucher-ID kennzeichnen (empfohlen)

Damit die Zuordnung Zahlung-zu-Traffic-Quelle möglichst präzise funktioniert, setzen Sie die anonyme Zenovay-ID des Besuchers als custom_id, wenn Sie die PayPal-Bestellung auf Ihrem Server erstellen:

// Node.js example using @paypal/paypal-server-sdk
const visitorId = req.cookies['zv_visitor_id']; // or however your client passes it

await paypalClient.ordersCreate({
  body: {
    intent: 'CAPTURE',
    purchase_units: [{
      amount: { currency_code: 'USD', value: '42.00' },
      custom_id: visitorId, // ← Zenovay visitor UUID goes here
    }],
  },
});

Wenn die Erfassung abgeschlossen ist, liest Zenovay purchase_units[0].custom_id aus und verknüpft die Zahlung mit der Sitzung des Besuchers — einschließlich der Quelle, der Kampagne und der Seiten, die er vor der Zahlung besucht hat.

Wenn Sie custom_id nicht setzen, funktioniert die Attribution dennoch über die E-Mail-Adresse des Zahlers, ist aber weniger präzise (sie greift nur, wenn sich der Besucher zuvor mit derselben E-Mail identifiziert hat).

Wie die Attribution funktioniert

Zenovay ordnet jeden Zahlung einer Traffic-Quelle zu und lässt Sie zwischen mehreren Attributionsmodellen vom Tab Revenue aus wählen:

• Last Touch (Standard) — 100% des Kredits gehen an den letzten Kanal vor der Konvertierung. Gut zum Messen, was Deals abschließt.
• First Touch — 100% des Kredits gehen an den Kanal, der den Besucher zuerst gebracht hat. Gut zum Messen, was Entdeckung antreibt.
• Linear — Kredit wird gleichmäßig auf alle von dem Besucher verwendeten Kanäle aufgeteilt.
• Position-Based — 40% zum ersten Kanal, 40% zum letzten, die verbleibenden 20% über alles dazwischen.
• Time-Decay — mehr Kredit zu Kanälen, die näher an der Konvertierung liegen, mit einer 7-Tage-Halbwertszeit.

Sie wählen das Modell im Tab Revenue; die Aufschlüsselung wird für das von Ihnen gewählte Modell neu berechnet.

Schritt 5: Sandbox-Tests — verwenden Sie einen echten Checkout, nicht den Simulator

Verwenden Sie nicht den Webhooks Simulator von PayPal zum Testen. Simulator-Events können absichtlich nicht signaturverifiziert werden (PayPal dokumentiert dies) — sie schlagen die Verifizierungsprüfung von Zenovay immer fehl. Verwenden Sie stattdessen einen echten Sandbox-Checkout, wie unten beschrieben.

So prüfen Sie Ihre Sandbox-Integration richtig:

1. PayPal Developer Dashboard → Sandbox → Accounts. Sie sollten ein standardmäßiges Personal (buyer)-Sandbox-Konto mit einer Fake-E-Mail + Passwort sehen — das sind die Test-Käufer-Anmeldedaten.
2. Erstellen Sie aus Ihrer Anwendung oder dem PayPal SDK eine Sandbox-Bestellung, die auf Ihre Sandbox-client_id zeigt (setzen Sie purchase_units[0].custom_id = visitorId, wenn Sie die beste Attribution wünschen — siehe Schritt 4 oben).
3. Schließen Sie den Checkout mit dem Sandbox-Käufer-Konto aus Schritt 1 ab.
4. Innerhalb von etwa 10 Sekunden sendet PayPal einen echten, signierten PAYMENT.CAPTURE.COMPLETED-Webhook an Zenovay. Prüfen Sie das Eintreffen, indem Sie den Tab Revenue auf Ihrem Website-Dashboard öffnen — die Erfassung sollte mit der Sandbox-E-Mail des Käufers + Betrag erscheinen.

Wenn die Erfassung nach etwa 30 Sekunden nicht erscheint:

• Prüfen Sie das Verification status-Badge auf der PayPal-Karte in Ihren Revenue-Einstellungen — es zeigt den jüngsten Fehler.
• Vergewissern Sie sich, dass Sandbox vs. Live-Modus übereinstimmen: Ein Sandbox-Webhook, der gegen eine Live-Integration ausgelöst wird (oder umgekehrt), schlägt die Signaturprüfung fehl.
• Vergewissern Sie sich, dass der Webhook noch in PayPal registriert ist: PayPal Dashboard → Ihre App → Webhooks. Falls er gelöscht wurde, re-addieren Sie ihn und fügen Sie die neue Webhook ID zurück in Zenovay ein.

Wechsel von Sandbox zu Live

Wenn Sie für die Produktion bereit sind:

1. Erstellen Sie in PayPal Developer eine Live-REST-API-App und einen Live-Webhook (wiederholen Sie Schritt 1 + Schritt 2 im Live-Tab — der Live-Webhook erhält seine eigene Webhook ID).
2. Öffnen Sie in Zenovay die PayPal-Karte, fügen Sie die Live-Zugangsdaten und Live-Webhook-ID ein, schalten Sie den Toggle auf Live und klicken Sie auf Save.

PayPal sendet Events zu der Umgebung, die zu der registrierten Webhook ID passt, daher halten Sie die Zugangsdaten und Webhook ID für die gleiche Umgebung zusammen.

Trennen

Öffnen Sie die Einstellungen Ihrer Website → Tab Revenue → klicken Sie auf die PayPal-Karte → Remove.

Standardmäßig bewirkt das Trennen nur das Entfernen Ihrer PayPal-Zugangsdaten. Ihre vorhandenen Zahlungsdatensätze, Zuordnungshistorie und Daten im Revenue-Dashboard bleiben erhalten (gemäß dem Datenaufbewahrungsfenster Ihres Plans). Sie können sich jederzeit erneut verbinden und an der Stelle weitermachen, an der Sie aufgehört haben.

Optional: auch die historischen PayPal-Daten löschen

Der Trennungs-Dialog enthält ein Kontrollkästchen: „Auch N PayPal-Datensätze (insgesamt X €) dauerhaft löschen". Aktivieren Sie es nur, wenn Sie einen sauberen Stand wollen — zum Beispiel beim Stillegen einer Test-Integration oder beim Datenschutz-Aufräumen.

Wenn aktiviert, wird Zenovay:

• alle PayPal-payment_events-Zeilen für diese Website löschen
• alle PayPal-payments-Zeilen für diese Website löschen
• das Feld paypal_customer_id bei jedem identifizierten Benutzer leeren (der Benutzerdatensatz selbst bleibt bestehen — sie behalten ihre Stripe-ID usw.)

Die Löschung läuft in einer einzelnen Transaktion — schlägt ein Schritt fehl, werden alle drei zurückgerollt, sodass Sie nie in einem halbgelöschten Zustand landen. Die Aktion ist unumkehrbar.

Vergessen Sie nicht, den Webhook auf PayPal-Seite zu entfernen

Das Trennen in Zenovay bewirkt nur, dass Zenovay keine Events mehr annimmt. PayPal sendet den Webhook so lange weiter an unseren Endpunkt, bis Sie ihn in Ihrem PayPal Developer Dashboard löschen:

1. Öffnen Sie https://developer.paypal.com/dashboard/applications/
2. Klicken Sie auf Ihre PayPal REST API App.
3. Öffnen Sie den Bereich Webhooks.
4. Suchen Sie den Webhook, der auf https://api.zenovay.com/api/webhooks/paypal/{your-website-id} zeigt, und entfernen Sie ihn.

Bis Sie ihn auf PayPal-Seite entfernen, antwortet unser Endpunkt jeder Zustellung mit 410 Gone. PayPal stellt Wiederholungsversuche nach 410 ein — das ist also größtenteils kosmetisch, aber gute Hygiene und verhindert, dass der Webhook PayPals eigene Retry-Logs zuspammt.

Einschränkungen

• Ein PayPal-Konto pro Zenovay-Website. Wenn Sie Zahlungen über mehrere PayPal-Konten annehmen, konfigurieren Sie jedes auf einer eigenen Zenovay-Website.
• Connect ist nur Manualeingabe von Zugangsdaten. Es gibt kein „Log in with PayPal"-OAuth-Redirect — Sie fügen Client ID, Client Secret und Webhook ID direkt ein.

Fehlerbehebung

„Verification failed" bei einem echten Test-Webhook

Höchstwahrscheinlich ein Sandbox/Live-Konflikt — der Webhook, der von sandbox.paypal.com gegen Zugangsdaten ausgelöst wird, die als Live markiert sind (oder umgekehrt), schlägt die Signaturprüfung fehl. Prüfen Sie, dass der Toggle auf der PayPal-Karte mit der Umgebung Ihrer Zugangsdaten übereinstimmt.

Wenn Sie den Webhooks Simulator von PayPal verwendet haben, ist dies eine bekannte Einschränkung — Simulator-Events können per Design nicht signaturverifiziert werden (PayPal bindet die Signatur an einen Platzhalter-WEBHOOK_ID-Literalwert und nicht an Ihre echte Webhook-ID). Testen Sie stattdessen immer mit einem echten Sandbox-Checkout.

„NOT_AUTHORIZED" / 403-Fehler

Dies bedeutet normalerweise, dass die Webhooks-Funktion nicht auf Ihrer PayPal-REST-API-App aktiviert ist, oder Sie verwenden ein Personal-Sandbox-Konto, wo Webhooks ein Business-Sandbox-Konto erfordern.

Behebung:

1. Öffnen Sie https://developer.paypal.com/dashboard/applications und klicken Sie auf Ihre App.
2. Vergewissern Sie sich, dass Sie auf dem richtigen Tab sind (Sandbox oder Live) — sie haben getrennte Einstellungen.
3. Scrollen Sie zum Abschnitt Features (unter dem Block mit Client ID / Secret).
4. Aktivieren Sie das Kontrollkästchen Webhooks.
5. Klicken Sie am Ende der Seite auf Save Changes.
6. Wenn Sie auf Sandbox sind, vergewissern Sie sich, dass Sie ein Business-Sandbox-Konto verwenden, nicht ein Personal-Konto.

Sie müssen das Client Secret nicht neu generieren. Die neue Berechtigung gilt unmittelbar für frische OAuth-Tokens.

Haben das Limit von 10 Webhooks auf Ihrer PayPal-App erreicht

PayPal begrenzt jede REST-API-App auf 10 Webhooks. Wenn Sie Zenovay über viele Zenovay-Websites registriert haben, kann dieses Limit erreicht werden. Löschen Sie ungenutzte Webhooks unter https://developer.paypal.com/dashboard/applications, dann fügen Sie einen neuen Webhook hinzu und fügen Sie seine ID in die relevante Zenovay-Website ein.

Weiterführende Lektüre

• Stripe-Umsatzintegration
• Webhooks-Übersicht
• E-Commerce-Umsatztracking
• Tracking-Skript installieren