Aller au contenu

Sessions KYC hébergées

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 »
ChampTypeObligatoireDescription
formCodestringouiCode du formulaire KYC à utiliser (ex. kyc-client-wallet). Les écritures KYC_CLIENT_WALLET et kyc-client-wallet sont acceptées.
externalRefstringconseilléIdentifiant de la personne dans votre système (190 caractères max). Repris dans les webhooks et la redirection.
redirectUrlstringnonOù renvoyer la personne à la fin : https://… ou schéma d’application (monapp://kyc/retour).
webhookUrlstringnonURL qui reçoit les événements de cette session. Les abonnements webhook de l’organisation les reçoivent aussi.
prefillobjetnonValeurs pré-remplies, par clé de champ du formulaire (ex. first_name). Elles complètent la saisie sans l’écraser.
metadataobjetnonDonnées libres renvoyées telles quelles dans les webhooks (ex. identifiant de commande).
localestringnonLangue du parcours : fr (défaut) ou en.
expiresInMinutesentiernonValidité du lien : de 5 minutes à 7 jours (10 080). Défaut : 24 heures.
ChampDescription
idIdentifiant de la session
urlLien de vérification à ouvrir par la personne
statusCREATED
expiresAtDate d’expiration du lien
signingSecretSecret de signature des webhooks et de la redirection. Renvoyé une seule fois.
submissionId, providerIdDossier 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.

  • 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.