Verarbeiten Sie Security Deposits API-Webhooks anhand des aktuellen Kautionsdatensatzes. Prüfen Sie die Signatur und rufen Sie den Status ab, wenn eine Nachricht veraltet oder unvollständig sein könnte. Ein Teil-Capture bei Stripe kann endgültig sein; der Rest bleibt dann nicht verfügbar.
Dieser Leitfaden ergänzt die API-Einführung um eine Statuszuordnung für Vermietungssoftware.
Wie prüfen Sie einen Kautions-Webhook?
Die PayRequest-Referenz beschreibt `X-PayRequest-Signature` als `sha256=` mit dem HMAC-SHA256-Digest des unveränderten Request-Bodys. Verwenden Sie das konfigurierte Webhook-Geheimnis und eine geeignete konstante Vergleichszeit. Prüfen Sie die ursprünglichen Bytes vor der JSON-Verarbeitung. `X-PayRequest-Event` enthält den Ereignisnamen.
Übernehmen Sie keine Stripe-Header oder Zeitstempelregeln. Die öffentliche Kautionsreferenz legt weder Lieferreihenfolge noch Event-ID-Schema oder Replay-Frist fest.
Ordnen Sie Ereignisse Buchungsentscheidungen zu
Ein Webhook meldet einen Zustand, belegt aber keinen Schaden. Vereinbarung, Prüfung und Entscheidung bleiben im Vermietungssystem.
| Ereignis oder Status | Bedeutung | Handlung |
|---|---|---|
| deposit.created / pending | Anfrage ohne bestätigte Reservierung | Autorisierung abwarten |
| deposit.authorized | Mittel waren reserviert | Aktuellen Status und capture_before prüfen |
| deposit.captured | Betrag eingezogen | Tatsächlichen Betrag und Endzustand speichern |
| deposit.partially_captured | Anbieterabhängiges Ergebnis | Aktuellen Datensatz abrufen |
| deposit.released | Reservierung freigegeben | Nicht als Rückerstattung bezeichnen |
| deposit.expired | Bestätigte Reservierung abgelaufen | Offene Verpflichtungen prüfen |
| deposit.failed | Vorgang fehlgeschlagen | Datensatz und Fehlerkontext prüfen |
Warum meldet ein Stripe-Teil-Capture deposit.captured?
PayRequest dokumentiert einen endgültigen Capture für Stripe. Bei €350 Autorisierung und €150 Einzug werden €200 freigegeben. Status: `captured`; captured_amount: 150.00; Ereignis: `deposit.captured`. Die Differenz ist keine verbleibende Sicherheit. Siehe Stripe-Autorisierungen und den Leitfaden zum Teil-Capture.
Wie behandeln Sie doppelte oder späte Nachrichten?
Eine wiederholte Benachrichtigung darf weder eine zweite Nachricht noch einen zweiten Einzug auslösen. Nutzen Sie einen dokumentierten Lieferbezeichner, wenn vorhanden; erfinden Sie kein Payload-Feld. Rufen Sie bei Unklarheit den aktuellen Datensatz ab. Ein später Autorisierungshinweis darf einen endgültigen Capture nicht zurücksetzen.
Stripe beschreibt doppelte und ungeordnete Webhooks. Das erklärt das allgemeine Risiko, definiert aber keinen PayRequest-Zustellplan. Pending mit Metadaten zu einem abgelaufenen Autorisierungsversuch unterscheidet sich vom Status expired einer zuvor bestätigten Reservierung.
Verbinden Sie Kautionen mit Buchungen, führen Sie Mietzahlungen über Zahlungslinks getrennt und prüfen Sie Tarifgrenzen sowie die Integrationscheckliste.
Redaktioneller Hinweis: KI unterstützte Text und Bild. Dokumentation geprüft am 13. Oktober 2026; keine Webhook-Zustellung oder Live-Capture getestet.
