Concevoir votre produit en fonction des résultats de vérification asynchrones

Entre la soumission et le résultat final, votre application doit se trouver dans un état d'attente, déterminé par l'identifiant de vérification, géré par des événements provenant de votre serveur et capable de changer d'état à plusieurs reprises. Dès que le SDK appelsonSubmitIndique que la vérification a été créée. Ne précise pas si elle a réussi.

Cela paraît évident jusqu'à ce qu'une vérification reste en cours d'examen pendant une journée, soit renvoyée pour une nouvelle photo, soit de nouveau approuvée. Un produit conçu autour d'un simple rappel « succès ou échec » ne peut gérer ce type de situation. Un produit construit autour d'une petite machine à états la gère sans problème, sans cas particuliers.

Pourquoi le résultat ne peut-il pas être joint à la soumission ?

Les vérifications d'identité prennent des temps variables pour diverses raisons. Il faut lire un document, consulter un registre gouvernemental, comparer un visage. Ensuite, un système de décision (s’ouvre dans un nouvel onglet) peut être en attente sur un écran de surveillance, une entreprise peut attendre la vérification de l'identité de ses dirigeants, et un membre de votre équipe peut avoir besoin d'effectuer une vérification. Certaines de ces opérations ne prennent que quelques secondes, d'autres plusieurs jours.

Donc Toden renvoie dès que la vérification est créée, avec un statut deprocessinget indique à votre serveur comment la situation se résout via des webhooks (s’ouvre dans un nouvel onglet) ou une interrogation d'état (s’ouvre dans un nouvel onglet) . La question de conception pour votre produit est de savoir ce qu'il faut afficher et ce qu'il faut autoriser pendant cet intervalle.

Deux champs, deux questions

Chaque vérification soumise comporte deux champs d'état, et vous avez besoin des deux.

statusIl s'agit du résultat. C'est le domaine sur lequel vous agissez, et il utilise dix valeurs tout au long du cycle de vie :not_started,in_progress,processing,in_review,awaiting_resubmission,approved,declined,abandoned,expiredeterror.

checkStatusVoici ce que les contrôles automatisés ont révélé :pending,verified,failed,not_foundouerrorLes règles de décision et les réviseurs ne les changent jamais.

Ils sont en désaccord dès qu'une décision autre que celle relative aux vérifications est prise. Une vérification peut être effectuée.approvedaveccheckStatus: "failed"Parce qu'un examinateur a accepté un selfie dont la note était légèrement inférieure à la note de passage, en raison d'une mauvaise luminosité. Conservez les deux. Le jour où quelqu'un demandera pourquoi ce client a été autorisé à passer,checkStatusetreasonCodeVoici votre réponse.

Le statut est décidé selon un ordre fixe : la décision du réviseur prévaut, puis celle de votre flux de travail, puis les vérifications seules.

Associer le statut à ce que voit l'utilisateur

La plupart des produits ne nécessitent qu'une poignée d'états visibles par l'utilisateur. Voici, comme point de départ, une correspondance avec les valeurs documentées :

La même règle s'applique au code, sous la forme d'une fonction unique que vos écrans peuvent partager :

type UiState = "checking" | "action_needed" | "verified" | "not_verified" | "start_again";

function uiStateFor(status: string): UiState {
  switch (status) {
    case "approved": return "verified";
    case "declined": return "not_verified";
    case "awaiting_resubmission": return "action_needed";
    case "abandoned":
    case "expired":
    case "error": return "start_again";
    default: return "checking"; // processing, in_review and anything unrecognised
  }
}

La branche par défaut est intentionnelle. Elle couvrenot_started,in_progress,processingetin_reviewet si une valeur que vous ne reconnaissez pas l'atteint, « vérification en cours » est une réponse plus sûre qu'un échec.

Formuler un déclin

Sur unfailedounot_foundrésultat,reasonIl s'agit d'une phrase rédigée à l'intention du candidat, sans aucune note ni seuil, et vous pouvez la présenter telle quelle.reasonCodeest le jeton stable sur lequel se baser :document_expiredpourrait déclencher « Télécharger un document actuel »,selfie_mismatchune invitation à reprendre le selfie avec une meilleure lumière.errorrésultatreasonSi le message vous est adressé, par exemple concernant votre solde créditeur, affichez un message générique et transmettez le motif à votre équipe.

Distinguer « quelques secondes » de « quelques jours »

processingCela concerne à la fois un document en cours de lecture et une décision affichée dans une liste de surveillance. Le point de terminaison d'étatwaitingOnce champ indique lequel :nullpendant que les vérifications sont toujours en cours,"screening","key_people"pour une entreprise qui attend ses administrateurs et propriétaires, ou"address_presence"Pour une vérification d'adresse qui s'étend sur plusieurs jours (lorsqu'elle est activée), utilisez cette option pour définir les attentes (« cela prend généralement une minute » plutôt que « nous vous enverrons un e-mail ») et considérez toute valeur inconnue comme un délai d'attente non encore pris en compte.

À quel signal se fier, et quand ?

Vous recevez trois signaux, et ils n'ont pas tous la même autorité.

1. Le signal du client .SDK 'sonSubmitou d'une page hébergéesubmittedCet événement se déclenche lorsque le demandeur termine le processus. Utilisez-le pour afficher immédiatement l'écran d'attente. Ne l'utilisez pas pour accorder des autorisations.

2. Des webhooks sont envoyés à votre serveur. Ce sont les enregistrements. Mettez à jour votre base de données à partir de ces enregistrements et affichez la modification à l'écran de l'utilisateur.

3. Le point de terminaison d'état. GET /api/kyc/status/:verificationIdRenvoie l'état actuel avec une clé publiable et ne contient aucune donnée personnelle, score ou résultat. Utilisez-le pour combler un manque, par exemple lorsque l'application redémarre avant que votre serveur n'ait envoyé de données.

Le premier webhook n'est pas toujours le dernier

Si votre flux de travail comporte des règles de décision,verification.completedest envoyé une fois les vérifications terminées, avant que le flux de travail n'ait pris sa décision.statusreflète uniquement les vérifications. Le verdict du flux de travail arrive ensuite.verification.status_updatedavecsource: "workflow"C’est sur cette base qu’il convient d’agir. Ultérieurement, un réviseur peut décider ou modifier une décision antérieure, et chaque modification constitue une nouvelle décision.verification.status_updated.

Les livraisons sont tentées à nouveau indépendamment et peuvent arriver dans le désordre, veuillez donc conserver lechangedAtVous conservez la modification et ignorez toute modification antérieure. Sans règles de décision, les vérifications constituent la décision et le statut surverification.completedCela reste inchangé sauf si un réviseur le modifie ultérieurement.

Les nouvelles soumissions conservent le même identifiant.

Lorsqu'un examinateur renvoie une vérification, le candidat ne refait que les étapes demandées, et sa nouvelle soumission effectue la même vérification. Vous recevez alors un autre événement de résultat avec les mêmes informations.verificationId,attemptcompté, etcheckStatusretour àpendingPendant que les vérifications se relancent, mettez à jour l'enregistrement. Créer une nouvelle ligne pour chaque événement vous ferait avoir deux clients au lieu d'un seul.

Sondages, si nécessaire

Les webhooks doivent être déployés en production. L'interrogation périodique sert à combler les lacunes : un écran mobile qui se rouvre ou un environnement où la réception de webhooks est indisponible pour le moment. Si vous utilisez l'interrogation périodique :

• Reculez, en commençant par quelques secondes et en augmentant progressivement l'intervalle, et arrêtez-vous une fois la situation stabilisée.

• N'oubliez pas la limite par défaut documentée de 100 requêtes par tranche de 15 minutes et par client, et lisez la documentation.RateLimit-RemainingetRateLimit-ResetEn-têtes plutôt que de deviner.

• Interrogez le moins de sources possible. Une douzaine d'écrans ouverts interrogeant chacun la même source de vérification génèrent douze fois plus de trafic pour une seule réponse.

Nouvelles tentatives en cours

Le problème persiste également du côté de la soumission. Un réseau mobile ne reçoit pas la réponse à l'appel de création, et l'application ignore si la vérification a été effectuée. Envoyez une réponse stable.metadata.requestIdpour chaque vérification logique et la réutiliser lors de toute nouvelle tentative. API Elle renvoie la vérification existante au lieu d'en créer une seconde et ne facture jamais deux fois.

Une visite guidée

Prenons l'exemple d'une application d'épargne hypothétique dont le processus vérifie chaque utilisateur authentifié. Un candidat soumet sa demande sur son téléphone à 9 h. L'application reçoit la demande.onSubmitet affiche « Nous vérifions vos informations ». Quelques secondes plus tard, le serveur reçoitverification.completedaveccheckStatus: "verified". C'eststatuslecturesapprovedEn effet, cet événement ne reflète que les vérifications, et le système n'accorde donc encore rien : le flux de travail est toujours en attente à l'écran, et une vérification d'état le confirme.processingavecwaitingOn: "screening"L'écran affiche une correspondance potentielle, le flux de travail l'achemine vers la zone de vérification, etverification.status_updatedarrive avecin_reviewL'application modifie son message pour indiquer que l'examen peut prendre plus de temps. À 14h30, un responsable de la conformité lève le faux positif et approuve ; un secondverification.status_updatedarrive avecapprovedet le système dorsal permet les dépôts et envoie une notification push.

Rien dans cette séquence ne nécessitait un traitement particulier. Il s'agit d'un seul enregistrement, indexé par un seul identifiant, mis à jour successivement par chaque événement.

Liste de contrôle pour votre état en attente

1. Créez un enregistrement local indexé surverificationIdle momentonSubmitincendies.

2. Mettez-le à jour uniquement depuis votre backend, via des webhooks.

3. Agir surstatus; magasincheckStatus,reasonetreasonCodeà côté.

4. Restez informé(e) des dernières actualitéschangedAtet ignorer les modifications antérieures.

5. Traiter le statut inconnu etwaitingOnvaleurs comme « vérification en cours ».

6. Lors d'une nouvelle soumission, mettez à jour l'enregistrement et indiquez la tentative.

7. La parole décline dereasonCodeet ne jamais montrer unerrorraison au demandeur.

8. RéutiliserrequestIdlors des nouvelles tentatives, et interroger uniquement pour combler les lacunes.