Traitez les webhooks Security Deposits API à partir du dossier de caution actuel. Vérifiez la signature et relisez l’état si un message peut être ancien ou incomplet. Une capture partielle Stripe peut être définitive : le solde n’est alors plus disponible.
Ce guide complète la présentation de l’API par une grille destinée aux développeurs de logiciels de location.
Comment vérifier un webhook de caution ?
La référence PayRequest définit `X-PayRequest-Signature` comme `sha256=` suivi du condensat HMAC-SHA256 du corps brut de la requête. Utilisez le secret configuré, vérifiez les octets d’origine avant de traiter le JSON et comparez les signatures avec une méthode adaptée à temps constant. `X-PayRequest-Event` indique l’événement.
Ne transposez pas les en-têtes ou horodatages Stripe. La page publique ne précise ni ordre de livraison, ni schéma d’identifiant d’événement, ni fenêtre de rejeu.
Associer chaque événement à une décision
Un webhook décrit la caution ; il ne prouve pas un dommage. Conservez accord, inspection et décision dans votre logiciel.
| Événement ou état | Interprétation | Action |
|---|---|---|
| deposit.created / pending | Demande sans réserve confirmée | Attendre l’autorisation |
| deposit.authorized | Fonds précédemment réservés | Vérifier état actuel et capture_before |
| deposit.captured | Encaissement terminé | Enregistrer montant et état final |
| deposit.partially_captured | Résultat selon le prestataire | Relire le dossier |
| deposit.released | Réserve libérée | Ne pas parler de remboursement |
| deposit.expired | Réserve confirmée expirée | Examiner l’obligation restante |
| deposit.failed | Opération échouée | Examiner dossier et contexte |
Pourquoi une capture partielle Stripe émet-elle deposit.captured ?
PayRequest documente une capture finale unique pour Stripe. Une autorisation de €350 avec €150 encaissés libère €200. L’état est `captured`, captured_amount vaut 150.00 et l’événement est `deposit.captured`. La différence n’est pas une réserve encore utilisable. Consultez Stripe et le guide de capture partielle.
Gérer les messages doubles ou tardifs
Une notification répétée ne doit déclencher ni deuxième message ni deuxième encaissement. Utilisez un identifiant de livraison seulement si le contrat le documente ; n’inventez pas de champ. Relisez l’état en cas d’incertitude. Une ancienne notification d’autorisation ne doit pas annuler localement une capture finale.
Stripe décrit les doublons et événements non ordonnés, ce qui explique le risque général sans définir le calendrier PayRequest. Pending avec métadonnées de tentative expirée diffère de expired pour une réserve précédemment confirmée.
Reliez les cautions aux réservations, séparez les frais de location via les liens de paiement, puis consultez les limites et la checklist d’intégration.
Note éditoriale : texte et image assistés par IA. Documentation vérifiée le 13 octobre 2026 ; aucune livraison webhook ni capture réelle testée.
