Vos cautions, pilotées depuis votre logiciel

Comment ça marche

1. 1

   Créez une clé

   Depuis Compte › API. Une clé par logiciel connecté.

2. 2

   Créez la caution

   À la réservation, votre logiciel appelle POST /deposits. Le locataire reçoit le lien et enregistre sa carte, sans être débité.

3. 3

   Suivez-la

   Kauti prévient votre serveur à chaque étape. Vous encaissez ou libérez par un appel, ou laissez la libération automatique faire.

Une caution créée par l'API suit exactement les mêmes règles qu'une caution créée dans l'interface : même page pour le locataire, mêmes e-mails, même libération automatique, même facturation. Elle apparaît aussi dans votre tableau de bord.

Démarrage rapide

Toutes les requêtes passent par https://www.kauti.fr/api/v1, en HTTPS, avec la clé dans l'en-tête Authorization. Les montants sont en centimes, les dates au format AAAA-MM-JJ, les heures en HH:MM, à l'heure locale du compte. Une location couvre 90 jours au plus entre start_date et end_date, et start_date tombe entre hier et 365 jours après aujourd'hui.

curl https://www.kauti.fr/api/v1/deposits \
  -H "Authorization: Bearer kauti_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "guest": { "email": "locataire@exemple.fr", "phone": "+33612345678" },
    "rental": {
      "start_date": "2026-11-12", "start_time": "16:00",
      "end_date": "2026-11-19", "end_time": "10:00",
      "reference": "BOOKING-4123456789"
    },
    "external_id": "resa-8812",
    "send_email": true
  }'

La réponse décrit la caution. Avec "send_email": false, Kauti n'écrit pas au locataire : envoyez-lui vous-même checkout_url, par SMS ou dans votre propre message de confirmation. external_id, facultatif, est votre identifiant de réservation : une seconde création avec le même renvoie une erreur au lieu d'une caution en double.

{
  "object": "deposit",
  "id": "5b0d9c3e-8f1a-4b8e-9d3a-2f6c1e7a4b90",
  "external_id": "resa-8812",
  "status": "pending_guest",
  "amount": 50000,
  "currency": "eur",
  "guest": { "email": "locataire@exemple.fr", "phone": "+33612345678", "email_bounced": false },
  "rental": {
    "reference": "BOOKING-4123456789",
    "start_date": "2026-11-12", "start_time": "16:00",
    "end_date": "2026-11-19", "end_time": "10:00"
  },
  "checkout_url": "https://www.kauti.fr/c/…",
  "card_saved": false,
  "terms_accepted_at": null,
  "authorized_amount": 0,
  "authorized_at": null,
  "authorization_expires_at": null,
  "automatic_release_at": "2026-11-21T09:00:00.000Z",
  "incident": null,
  "captured_amount": 0,
  "captured_at": null,
  "released_at": null,
  "source": "api",
  "created_at": "2026-10-02T09:12:44.381Z",
  "updated_at": "2026-10-02T09:12:44.381Z"
}

Pour essayer sans rien engager : une caution annulée avant que le locataire ait enregistré sa carte ne compte pas dans votre forfait.

Points d’accès

Les opérations sur une caution renvoient la caution telle qu'elle est après coup : c'est son statut qui dit si un encaissement a abouti. L'encaissement d'un incident se fait dans les 48 heures qui suivent sa déclaration. Le blocage se choisit à la création, avec "hold": true : Kauti le pose de lui-même au début de la location, ou dès l'enregistrement de la carte si elle a déjà commencé. Il ne peut pas être ajouté ensuite à une caution créée sans. La banque fixe son échéance, renvoyée dans authorization_expires_at (sept jours en général) ; si elle tombe avant la libération, le montant n'est garanti que jusque-là, et la carte reste enregistrée jusqu'à la libération.

Statuts d’une caution

Paiements

Un paiement est une somme que votre locataire règle une fois, par carte, sur votre compte Stripe : solde du séjour, ménage, frais. Les notifications portent data.payment au lieu de data.deposit. Commission Kauti : 0,5 % + 0,50 € HT par paiement réglé, 2,00 € HT minimum, sur votre facture Kauti ; les frais Stripe sont déduits du paiement. Un remboursement ne rend ni l'une ni les autres.

Notifications

Renseignez une adresse HTTPS dans Compte › API. À chaque changement de statut, Kauti y envoie un POST JSON : { id, object: "event", type, created_at, data: { deposit } }. Le journal des derniers envois, avec la réponse de votre serveur, est visible au même endroit.

Chaque envoi est signé. L'en-tête Kauti-Signature vaut t=<horodatage>,v1=<signature>, où la signature est le HMAC-SHA256, en hexadécimal, de <horodatage>.<corps brut> avec le secret affiché dans Compte › API. Rejetez tout envoi dont la signature ne correspond pas ou dont l'horodatage a plus de cinq minutes.

import crypto from "node:crypto";

// rawBody : le corps de la requête tel que reçu, sans le reformater.
function verifyKautiSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Erreurs

Une erreur répond { "error": { "code", "message" } } : le code est stable, à utiliser dans votre programme ; le message, en français, s'adresse à un humain.

Sécurité

• Des clés révocables

  Kauti ne conserve que l'empreinte de chaque clé : elle n'est affichée qu'une fois, à sa création. Une clé se révoque d'un clic.

• Réservées au propriétaire

  Seul le propriétaire du compte crée et révoque les clés et règle les notifications.

• Aucune carte dans l'API

  L'API ne voit jamais une carte bancaire : le locataire la saisit chez Stripe, sur la page de caution.

Vous éditez un logiciel ?