Documentation Développeur

API & Webhooks Kaution.io

Intégrez Kaution.io à votre ERP ou système d'information. Créez des cautions, suivez leur statut, encaissez et libérez. Le tout via une API REST sécurisée et des webhooks temps réel.

REST API v1

Webhooks sortants

HMAC SHA-256

Sandbox intégré

Sommaire

1. Authentification 2. Environnement Sandbox / Test 3. Créer une caution 4. Lister les cautions 5. Récupérer une caution 6. Encaisser (capture) 7. Libérer une caution 7b. Pré-autoriser une carte enregistrée 8. Statuts & Cycle de vie 9. Webhooks sortants 10. Codes d'erreur

URL de base

Toutes les requêtes API doivent être envoyées à l'URL de base suivante :

https://kaution.io/functions/v1/api-v1

1. Authentification

L'API Kaution.io utilise des clés API au format kio_....Chaque clé est liée à un compte marchand et permet d'agir sur ses cautions uniquement.

Obtenir une clé API

Les clés API se créent depuis le tableau de bord Kaution.io, onglet « Clés API ».. La clé complète n'est affichée qu'une seule fois à la création — conservez-la en lieu sûr.

Utilisation

Incluez votre clé API dans l'en-tête Authorization de chaque requête :

Authorization: Bearer kio_votre_cle_api

Sécurité

Les clés sont hachées (SHA-256) et stockées de façon irréversible
Une clé peut être révoquée ou réactivée à tout moment depuis le tableau de bord
Ne partagez jamais une clé API publiquement (GitHub, Slack, etc.)

2. Environnement Sandbox / Test

Kaution.io dispose d'un environnement de test intégré via Stripe. Vous pouvez tester l'intégralité du flux (création, validation, capture, libération, webhooks) sans aucun mouvement d'argent réel.

Cartes de test Stripe

Utilisez les cartes de test suivantes dans l'environnement sandbox :

Numéro de carte	Scénario
4242 4242 4242 4242	Paiement réussi
4000 0027 6000 3184	Pré-autorisation réussie (caution)
4000 0000 0000 9995	Fonds insuffisants (échec)
4000 0000 0000 0069	Carte expirée (échec)

Date d'expiration : toute date future (ex: 12/34) — CVC : any 3 digits

Passage en production

Le passage en production ne nécessite aucune modification de code côté ERP. Il suffit que les clés Stripe de la plateforme et du compte marchand connecté soient en mode production (sk_live_...).L'API, les webhooks et tous les endpoints fonctionnent à l'identique.

3. Créer une caution / demande de pré-autorisation

Crée une nouvelle caution (pré-autorisation / empreinte bancaire) ou un paiement direct. Un lien de paiement Stripe est généré et retourné dans la réponse.

POST

/cautions

Paramètres du corps (JSON)

Champ	Type	Requis	Description
client_name	string	Oui	Nom du client (max 120)
client_email	string	Oui	Email valide du client
client_phone	string	Non	Téléphone (max 32)
amount	integer	Oui*	Montant en centimes (min 50, max 1 000 000 00). *Non requis en mode `tokenisation`
description	string	Non	Description (max 500)
mode	string	Non	`"caution"` (défaut), `"paiement"` ou `"tokenisation"`

Modes

mode: "caution"

Pré-autorisation (empreinte bancaire). Les fonds sont bloqués mais non débités. Capturez ou libérez ultérieurement. Valide 7 jours. La carte est automatiquement tokenisée pour une réutilisation ultérieure via /authorize.

mode: "paiement"

Paiement direct. Le montant est encaissé immédiatement (capture automatique). Le statut passe directement à saisie. La carte est automatiquement tokenisée pour une réutilisation ultérieure via /authorize.

mode: "tokenisation"

Enregistrement de carte seule. Aucun blocage de plafond. Utilisez ensuite POST /cautions/:id/authorize pour pré-autoriser le montant souhaité au bon moment.

Exemple de requête

curl -X POST https://kaution.io/functions/v1/api-v1/cautions \
  -H "Authorization: Bearer kio_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Jean Dupont",
    "client_email": "jean@exemple.fr",
    "client_phone": "0612345678",
    "amount": 50000,
    "description": "Caution location voiture",
    "mode": "caution"
  }'

Réponse (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "en_attente",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "short_url": "https://kaution.io/k/Ab3x9Q",
  "mode": "caution",
  "amount": 50000,
  "client_name": "Jean Dupont",
  "client_email": "jean@exemple.fr",
  "created_at": "2026-09-28T10:00:00.000Z"
}

Le checkout_url doit être envoyé au client pour qu'il valide sa carte.Le short_url est une version raccourcie utilisable en QR code.

4. Lister les cautions

Récupère la liste des cautions du compte marchand, avec pagination et filtre par statut.

GET

/cautions

Paramètres de requête

Paramètre	Type	Défaut	Description
limit	integer	50	Nombre de résultats (max 100)
offset	integer	0	Décalage pour la pagination
status	string	—	Filtrer par statut (en_attente, validee, saisie, liberee, expiree)

Exemple

curl https://kaution.io/functions/v1/api-v1/cautions?limit=10&status=validee \
  -H "Authorization: Bearer kio_votre_cle_api"

Réponse (200 OK)

{
  "cautions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_name": "Jean Dupont",
      "client_email": "jean@exemple.fr",
      "amount": 50000,
      "status": "validee",
      "mode": "caution",
      "description": "Caution location voiture",
      "created_at": "2026-09-28T10:00:00.000Z",
      "hold_expires_at": "2026-10-05T10:00:00.000Z",
      "captured_amount": null,
      "short_code": "Ab3x9Q"
    }
  ]
}

5. Récupérer le statut d'une caution

Récupère les détails complets d'une caution spécifique, incluant son statut, le montant, les informations client et les références Stripe.

GET

/cautions/:id

Exemple

curl https://kaution.io/functions/v1/api-v1/cautions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer kio_votre_cle_api"

Réponse (200 OK)

{
  "caution": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_name": "Jean Dupont",
    "client_email": "jean@exemple.fr",
    "client_phone": "0612345678",
    "amount": 50000,
    "captured_amount": null,
    "status": "validee",
    "mode": "caution",
    "description": "Caution location voiture",
    "short_code": "Ab3x9Q",
    "stripe_checkout_session_id": "cs_test_...",
    "stripe_payment_intent_id": "pi_...",
    "stripe_customer_id": "cus_...",
    "hold_expires_at": "2026-10-05T10:00:00.000Z",
    "created_at": "2026-09-28T10:00:00.000Z"
  }
}

6. Encaisser une caution (capture)

Encaisse tout ou partie d'une caution validée (pré-autorisation). Le montant est débité de la carte du client. La caution doit être au statut validee.

POST

/cautions/:id/capture

Paramètres du corps (JSON)

Champ	Type	Requis	Description
amount	integer	Non	Montant à capturer en centimes. Si omis, capture totale. Si inférieur au montant de la caution, capture partielle.

Exemple — capture totale

curl -X POST https://kaution.io/functions/v1/api-v1/cautions/a1b2c3d4/capture \
  -H "Authorization: Bearer kio_votre_cle_api" \
  -H "Content-Type: application/json"

Exemple — capture partielle (200€ sur 500€)

curl -X POST https://kaution.io/functions/v1/api-v1/cautions/a1b2c3d4/capture \
  -H "Authorization: Bearer kio_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 20000 }'

Réponse (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "saisie",
  "captured_amount": 20000
}

7. Libérer une caution

Libère une caution validée. Les fonds bloqués sur la carte du client sont immédiatement débloqués. Aucun débit n'est effectué. La caution doit être au statut validee.

POST

/cautions/:id/release

Exemple

curl -X POST https://kaution.io/functions/v1/api-v1/cautions/a1b2c3d4/release \
  -H "Authorization: Bearer kio_votre_cle_api"

Réponse (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "liberee"
}

7b. Pré-autoriser une carte enregistrée

Après n'importe quelle caution dont la carte a été enregistrée (mode tokenisation,caution ou paiement), utilisez cet endpoint pour pré-autoriser un montant sur la carte enregistrée — sans action du client. La caution passe en mode cautionavec une pré-autorisation Stripe classique (valide 7 jours).

POST

/cautions/:id/authorize

Paramètres du corps (JSON)

Champ	Type	Requis	Description
amount	integer	Oui	Montant à pré-autoriser en centimes (min 50)
description	string	Non	Description (max 500)

Exemple de requête

curl -X POST https://kaution.io/functions/v1/api-v1/cautions/a1b2c3d4/authorize \
  -H "Authorization: Bearer kio_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "description": "Caution saison août 2026"
  }'

Réponse (200 OK)

{
  "success": true,
  "payment_intent_id": "pi_...",
  "caution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "validee",
  "amount": 500000
}

Cas d'usage : tokenisation différée

Ce endpoint permet le flux « tokeniser un jour, pré-autoriser un autre jour » :

Créez une caution en mode: "tokenisation" → le client enregistre sa carte (aucun blocage)
Plus tard, appelez POST /cautions/:id/authorize avec le montant → pré-autorisation sans action du client
Ensuite, utilisez capture ou release comme pour une caution classique

Cas d'usage : réautorisation après paiement ou caution

La carte est automatiquement sauvegardée lors d'un paiement ou d'unecaution. Vous pouvez donc pré-autoriser un nouveau montant sur la même carte sans demander au client de ressaisir sa carte :

Créez une caution en mode: "paiement" ou mode: "caution" → le client paie, la carte est tokenisée
Plus tard, appelez POST /cautions/:id/authorize avec un nouveau montant → pré-autorisation sans action du client
Ensuite, utilisez capture ou release comme pour une caution classique

8. Statuts & Cycle de vie

Chaque caution passe par un cycle de vie défini. Le statut est accessible via l'API (GET /cautions/:id) et via les webhooks.

en_attenteEn attente

valideeValidée

saisieSaisie (encaissée)

libereeLibérée

en_attente — En attente

La caution a été créée. Le client n'a pas encore validé sa carte sur la page Stripe Checkout.

validee — Validée (pré-autorisée)

Le client a validé sa carte. Les fonds sont bloqués (caution) ou encaissés (paiement). La pré-autorisation expire après 7 jours.

saisie — Saisie (encaissée)

Le montant (total ou partiel) a été capturé. Les fonds sont transférés au marchand.

liberee — Libérée

La caution a été libérée. Les fonds bloqués sont rendus au client. Aucun débit.

9. Webhooks sortants

Kaution.io envoie des notifications HTTP POST vers vos endpoints configurés lorsqu'un événement se produit sur une caution. Les webhooks se configurent depuis le tableau de bord, onglet « Webhooks ».

Événements disponibles

Événement	Déclenchement
deposit.requested	Une caution est créée (lien de paiement généré)
deposit.authorized	Le client a validé sa carte (pré-autorisation confirmée)
deposit.captured	La caution a été encaissée (totale ou partielle)
deposit.released	La caution a été libérée (fonds rendus au client)

Format du payload

Chaque webhook envoie un corps JSON au format suivant :

{
  "event": "deposit.authorized",
  "data": {
    "caution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_name": "Jean Dupont",
    "client_email": "jean@exemple.fr",
    "amount": 50000,
    "description": "Caution location voiture",
    "mode": "caution",
    "status": "validee"
  },
  "timestamp": "2026-09-28T10:05:00.000Z"
}

En-têtes HTTP

En-tête	Description
Content-Type	application/json
Kaution-Event	Type d'événement (ex: deposit.authorized)
Kaution-Webhook-Signature	Signature HMAC pour vérification (voir ci-dessous)

Vérification de la signature (HMAC SHA-256)

Chaque webhook est signé avec HMAC SHA-256. L'en-tête Kaution-Webhook-Signaturecontient t=timestamp,v1=signature. Pour vérifier :

// Exemple de vérification (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts.t;
  const v1 = parts.v1;

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // Comparaison sécurisée (protection contre timing attacks)
  return crypto.timingSafeEqual(
    Buffer.from(v1, 'hex'),
    Buffer.from(expectedSig, 'hex')
  );
}

// Dans votre handler Express:
// const rawBody = req.rawBody; // body brut (non parsé)
// const sig = req.headers['kaution-webhook-signature'];
// const secret = 'votre_secret_webhook';
// if (!verifyWebhookSignature(rawBody, sig, secret)) {
//   return res.status(401).send('Signature invalide');
// }

Le secret du webhook est généré automatiquement à la création et visible dans le tableau de bord.

Recommandations de réception

Répondez avec un statut 200 rapidement (sous 10 secondes)
Traitez les événements de façon idempotente (un même événement peut être reçu plusieurs fois)
En cas d'échec, Kaution.io effectue jusqu'à 3 tentatives avec backoff (1s, 5s, 25s)
L'historique des livraisons est visible dans le tableau de bord

10. Codes d'erreur

Code HTTP	Message	Cause
400	Paramètres invalides	Champ manquant, format incorrect, montant hors limites
401	Clé API invalide ou révoquée	Clé manquante, incorrecte ou désactivée
403	Quota mensuel atteint / Aucun abonnement	Limite du plan atteinte ou abonnement inactif
404	Caution introuvable	ID inexistant ou n'appartenant pas au marchand
500	Erreur serveur	Erreur Stripe ou problème technique interne

Format d'erreur

{
  "error": "Montant invalide (en centimes, 50 minimum)"
}

Récapitulatif des endpoints

POST

/cautionsCréer une caution, un paiement ou une tokenisation

GET

/cautionsLister les cautions (pagination + filtre)

GET

/cautions/:idRécupérer une caution et son statut

POST

/cautions/:id/captureEncaisser (total ou partiel)

POST

/cautions/:id/authorizePré-autoriser un montant sur une carte enregistrée

POST

/cautions/:id/releaseLibérer la caution

Prêt à intégrer Kaution.io ?

Créez un compte, générez une clé API et commencez à tester en sandbox dès maintenant.