Associer les statuts de vérification aux états de votre produit

Votre produit doit changer d'état sur un seul champ :statusIl s'agit du résultat d'une vérification, et il prend l'une des dix valeurs suivantes :not_startedàapproved. MagasincheckStatusÀ côté, il enregistre les résultats des contrôles automatisés et constitue la seule explication en cas de divergence. Ces divergences sont plus fréquentes que prévu par les ingénieurs, et c'est intentionnel.

En pratique, cela signifie trois choses : cartographier chacun des dixstatusvaleurs à un seul état dans votre propre système, prenez la plus récentestatusde laverification.status_updatedUtilisez un webhook ou un système d'interrogation régulière plutôt que le premier événement reçu.reasonCode(Il ne faut jamais se fier uniquement au statut brut) pour déterminer les informations à communiquer au demandeur. La suite de cet article transforme ces informations en un tableau que vous pouvez utiliser et en un code que vous pouvez adapter.

Pourquoi y a-t-il deux champs au lieu d'un seul ?

Deux éléments distincts déterminent la vérification. Les contrôles automatisés lisent le document, consultent les registres gouvernementaux, comparent le visage et lisent la puce. Ensuite, les règles de décision de votre flux de travail, ou un membre de votre équipe, déterminent la marche à suivre concernant la personne. La documentation relative au cycle de vie de la vérification (s’ouvre dans un nouvel onglet) attribue un champ spécifique à chaque étape.

statusle processus s'effectue dans un ordre fixe, et la première règle applicable prévaut : la décision du réviseur, puis celle de votre flux de travail, puis les vérifications seules.checkStatusne change jamais à cause d'une règle ou d'un examinateur. Ainsi, un candidat dont le visage ne correspondait pas, mais qui a été approuvé par un examinateur après un appel vidéo, se retrouve avecstatus: "approved"etcheckStatus: "failed"Les deux affirmations sont vraies, et ne retenir que la première vous empêcherait d'expliquer ultérieurement pourquoi l'exception a été autorisée.

Comment chaque statut doit-il correspondre à votre produit ?

Voici un exemple de cartographie pour une application de prêt. Les états de compte et les messages sont donnés à titre d'exemple ; les colonnes de droite correspondent aux éléments à copier.

Deux choix de conception dans ce tableau méritent d'être copiés, même si vous renommez chaque État.

Premièrement, un état par valeur, même si deux valeurs se ressemblent . Il est tentant de se replier sur soi.in_reviewdansprocessingcar les deux signifient « attendez ». Il faut les distinguer.in_reviewcela signifie qu'une personne de votre équipe doit prendre une décision, ce qui constitue une mesure de file d'attente interne, tandis queprocessingLa plateforme fonctionne-t-elle ?

Deuxième,declinedest un état, avec la raison qui l'accompagne . Une pièce d'identité que la base de données gouvernementale ne possède pas est unedeclinedavecreasonCode: "identity_not_found"Il ne s'agit pas d'un statut distinct. Il faut se baser sur le code, et non sur une multiplication des états.

Qu'est-ce qui est réellement mis en attente par le traitement ?

En général, seuls les contrôles sont effectués. Mais lorsque votre flux de travail conditionne sa décision à un élément plus lent,processingpeut durer plus longtemps, et le point de terminaison d'état comprendwaitingOnpour dire quoi. Les valeurs incluent"screening"(des sanctions, PEP ou un filtre anti-médias négatifs) et"key_people"(les directeurs et les propriétaires d'une application commerciale finalisant leurs propres vérifications) ;nullCela signifie que les vérifications sont toujours en cours. La documentation relative aux points de terminaison d'état (s’ouvre dans un nouvel onglet) les répertorie.

Ce champ permet à votre écran de sélection des candidats d'afficher un message plus utile qu'une icône de chargement, et à votre équipe opérationnelle de comprendre pourquoi une candidature a été retenue.processingpendant deux jours.

Pourquoi la valeur verification.completed n'est-elle pas toujours la réponse finale ?

Parce qu'il décrit les vérifications, et non la décision. Les événementsverification.completed,.failed,.not_foundet.errorsont envoyées dès que les vérifications sont terminées. Si votre flux de travail comporte des règles de décision, cela se produit avant que le flux de travail n'ait pris sa décision, et leursstatusreflète uniquement les chèques.

Le verdict arrive ensuite.verification.status_updated, avecsource: "workflow"Le même événement se déclenche également lorsqu'un réviseur prend une décision dans le tableau de bord (source: "dashboard") ou votre système dorsal décide par le biais de l'examen API (source: "api"Il transportepreviousStatuset le nouveaustatuset contrairement à la plupart des événements, il est livré à plat plutôt qu'emballé dans undataobjet, comme l'explique la documentation sur les webhooks (s’ouvre dans un nouvel onglet) .

Un exemple concret permet de comprendre le piège. Un processus de sélection refuse toute personne figurant sur une liste de surveillance. Un candidat réussit tous les contrôles :verification.completedarrive avecstatus: "approved"Quelques secondes plus tard, l'attente liée au filtrage se résorbe et le flux de travail diminue.verification.status_updatedarrive avecstatus: "declined"etsource: "workflow"Si votre responsable a intégré le client dès le premier événement, vous avez intégré une personne que votre propre politique rejette.

La règle : si votre flux de travail comporte des règles de décision, traitez-les comme telles.verification.status_updated(ou un nouveau sondage) comme source destatusSans règles de décision, les vérifications se limitent à la décision etverification.completedCette version est définitive, sauf si un réviseur la modifie ultérieurement.

Que devez-vous dire au candidat ?

UtiliserreasonCodepour choisir le message et utiliserreasonsoigneusement.

Sur unfailedounot_foundvérifier,reasonCe document est destiné au demandeur : il décrit clairement les points non conformes et les démarches à suivre, sans mention de score, de seuil ou d’éléments tirés des dossiers gouvernementaux. Vous pouvez le présenter tel quel.

Sur unerrorrésultat,reasonCe texte est destiné à vous. Il peut contenir la mention « recharger votre solde » ou « contacter » Toden ", ce qui ne signifie rien pour un candidat. Affichez-lui un message générique et acheminez-le vers lereasonà votre équipe.

De nouveaux codes peuvent être ajoutés au fil du temps ; par conséquent, associez un code non reconnu à un message d'erreur générique plutôt qu'à une erreur dans votre code.

À quoi cela ressemble-t-il en code ?

Un gestionnaire qui applique les règles ci-dessus, en TypeScript.accountsLes appels ne sont que des espaces réservés à votre propre persévérance.

type Status =
  | 'not_started' | 'in_progress' | 'processing' | 'in_review'
  | 'awaiting_resubmission' | 'approved' | 'declined'
  | 'abandoned' | 'expired' | 'error';

const ACCOUNT_STATE: Record<Status, string> = {
  not_started: 'kyc_invited',
  in_progress: 'kyc_in_progress',
  processing: 'kyc_checking',
  in_review: 'kyc_manual_review',
  awaiting_resubmission: 'kyc_action_needed',
  approved: 'kyc_passed',
  declined: 'kyc_failed',
  abandoned: 'kyc_dropped',
  expired: 'kyc_link_expired',
  error: 'kyc_retry',
};

export async function applyVerificationStatus(event: {
  verificationId: string;
  status: Status;
  checkStatus?: string;
  reasonCode?: string | null;
  reason?: string | null;
}) {
  const state = ACCOUNT_STATE[event.status] ?? 'kyc_checking'; // unknown value: keep waiting
  await accounts.updateByVerificationId(event.verificationId, {
    kycState: state,
    kycStatus: event.status,
    kycCheckStatus: event.checkStatus ?? null, // the explanation, kept for audit
    kycReasonCode: event.reasonCode ?? null,
    kycReason: event.reason ?? null,
  });
}

Appelez-le des deux côtésverification.status_updatedLe gestionnaire et votre chemin d'interrogation, afin qu'ils ne puissent pas diverger. Dédupliquer les livraisons de webhook sur leX-Myaza-Deliveryen-tête avant de l'appeler.

Que se passe-t-il lorsqu'une vérification est renvoyée ?

Elle conserve son identifiant. Lorsqu'un examinateur renvoie une vérification et que le candidat soumet à nouveau sa demande, la même vérification déclenche une nouvelle tentative :attemptaugmente de un,checkStatusretour àpendinget les vérifications sont relancées. Votre mappage gère cela sans cas particuliers : le statut passe deawaiting_resubmissionàprocessinget se stabilise ensuite. Saisie de vos enregistrements surverificationIdCe qui permet cela, c'est que le résultat ne soit pas obtenu par une requête du type « dernière vérification pour cet utilisateur ».

Pour avoir une vue d'ensemble, incluant toutes les tentatives précédentes et toutes les décisions prises, lisezGET /api/kyc/verifications/:iddepuis votre serveur avec une clé secrète. Il renvoiereviewetstatusHistory, du plus récent au plus ancien, comme décrit dans la référence des résultats de vérification (s’ouvre dans un nouvel onglet) .

Liste de contrôle

• Un état de produit parstatusvaleur, avecin_reviewetprocessingmaintenus à l'écart.

• checkStatus,reasonetreasonCodestocké à côté destatus, toujours.

• Dernierstatustiré deverification.status_updatedou par sondage lorsque votre flux de travail comporte des règles de décision.

• Exemplaire du demandeur choisi parreasonCode;reasonaffiché uniquement surfailedetnot_found.

• InconnustatusoureasonCodeLes valeurs sont traitées comme « attendre » ou « erreur générique », jamais comme un plantage.

• Enregistrements saisis surverificationId, donc les nouvelles soumissions mettent à jour la même ligne.

Le hub pour développeurs permet de faire le lien entre les références de webhook et d'état utilisées ici.