Sessions hébergées

Une session hébergée est la façon la plus simple de recueillir des documents. Vous créez la demande côté serveur, puis vous demandez à Certivant une URL de session et la transmettez au demandeur. Certivant gère l'envoi des documents, la capture par caméra, la vivacité, les retours de l'OCR et les nouvelles tentatives : il ne vous reste qu'à attendre le webhook.

Quand utiliser une session

La plupart des intégrations utilisent des sessions. L'envoi de documents par API est une solution de contournement réservée à des cas particuliers.

Générer une URL de session

POST /api/v1/kyc/requests/:id/session-url    Portée : kyc:write

La demande doit être à l'état PENDING_UPLOAD.

Corps de la requête

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Réponse

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

L'URL contient un jeton signé à usage unique. Une fois expirée (ou après la soumission par le demandeur), elle n'est plus valide. Générez-en une nouvelle si le demandeur a besoin d'une autre tentative.

Le parcours du demandeur

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

Le demandeur n'a pas besoin de compte pour utiliser l'URL de session : Certivant ne lui attribue aucun identifiant de connexion. Il clique, effectue le parcours, puis quitte la page. Tout l'état est conservé sur la demande, et non sur une fiche utilisateur.

Image de marque et marque blanche

L'interface hébergée reprend les paramètres de marque blanche de votre organisation : logo, couleur de marque, courriel de support, domaine personnalisé si vous en avez configuré un. Configurez-les une seule fois dans Paramètres → Marque blanche du tableau de bord ; chaque session en hérite.

Domaines personnalisés

Par défaut, les URL des sessions et des formulaires hébergés se trouvent sur l'hôte Certivant partagé (app.certivant.com/s/…). Si vous souhaitez les avoir sur votre propre domaine (verify.yourcompany.com à la place), configurez un domaine personnalisé dans Paramètres → Marque blanche → Domaine personnalisé. Cela ne déplace que les liens destinés aux demandeurs : l'hôte de l'API et votre chemin de base /api/v1/kyc ne changent pas, et votre organisation reste identifiée par votre clé d'API.

Ordinateur ou mobile

La session est adaptative et fonctionne sur les téléphones, les tablettes et les ordinateurs. La capture des documents utilise la caméra de l'appareil sur mobile ; sur ordinateur, Certivant invite le demandeur à passer à son téléphone via un code QR afin que la vivacité et la numérisation des documents utilisent la meilleure caméra. Ce comportement est automatique : votre intégration n'a rien à détecter.

Ce qui se passe après la soumission

Lorsque le demandeur clique sur Soumettre sur la page hébergée :

1. Certivant appelle en interne POST /requests/:id/submit au nom du demandeur.
2. La demande passe à PROCESSING.
3. Le premier webhook est déclenché : kyc.request.processing.
4. Le traitement se termine (généralement en quelques secondes). Un second webhook est déclenché : kyc.request.approved, kyc.request.rejected ou kyc.request.escalated.
5. Si vous avez fourni redirectUrl, le demandeur y est redirigé. Sinon, il voit une page de remerciement.

Votre backend doit attendre le webhook : n'interrogez pas le point de terminaison de la demande pour détecter la fin du traitement. Voir Webhooks.

Réutiliser une URL de session après un rejet

Si la demande est rejetée et que vous appelez POST /requests/:id/resubmit, l'URL de session existante n'est pas réactivée. Générez-en une nouvelle :

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Envoyez ensuite la nouvelle URL au demandeur. Astuce : conservez le même externalRef afin que la ligne de votre base de données reste corrélée.

Les formulaires comme alternative

Si vous devez recueillir des données structurées (et non seulement des documents) — réponses à des questionnaires de conformité, détails sur l'origine des fonds, champs KYB supplémentaires — utilisez plutôt les Formulaires, ou en complément de la session. Les formulaires se trouvent dans le tableau de bord, à KYC → Formulaires, et chacun dispose d'une URL de soumission publique : https://app.certivant.com/forms/:slug.

Les formulaires créent automatiquement une demande KYC à la soumission, joignent les réponses du formulaire comme métadonnées et déclenchent les mêmes webhooks. Voir la documentation locataire sur les Formulaires pour la configuration. Les développeurs n'interagissent généralement pas avec les formulaires via l'API : le générateur de formulaires du tableau de bord est l'interface prévue.

Erreurs

• 400 BAD_REQUEST : la demande n'est pas à l'état PENDING_UPLOAD. Vous ne pouvez générer des URL de session que pour des demandes en attente de documents.
• 400 VALIDATION_ERROR : expiresInHours est hors de la plage 1 à 168, ou redirectUrl n'est pas une URL valide.

Notes de sécurité

• L'URL de session contient un jeton signé : quiconque possède l'URL peut effectuer la vérification. Traitez-la comme un lien de réinitialisation de mot de passe : envoyez-la directement au demandeur par un canal auquel lui seul a accès.
• Utilisez une valeur courte pour expiresInHours (24 ou 48) pour les parcours à haut risque. Ne choisissez une durée plus longue que lorsque le demandeur doit avoir le temps de rassembler ses documents.
• Lorsqu'une session expire sans avoir été utilisée, la demande sous-jacente reste à l'état PENDING_UPLOAD. Générez une nouvelle URL ou contactez le demandeur pour la lui renvoyer.