Verwerk Security Deposits API-webhooks op basis van het actuele borgrecord. Controleer de handtekening en haal de status op wanneer een bericht verouderd of onvolledig kan zijn. Een gedeeltelijke Stripe-capture kan definitief zijn: het ongebruikte bedrag blijft niet beschikbaar.
Deze handleiding biedt een statusoverzicht voor ontwikkelaars van verhuursoftware. Gebruik de API-introductie voor de endpoints.
Hoe controleer je een borg-webhook?
Volgens de PayRequest-referentie bevat `X-PayRequest-Signature` de waarde `sha256=` gevolgd door de HMAC-SHA256-digest van de oorspronkelijke requestbody. Gebruik het ingestelde webhookgeheim, controleer de oorspronkelijke bytes vóór JSON-verwerking en vergelijk handtekeningen met een geschikte constante-tijdvergelijking. `X-PayRequest-Event` bevat de eventnaam.
Neem Stripe-headers of tijdstempelregels niet over. De openbare borgreferentie specificeert geen aflevervolgorde, event-ID-schema of replaytermijn. Controleer het volledige webhookcontract voordat je daarop vertrouwt.
Koppel gebeurtenissen aan boekingsbeslissingen
Een webhook meldt borgstatus; hij bewijst geen schade en geeft geen zelfstandige toestemming om af te schrijven. Bewaar inspectie, overeenkomst en beslissing in je verhuursysteem.
| Gebeurtenis of status | Betekenis | Actie |
|---|---|---|
| deposit.created / pending | Verzoek bestaat, geen bevestigde reservering | Wacht op autorisatie |
| deposit.authorized | Bedrag was gereserveerd | Controleer actuele status en capture_before |
| deposit.captured | Afschrijving afgerond | Bewaar afgeschreven bedrag en eindstatus |
| deposit.partially_captured | Providerafhankelijke uitkomst | Haal actuele status op |
| deposit.released | Reservering vrijgegeven | Beschrijf dit niet als terugbetaling |
| deposit.expired | Bevestigde reservering verlopen | Beoordeel openstaande verplichtingen |
| deposit.failed | Borgactie mislukt | Controleer record en foutcontext |
Waarom geeft gedeeltelijke Stripe-capture deposit.captured?
De gedocumenteerde Stripe-route ondersteunt één definitieve capture. Bij €350 autorisatie en €150 afschrijving wordt €200 vrijgegeven. De status is `captured`, captured_amount is 150.00 en de gebeurtenis is `deposit.captured`. Het verschil tussen oorspronkelijk en afgeschreven bedrag is geen resterende borg.
Lees de Stripe-uitleg en de handleiding gedeeltelijk afschrijven.
Hoe verwerk je dubbele of late berichten?
Maak de lokale boekingsupdate herhaalbaar zonder tweede bericht of afschrijving. Gebruik een aflever-ID alleen als het contract dat werkelijk beschrijft; verzin geen payloadveld. Haal bij twijfel actuele status op. Een laat autorisatiebericht mag een definitieve capture niet terugzetten naar gereserveerd.
Stripe beschrijft dubbele en ongeordende webhooks; dit verklaart het integratierisico maar bewijst geen PayRequest-afleverschema. Pending met metadata over een verlopen autorisatiepoging verschilt bovendien van expired voor een eerder bevestigde reservering.
Koppel borgverzoeken aan boekingen, houd de huurprijs apart via betaallinks en bekijk limieten. Gebruik vóór livegang de integratiechecklist.
Redactionele toelichting: AI hielp bij tekst en cover. Documentatie is gecontroleerd op 13 oktober 2026; er zijn geen webhookleveringen of live captures getest.
