Webhook-Einrichtung bei PayPal

Überblick

Ein Webhook ist die Rückmeldung von PayPal an Kyvento: Immer wenn bei PayPal etwas passiert, das Kyvento wissen muss – eine Zahlung ist eingegangen, ein Betrag wurde erstattet, PayPal bucht eine Zahlung zurück oder ein Kunde eröffnet einen Konflikt (Dispute) –, schickt PayPal eine Nachricht an eine feste Adresse in Kyvento. Ohne diesen Rückkanal sieht Kyvento nur die unmittelbare Zahlung, aber keine dieser nachgelagerten Ereignisse. Die Folge: Rechnungen bleiben fälschlich auf „bezahlt", obwohl das Geld längst zurückgeflossen ist. Dieser Artikel zeigt Schritt für Schritt, wie der Webhook eingerichtet wird – das ist ein Zwei-Wege-Setup: Sie tragen die Kyvento-Webhook-URL in Ihrer PayPal-App ein und übertragen anschließend die von PayPal erzeugte Webhook-ID zurück nach Kyvento.

Voraussetzungen

• Ein PayPal-Geschäftskonto und Zugang zum PayPal Developer Dashboard (developer.paypal.com).
• PayPal ist in Kyvento eingerichtet (Client-ID und Secret hinterlegt) – Einstellungen → Zahlungen → PayPal.
• In Kyvento die Berechtigung, Einstellungen zu verwalten (z. B. Systemrolle „Administrator" oder „Vollzugriff").
• Sie wissen, ob Sie PayPal in Kyvento im Live- oder im Sandbox-Modus betreiben.

Schritt 1: Webhook-URL aus Kyvento kopieren

1. Öffnen Sie in Kyvento Einstellungen → Zahlungen → PayPal.
2. Suchen Sie die Karte „Webhook-URL". Dort steht Ihre persönliche, kontogebundene Adresse – sie endet auf Ihre Kyvento-Konto-Nummer und sieht etwa so aus: https://app.kyvento.com/api/webhooks/paypal/123.
3. Klicken Sie auf das Kopier-Symbol, um die vollständige URL in die Zwischenablage zu übernehmen.

Schritt 2: Die richtige App im PayPal Developer Dashboard öffnen

1. Melden Sie sich unter developer.paypal.com an und öffnen Sie Apps & Credentials.
2. Schalten Sie oben auf die passende Umgebung um: Live oder Sandbox – dieselbe, die Sie in Kyvento verwenden.
3. Öffnen Sie die App, deren Client-ID und Secret Sie in Kyvento hinterlegt haben.

Auf derselben App-Seite liegt unter Features auch der Zusatzdienst „Transaction search", den Kyvento für den täglichen Saldo-Abgleich braucht. Ist er noch nicht angehakt, holen Sie das bei dieser Gelegenheit nach – wie, steht im Abschnitt „Transaction search aktivieren" unter PayPal-Integration.

Schritt 3: Den Webhook anlegen und Ereignisse auswählen

1. Scrollen Sie in der App zum Abschnitt „Webhooks" und klicken Sie auf „Add Webhook".
2. Fügen Sie unter „Webhook URL" die in Schritt 1 kopierte Kyvento-URL ein.
3. Wählen Sie bei „Event types" die folgenden Ereignisse aus. Kyvento verarbeitet ausschließlich diese – ein fehlendes Ereignis bedeutet, dass die zugehörige Aktion in Kyvento nie ankommt:

• PAYMENT.CAPTURE.COMPLETED – Zahlung erfolgreich eingegangen (Rechnung wird auf „bezahlt" gesetzt)
• PAYMENT.CAPTURE.DENIED – Zahlung abgelehnt/fehlgeschlagen
• PAYMENT.CAPTURE.REFUNDED – Betrag wurde erstattet
• PAYMENT.CAPTURE.REVERSED – erzwungene Rückbuchung (z. B. durch die Bank), auch ohne formalen Konflikt
• CUSTOMER.DISPUTE.CREATED – Kunde eröffnet einen Konflikt/Käuferschutzfall
• CUSTOMER.DISPUTE.RESOLVED – Konflikt abgeschlossen (zu Ihren Gunsten oder nicht)
• BILLING_AGREEMENTS.AGREEMENT.CANCELLED – der Kunde hat die automatischen Zahlungen in seinem PayPal-Konto widerrufen; Kyvento löst daraufhin das gespeicherte PayPal-Zahlungsmittel des Kunden ab. PayPal sendet für diesen Widerruf kein VAULT.PAYMENT-TOKEN.DELETED – fehlt dieses Ereignis, behält der Kunde im Portal ein Zahlungsmittel, das nicht mehr existiert.

Die sieben Ereignisse oben sind verpflichtend für eine vollständige Verbuchung. Zusätzlich können Sie VAULT.PAYMENT-TOKEN.CREATED und VAULT.PAYMENT-TOKEN.DELETED aktivieren: CREATED wird nur protokolliert und löst keine Buchung aus; DELETED löst – wie der Widerrufs-Event – das gespeicherte Zahlungsmittel aktiv ab und sollte deshalb ebenfalls ausgewählt sein.

4. Speichern Sie den Webhook mit „Save".

Falls die Einzelauswahl zu kleinteilig ist, funktioniert auch „All events" – Kyvento ignoriert dann einfach alles, was nicht in der Liste oben steht. Die gezielte Auswahl hält das Ereignis-Protokoll jedoch übersichtlicher.

Schritt 4: Die Webhook-ID zurück nach Kyvento übertragen

Damit Kyvento sicher sein kann, dass eine Nachricht wirklich von Ihrer PayPal-App stammt, prüft es jede Zustellung anhand der Webhook-ID. Ohne diese ID lehnt Kyvento alle Webhook-Ereignisse ab. Der Zahlungseinzug selbst funktioniert auch ohne Webhook-ID – Kyvento kennzeichnet das Feld deshalb als „Empfohlen": Ohne Webhook-ID erhalten Sie keine automatischen Meldungen zu Rückbuchungen (Chargebacks) und extern in PayPal ausgelösten Erstattungen.

1. Nach dem Speichern zeigt PayPal die neu erzeugte Webhook-ID an (eine Zeichenfolge wie 5GP028356R811364S). Kopieren Sie diese ID.
2. Wechseln Sie zurück nach Kyvento: Einstellungen → Zahlungen → PayPal.
3. Fügen Sie die kopierte ID in das Feld „Webhook ID" ein.
4. Speichern Sie die Einstellungen.

Erfolgskontrolle

Prüfen Sie zum Abschluss, ob die Verbindung wirklich funktioniert:

1. Öffnen Sie in der PayPal-App den angelegten Webhook und nutzen Sie – sofern verfügbar – die Funktion zum Senden eines Test-/Mock-Ereignisses (z. B. PAYMENT.CAPTURE.COMPLETED).
2. Im Ereignis-Protokoll des Webhooks muss die Zustellung mit dem Status HTTP 200 erscheinen. Der Status 200 bestätigt dabei nur, dass Kyvento die Zustellung angenommen hat – die Echtheitsprüfung anhand der Webhook-ID läuft unmittelbar danach.

Entscheidend ist deshalb die echte Gegenprobe: Lösen Sie eine Testzahlung aus – sie erscheint in Kyvento als „bezahlt". Erstatten Sie diese Zahlung anschließend direkt in PayPal; in Kyvento sollte die zugehörige Zahlung daraufhin als „Erstattet" erscheinen (in der Zahlungsübersicht der Rechnung). Eine Garantie ist das nicht: Kyvento verbucht PAYMENT.CAPTURE.REFUNDED nur, wenn sich aus der PayPal-Nachricht die ursprüngliche Zahlung (Capture-ID) ermitteln lässt – andernfalls wird das Ereignis nur protokolliert, und die Erstattung ist von Hand nachzutragen (siehe PayPal-Erstattung manuell in Kyvento nachtragen). Kyvento weist im PayPal-Tab selbst darauf hin.

Wenn es nicht klappt

• Status 403 im PayPal-Protokoll: In Kyvento fehlt die Webhook-ID (oder Client-ID/Secret) – Schritt 4 wurde noch nicht abgeschlossen. Tragen Sie die Webhook-ID in das Feld „Webhook ID" ein und speichern Sie.
• Zustellungen zeigen Status 200, aber in Kyvento kommt nichts an: Die hinterlegte Webhook-ID passt nicht zur sendenden App. Häufigste Ursache: Die ID stammt aus der falschen Umgebung (Live statt Sandbox oder umgekehrt) oder aus einer anderen App. Kyvento nimmt die Zustellung zwar an, verwirft sie aber bei der anschließenden Echtheitsprüfung. Übertragen Sie die Webhook-ID aus genau der App, deren Client-ID in Kyvento hinterlegt ist.
• Status 404: Die Webhook-URL ist unvollständig – meist fehlt die Konto-Nummer am Ende. Kopieren Sie die URL erneut aus der Karte „Webhook-URL".
• Erstattungen/Konflikte kommen nicht an, Zahlungen aber schon: In der Ereignis-Auswahl fehlen die PAYMENT.CAPTURE.REFUNDED-/CUSTOMER.DISPUTE.*-Typen. Ergänzen Sie sie in der PayPal-App.
• Der Kunde hat die PayPal-Zahlungen widerrufen, im Portal steht das Zahlungsmittel aber noch: In der Ereignis-Auswahl fehlt BILLING_AGREEMENTS.AGREEMENT.CANCELLED. Ergänzen Sie den Typ – ein VAULT.PAYMENT-TOKEN.DELETED sendet PayPal bei einem Kunden-Widerruf nicht.

Nächste Schritte

• Stripe-Webhook einrichten – siehe Webhook-Einrichtung bei Stripe
• PayPal als Zahlungsmethode aktivieren – siehe PayPal-Integration
• Eine direkt in PayPal ausgelöste Erstattung von Hand nachtragen – siehe PayPal-Erstattung manuell in Kyvento nachtragen