Sessions KYC hébergées
This content is not available in your language yet.
Une session représente une vérification pour une personne : un lien unique, son parcours, ses contrôles et sa décision. Elle crée aussi le dossier correspondant dans la console admin, que vos agents retrouvent dans KYC → Dossiers à vérifier.
Créer une session POST /v1/kyc/sessions
Section intitulée « Créer une session »| Champ | Type | Obligatoire | Description |
|---|---|---|---|
formCode | string | oui | Code du formulaire KYC à utiliser (ex. kyc-client-wallet). Les écritures KYC_CLIENT_WALLET et kyc-client-wallet sont acceptées. |
externalRef | string | conseillé | Identifiant de la personne dans votre système (190 caractères max). Repris dans les webhooks et la redirection. |
redirectUrl | string | non | Où renvoyer la personne à la fin : https://… ou schéma d’application (monapp://kyc/retour). |
webhookUrl | string | non | URL qui reçoit les événements de cette session. Les abonnements webhook de l’organisation les reçoivent aussi. |
prefill | objet | non | Valeurs pré-remplies, par clé de champ du formulaire (ex. first_name). Elles complètent la saisie sans l’écraser. |
metadata | objet | non | Données libres renvoyées telles quelles dans les webhooks (ex. identifiant de commande). |
locale | string | non | Langue du parcours : fr (défaut) ou en. |
expiresInMinutes | entier | non | Validité du lien : de 5 minutes à 7 jours (10 080). Défaut : 24 heures. |
| Champ | Description |
|---|---|
id | Identifiant de la session |
url | Lien de vérification à ouvrir par la personne |
status | CREATED |
expiresAt | Date d’expiration du lien |
signingSecret | Secret de signature des webhooks et de la redirection. Renvoyé une seule fois. |
submissionId, providerId | Dossier créé dans la console admin |
Lire une session GET /v1/kyc/sessions/{id}
Section intitulée « Lire une session »Renvoie l’état complet : status, decision, riskScore, checks (chaque contrôle avec son résultat), aiReview (lecture du document par Réglia), attempts, dates (openedAt, submittedAt, decidedAt), decidedBy (AUTO ou AGENT), decisionReason et l’état de livraison du webhook.
Utilisez cet appel pour un contrôle ponctuel ; pour suivre l’avancement, préférez les webhooks.
Lister les sessions d’une personne GET /v1/kyc/sessions?externalRef=…
Section intitulée « Lister les sessions d’une personne »Renvoie toutes les sessions créées pour un externalRef, de la plus récente à la plus ancienne. Pratique pour savoir si un client a déjà une vérification en cours avant d’en créer une nouvelle.
Annuler une session POST /v1/kyc/sessions/{id}/cancel
Section intitulée « Annuler une session »Le lien devient inutilisable et la session passe à CANCELLED. À utiliser quand le client abandonne côté application ou quand vous recréez un lien.
Bonnes pratiques
Section intitulée « Bonnes pratiques »- Une session par tentative de vérification. Si le lien expire, créez-en une nouvelle plutôt que de réutiliser l’ancienne.
- Préremplissez ce que vous savez déjà (nom, téléphone) : le parcours est plus court et le contrôle « Cohérence avec votre application » compare ces valeurs à la pièce.
- Ne déduisez pas le résultat de la redirection seule : la personne peut la manipuler. La source de vérité est le webhook signé ou l’appel
GET.