Intégration guidée par les vérifications

Créez des parcours KYC et de vérification d’identité pilotés par les contrôles avec le SDK Web ComplyCube.

Vue d'ensemble

Ce guide vous accompagne dans l'intégration du SDK Web avec ComplyCube en utilisant l'approche pilotée par les vérifications, vous donnant un contrôle direct sur les étapes de vérification individuelles.

Pour un exemple rapide à copier-coller, utilisez notre assistant d’intégration.

Vous consultez le piloté par des vérifications guide SDK - une approche qui offre un contrôle détaillé mais qui convient mieux aux partenaires ou cas d’utilisation avancés. Nous recommandons d’utiliser l’intégration des flux de travail pour la plupart des implémentations.

Flux d'intégration

Le SDK Web s'exécute dans votre frontend, mais s'appuie sur votre backend pour créer des jetons sécurisés. Voici comment cela fonctionne :

Créer un client

Enregistrez un nouveau client (c.-à-d. le client) en utilisant l'API ComplyCube

Générez un jeton SDK

Votre backend demande un jeton JWT lié à ce client.

Importez et montez le SDK

Ajoutez les fichiers JS et CSS, puis montez le SDK dans votre application web.

Capturez des documents, des vidéos et des selfies

Le SDK guide votre client à travers les étapes requises.

Effectuer les contrôles de vérification

Les données capturées sont envoyées en toute sécurité à ComplyCube pour les vérifications, et les résultats sont fournis en temps réel via l’API ou les webhooks.

Guide d'intégration

Créer un client

Chaque parcours de vérification commence par un client (c'est-à-dire le client). Utilisez l'API pour créer le client.

Exemple de requête

curl -X POST https://api.complycube.com/v1/clients \\
     -H 'Authorization: <YOUR_API_KEY>' \\
     -H 'Content-Type: application/json' \\
     -d '{
          "type": "person",
          "email": "john.doe@example.com",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "john.doe@example.com",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'john.doe@example.com',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => 'john@doe.com',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "john@doe.com",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newClient);

Exemple de réponse

La réponse contiendra un identifiant (l'identifiant du client). Il est requis pour l'étape suivante.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "john.doe@example.com",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

Voir Référence de l'API Clients pour en savoir plus.

Générez un jeton SDK

Votre backend doit créer un jeton SDK pour chaque nouveau parcours. Ce jeton associe la session du SDK au client. Les jetons sont de courte durée et ne doivent pas être réutilisés.

Exemple de requête

curl -X POST https://api.complycube.com/v1/tokens \\
     -H 'Authorization: <YOUR_API_KEY>' \\
     -H 'Content-Type: application/json' \\
     -d '{
          "clientId":"CLIENT_ID",
          "referrer": "https://www.example.com/*"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    referrer: "https://www.example.com/*"
});

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

token = cc_api.tokens.create('CLIENT_ID','https://www.example.com/*')

 use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$report = $ccapi->tokens()->generate('CLIENT_ID', 'https://www.example.com/*');

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  referrer = "https://www.example.com/*"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Exemple de réponse

{
    "token": "<CLIENT_TOKEN>"
}

Voir Référence de l'API du jeton SDK pour en savoir plus.

Importer le SDK

Pour importer notre SDK Web, vous devez l'inclure dans le code HTML de votre page cible :

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importation de la bibliothèque JavaScript -->
    <script src="complycube.min.js"></script>

    <!-- Importation du CSS par défaut -->
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
     <!-- C'est ici que le SDK Web sera monté -->
    <div id="complycube-mount"></div>
  </body>
</html>

Chargement du SDK avec intégrité (Facultatif)

Pour plus de sécurité, vous pouvez charger le SDK Web ComplyCube de manière facultative à l’aide de Intégrité des sous-ressources (SRI). Cela permet au navigateur de vérifier que les fichiers JavaScript et CSS n’ont pas été modifiés en les validant à l’aide de sommes de contrôle cryptographiques.

Récupérer les dernières valeurs d’intégrité du SDK

Pour vous assurer d’utiliser toujours la dernière version prise en charge du SDK et les derniers hachages d’intégrité, récupérez les métadonnées des ressources depuis le point de terminaison d’informations du SDK Web.

Exemple de requête

curl -X POST https://api.complycube.com/v1/webSdk/latest \
     -H 'Authorization: <YOUR_API_KEY>'

Exemple de réponse

La réponse inclut les URL et les valeurs d’intégrité correspondantes pour les ressources JavaScript et CSS.

{
  "js": {
    "url": "<JAVASCRIPT_ASSET_URL>/complycube.min.js",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  },
  "css": {
    "url": "<CSS_ASSET_URL>/style.css",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  }
}

Importer le SDK à l’aide d’attributs d’intégrité

Utilisez les valeurs renvoyées pour charger le SDK dans votre HTML avec integrity et crossorigin attributs :

<!DOCTYPE html>
<html>
  ...
  <head>
    <!-- Importation de la bibliothèque JavaScript -->
    <script
      src="<JAVASCRIPT_ASSET_URL>/sdk.min.js"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
    </script>

    <!-- Importation du CSS par défaut -->
    <link
      rel="stylesheet"
      href="<CSS_ASSET_URL>/style.css"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
  </link>
  </head>
  
  <!-- C'est ici que le SDK Web sera monté -->
  <body>
    <div id="complycube-mount"></div>
  </body>
</html>

Remarques

L’utilisation du SRI est facultative, mais recommandée pour les environnements avec des exigences de sécurité plus strictes.
L’attribut crossorigin="anonymous" est requis lors de l’utilisation de SRI avec des ressources servies depuis une origine différente.
Les valeurs d’intégrité peuvent changer lorsque le SDK est mis à jour. Récupérez toujours les dernières valeurs depuis le point de terminaison.

Les liens vers complycube.min.js et style.css se trouvent dans votre portail développeurs.

Monter le SDK

Avec le jeton SDK généré, le SDK Web peut être initialisé dans votre frontend à l'aide du code JavaScript suivant :

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  stages: [
    'intro',
    'documentCapture',
    {
      name: 'faceCapture',
      options: {
        mode: 'video'
      }
    },
    'completion'
  ],
  onComplete: function(data) {
    // En utilisant les attributs de données renvoyés, demandez à votre
    // serveur backend d'effectuer les vérifications ComplyCube nécessaires
    console.info('Capture complete');
  },
  onModalClose: function() {
    // Gérer la tentative de fermeture de la modale
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Demander un nouveau jeton SDK
    } else {
      // Gérer les autres erreurs
      console.error(message);
    }
  }
});

Les paramètres de montage du SDK sont décrits dans la section des paramètres du SDK ci-dessous.

Politique de referrer

Pour permettre une communication réussie entre le SDK et nos serveurs, l' Referrer Policy de votre page web doit être défini sur strict-origin-when-cross-origin. Cela garantit que les informations de referrer sont transmises de manière sécurisée lors des requêtes HTTP.

Vous pouvez soit le faire par programmation, soit l'ajouter directement à la page web comme suit : <meta name="referrer" content="strict-origin-when-cross-origin">

Effectuer des vérifications

En utilisant les données renvoyées par le SDK, via le onComplete callback, vous pouvez maintenant demander à votre serveur backend d'exécuter les vérifications appropriées à l'aide du créer un endpoint de vérification.

Par exemple, utilisez :

documentCapture.documentId pour lancer une vérification de document.
documentCapture.documentId et faceCapture.livePhotoId pour lancer une vérification d'identité.
documentCapture.documentId et faceCapture.liveVideoId pour lancer une vérification d'identité renforcée.
poaCapture.documentId pour lancer une vérification de justificatif de domicile.

Si vous avez configuré des webhooks comme décrit dans notre guide des webhooks, vous serez informé lorsqu'une vérification sera terminée.

Pour récupérer les résultats de la vérification, vous pouvez effectuer une requête GET requête de vérification.

Exemple de requête

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \\
     -H 'Authorization: <YOUR_API_KEY>'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const check = await complycube.check.get("CHECK_ID");

using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var check = await checkApi.GetAsync("CHECK_ID");

Référence du SDK

Cette section décrit tous les paramètres configurables, les callbacks, les méthodes de cycle de vie et les options de branding disponibles dans le SDK Web ComplyCube.

Paramètres

Option

Description

token

Le jeton SDK généré par votre backend. Il est obligatoire. Type: string

containerId

L'ID de l'élément conteneur où le SDK est monté. Il doit s'agir d'un élément vide.

Type : string Valeur par défaut: complycube-mount

useModal

Définit si les écrans de l'interface se chargent dans une fenêtre modale plutôt qu'en ligne. Type : boolean Valeur par défaut: true

useFullScreen

Définit si le SDK se charge en mode plein écran. Type : boolean Valeur par défaut: false

disableClientAnalytics

Définit si nous suivons ou non les analyses client.

Type : boolean Valeur par défaut: false

stages

Il s'agit de la liste des étapes que vos clients suivront. Les étapes peuvent être fournies sous forme de chaînes ou d'objets. Voir Étapes ci-dessous pour en savoir plus.

Type : array[object] ou array[string]

Valeurs par défaut: ['intro', 'faceCapture, 'documentCapture', 'completion']

language

La langue de l'interface. Les valeurs valides incluent :

en , ar, br, de, es, fr, hi, hk, identifiant, it, ja, ko, nl, no, pl, pt, sv, th, vi, zh

Type : string Valeur par défaut: en

Callback

Les callbacks vous permettent de réagir aux événements du cycle de vie du SDK.

Option

Description

onComplete

Déclenché après que le client a terminé le parcours de vérification. Généralement utilisé pour déclencher une vérification sur votre backend.

Selon les étapes fournies, données peut inclure les attributs suivants :

documentCapture
- documentId: identifiant du document capturé.
- documentType: Type de document téléchargé.
faceCapture
- liveVideoId: identifiant de la vidéo capturée. OU;
- livePhotoId: identifiant de la photo capturée.
poaCapture
- documentId: identifiant du document de justificatif de domicile téléversé.
- documentType: type du document de justificatif de domicile téléversé.

onError

Déclenché lorsqu'une erreur se produit. L'objet d'erreur comporte deux attributs :

type: Cela peut être :
- exception
- token_expired : indique que le jeton a expiré. Dans ce cas, un nouveau jeton SDK doit être fourni.
message: Description de l'erreur.

onExit

Ce callback est déclenché lorsque votre client quitte avant de terminer le parcours. Il renverra la raison de la sortie, par exemple, USER_CONSENT_NOT_GRANTED.

onModalClose

Déclenché lorsque le client tente de fermer la modale. Vous pouvez autoriser ou empêcher la fermeture en mettant à jour l' isModalOpen attribut à l'aide de updateSettings.

Mise à jour des paramètres

Un certain nombre de paramètres peuvent être mis à jour à l’exécution comme suit :

complycube = ComplyCube.mount({...});

// Remplacer le jeton SDK
complycube.updateSettings({ token: "NEW_SDK_TOKEN" });
...
// Ouvrir la fenêtre modale
complycube.updateSettings({ isModalOpen: true });

//Fermer la fenêtre modale
complycube.updateSettings({ isModalOpen: false });

Démontage du SDK

Si vous utilisez le SDK dans une application monopage (SPA), vous pouvez appeler la fonction unmount pour supprimer le SDK et réinitialiser son état.

complycube = ComplyCube.mount({...});
...
complycube.unmount()

Étapes

Le stages tableau définit le parcours de vérification. Chaque étape peut être passée sous forme de string ou comme un objet avec des options.

Noms d'étapes pris en charge

intro: Écran d'accueil.
userConsentCapture: Capture du consentement du client.
documentCapture: Capture des documents d'identité.
faceCapture: Capture de selfies ou de vidéos de vérification de présence.
poaCapture: Capture du document de justificatif de domicile.
completion: Fin du parcours.

Lorsque userConsentCapture est activé, gérez toujours le onExit callback si le client refuse son consentement.

Veuillez vous assurer de transmettre le paramètre clientConsent lorsque le consentement est accordé par votre client.

Lorsqu'une étape est passée sous forme de objet, elle aura deux attributs, nom et options.

Nom

Voici le nom de l’étape

Options

Cela vous permet de personnaliser chaque étape comme suit :

Nom de l’étape

Options

intro

heading: Modifiez le titre de l’écran d’introduction.
message: Une liste de messages à afficher sur l’écran d’introduction. Taille maximale 3.
startButtonText: Modifiez le texte du bouton de démarrage sur l’écran d’introduction.

documentCapture

crossDeviceOnly: Un booléen qui indique s’il faut obliger les utilisateurs à capturer leur document à l’aide de leur téléphone. Cela supprime l’option de téléversement du document.
documentTypes: La liste des types de documents d’identité visibles pour l’utilisateur. Les types de documents valides incluent :
- passport
- driving_license
- national_identity_card
- residence_permit
Chaque valeur peut être soit un boolean ou un objet pays. Un booléen active ou désactive l’affichage du type de document, tandis qu’un objet pays spécifie le pays émetteur pour les documents autres que le passeport, en contournant l’écran de sélection du pays. La valeur du pays est le code ISO de pays à deux lettres.

faceCapture

mode: Le mode de capture faciale. Les valeurs possibles sont : photo ou video.

poaCapture

documentTypes: La liste des types de documents justificatifs de domicile (POA) visibles pour le client. Les types de documents POA valides incluent :
- bank_statement
- utility_bill

La valeur de chaque type de document est un booléen qui active ou désactive l’affichage du type de document.

completion

heading: Modifiez le titre de l’écran de fin.
message: Un message à afficher sur l’écran de fin. Taille maximale 1.

Exemple d’objet d’options

stages: [
  {
    name: "intro",
    options: {
      heading: "Nous devons vérifier votre identité",
      message: [
        "Afin d’ouvrir un compte, nous devons vérifier quelques éléments.",
        "Cela ne prendra qu’un instant",
      ],
      startButtonText: "Commencer la vérification"
    },
  },
  "userConsentCapture",
  {
    name: "documentCapture",
    options: {
      crossDeviceOnly: true,
      documentTypes: {
        passport: true,
        driving_license: false,
        national_identity_card: true,
        residence_permit: {
          country: "GB",
        },
      },
    },
  },
  {
    name: "faceCapture",
    options: {
      mode: "video"
    },
  },
  {
    name: "poaCapture",
    options: {
      documentTypes: {
        bank_statement: true,
        utility_bill: false,
      },
    },
  },
  {
    name: "completion",
    options: {
      heading: "Merci d’avoir terminé le processus",
      message: ["nous vous contacterons sous peu"]
    },
  }
];

Branding

Vous pouvez personnaliser l’apparence et le style du SDK avec l’ objet de branding . Il comprend les attributs décrits ci-dessous.

Apparence

Le apparence l'objet vous permet de personnaliser le jeu de couleurs du SDK avec des valeurs CSS (par ex. RGBA, Hex). Les attributs personnalisables comprennent :

Attribut

Description

infoPopupColor

Couleur d'arrière-plan de la fenêtre contextuelle d'avertissement.

infoPopupTextColor

Couleur d'arrière-plan de la fenêtre contextuelle d'avertissement.

infoPopupLinkHoverColor

Couleur d'arrière-plan de secours du lien de la fenêtre contextuelle d'avertissement au survol.

infoPopupLinkActiveColor

Couleur d'arrière-plan active de secours du lien de la fenêtre contextuelle d'avertissement.

errorPopupColor

Couleur d'arrière-plan de la fenêtre contextuelle d'erreur.

errorPopupTextColor

Couleur du texte de la fenêtre contextuelle d'erreur.

errorPopupLinkHoverColor

Couleur d'arrière-plan de secours du lien de la fenêtre contextuelle d'erreur au survol.

errorPopupLinkActiveColor

Couleur d'arrière-plan active de secours du lien de la fenêtre contextuelle d'erreur.

cameraButtonHoverColor

Couleur d'arrière-plan du bouton de caméra au survol.

cameraButtonActiveColor

Couleur d'arrière-plan active du bouton de caméra.

iconButtonActiveColor

Couleur d'arrière-plan active du bouton d'icône.

iconButtonHoverColor

Couleur d'arrière-plan du bouton d'icône au survol.

primaryButtonColor

Couleur d'arrière-plan du bouton principal.

primaryButtonTextColor

Couleur du texte du bouton principal.

primaryButtonActiveColor

Couleur d'arrière-plan active du bouton principal.

primaryButtonHoverColor

Couleur d'arrière-plan du bouton principal au survol.

primaryButtonBorderColor

Couleur de bordure du bouton principal.

secondaryButtonColor

Couleur d'arrière-plan du bouton secondaire.

secondaryButtonTextColor

Couleur du texte du bouton secondaire.

secondaryButtonActiveColor

Couleur d'arrière-plan active du bouton secondaire.

secondaryButtonHoverColor

Couleur d'arrière-plan du bouton secondaire au survol.

secondaryButtonBorderColor

Couleur de bordure du bouton secondaire.

documentSelectorColor

Couleur d'arrière-plan du sélecteur de document.

documentSelectorTextColor

Couleur du texte du sélecteur de document.

documentSelectorActiveBorderColor

Couleur d'arrière-plan active du sélecteur de document.

documentSelectorHoverBorderColor

Couleur d'arrière-plan du sélecteur de document au survol.

linkHoverColor

Couleur d'arrière-plan du lien au survol.

linkActiveColor

Couleur d'arrière-plan active du lien.

linkUnderlineColor

Couleur du soulignement du lien.

linkHoverTextColor

Couleur du texte du lien au survol.

bodyTextColor

Couleur du texte du contenu du SDK.

headingTextColor

Couleur du texte des titres du SDK.

subheadingTextColor

Couleur du texte des sous-titres du SDK.

Logo

Le logo l'objet possède les attributs suivants :

lightLogoUrl: URL pour la version claire de votre logo.
darkLogoUrl: URL pour la version sombre de votre logo.

Exemple de branding du logo

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  logo: {
    lightLogoUrl: 'light_logo_url',
    darkLogoUrl: 'dark_logo_url',
  }
},

Texte de branding

Le textBrand l’attribut représente le format textuel de votre marque.

Exemple de branding textuel

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  textBrand: 'Acme Bank'
}

Si logo et textBrand sont spécifiés en même temps, logo a priorité.