Gérer la vérification avec l'API

Les plateformes Connect qui inscrivent des comptes connectés à l’aide de l’API doivent Stripe fournir les informations requises pour Know your customer (KYC) et pour activer les fonctionnalités de compte. Elles doivent collecter elles-mêmes les informations et utiliser les API Accounts et Persons pour les fournir à Stripe. Nous vérifions ensuite les informations et demandons plus de détails si nécessaire.

Processus de vérification

Pour activer les paiements et virements d’un compte connecté, Stripe a besoin de certaines informations dont la nature varie en fonction :

• Pays d’origine des comptes connectés
• Le type de contrat de service applicable aux comptes connectés
• Fonctionnalités demandées pour les comptes connectés
• Le business_type (par exemple, particulier ou entreprise) et la structure de l’entreprise (par exemple, public_corporation ou private_partnership)

Pour répondre aux exigences KYC, les plateformes doivent choisir le flux d’inscription qui convient à leur entreprise et à leurs utilisateurs. De manière générale, vous devez choisir entre fournir toutes les informations requises au début du processus ou les fournir progressivement. Dans tous les cas, configurez votre intégration pour surveiller les requêtes de Stripe et y répondre.

1. Mettez en place une URL de webhook Connect dans vos paramètres de webhook afin de surveiller l’activité, en particulier les événements de type account.updated. Si vous utilisez l’API Persons, surveillez aussi les événements person.updated.
2. Une fois le compte créé, vérifiez immédiatement l’attribut requirements.currently_due de l’objet Account pour prendre connaissance d’éventuelles exigences supplémentaires. Demandez les informations supplémentaires requises à l’utilisateur et mettez à jour le compte connecté.
3. Continuez de surveiller les notifications d’événement account.updated pour être informé des changements de l’algorithme de hachage requirements et demander d’éventuelles informations complémentaires à votre utilisateur.

Quand vous fournissez des informations complémentaires, il n’est pas nécessaire de fournir également des informations déjà vérifiées. Par exemple, si l’information dob est déjà vérifiée, vous n’avez plus à la fournir lors des mises à jour suivantes.

Modifier des informations après vérification

Une fois qu’une personne ou une entreprise a été vérifiée, vous pouvez modifier certaines de leurs informations, en observant certaines restrictions. Consultez l’API Update Account pour connaître les restrictions en fonction de la configuration du compte connecté. Pour effectuer des modifications en contournant ces restrictions, contactez le service Support.

Déterminer si une vérification est nécessaire

Lorsque vous recevez un événement account.updated sur votre webhook ou que vous récupérez un compte avec l’API, vous recevez un objet Account. Les paramètres charges_enabled et payouts_enabled de l’objet Account indiquent si le compte peut créer des paiements et accepter des virements.

L’objet Account a un hachage requirements, qui représente les exigences de vérification du compte.

Le hachage des requirements contient les matrices suivantes :

• eventually_due : exigences que vous pourriez avoir à collecter, selon que les seuils correspondants sont atteints ou non. Lorsqu’une exigence devient obligatoire, elle apparaît également dans la liste des currently_due. Si une exigence devient obligatoire et que sa date d’échéance est antérieure à la current_deadline actuelle, la current_deadline devient la date d’application du seuil correspondant.
• currently_due : exigences que vous devez collecter à la current_deadline pour que le compte reste active. currently_due est un sous-ensemble de eventually_due.
• past_due : exigences dont les fonctionnalités sont désactivées parce qu’elles n’ont pas été vérifiées avant la current_deadline. past_due est un sous-ensemble de currently_due.
• errors : détails sur les échecs de validation et de vérification qui nécessitent de collecter à nouveau des exigences particulières dans les catégories currently_due ou past_due.
  • requirement : identifie l’exigence correspondant à l’erreur.
  • code : une valeur d’énumération décrivant le motif pour lequel l’exigence n’est pas valide ou ne peut pas être vérifiée.
  • reason : un message en anglais décrivant l’erreur plus en détail. La chaîne du motif peut également suggérer comment résoudre l’erreur.
• disabled_reason : décrit le motif pour lequel le compte n’est pas activé et ne peut pas traiter les paiements ou les transferts.
• current_deadline : date à laquelle les exigences figurant dans currently_due doivent être collectées pour que le compte reste active. Il s’agit de l’échéance la plus proche pour l’ensemble des fonctionnalités demandées et des exigences en matière de risque du compte, y compris les éventuelles fonctionnalités cachées.
• pending_verification : exigences susceptibles de devenir obligatoires, en fonction des résultats de la vérification ou de l’examen. Il s’agit d’un tableau vide, sauf si une vérification asynchrone est en cours. Un échec de vérification fait passer une exigence à l’état eventually_due, currently_due ou past_due. Une exigence soumise à la fois à un échec de vérification et à une vérification en cours peut également rester à l’état pending_verification.

L’exemple ci-dessous illustre l’algorithme de hachage requirements pour un compte dont certaines informations figurent dans currently_due, d’autres dans eventually_due et d’autres ont généré des errors de vérification.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "disabled_reason": null,
      "current_deadline": 1529085600,
      "past_due": [],
      "currently_due": [
          "company.tax_id",
          "company.verification.document",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "eventually_due": [
          "company.address.city",
          "company.address.line1",
          "company.address.postal_code",
          "company.address.state",
          "company.tax_id",
          "company.verification.document",
          "external_account",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "errors": [
          {
            "requirement": "company.verification.document",
            "reason": "The company name on the account couldn't be verified. Either update your business name or upload a document containing the business name.",
            "code": "failed_name_match"
          },
      ]
  },
  ...
}

Si l’attribut requirements.currently_due contient des entrées, vérifiez l’attribut requirements.current_deadline. current_deadline est un horodatage Unix qui permet d’identifier les moments où des informations sont nécessaires. En règle générale, si Stripe ne reçoit pas les informations avant la current_deadline, les virements sur le compte sont désactivés. Cependant, d’autres conséquences peuvent s’appliquer dans d’autres situations. Par exemple, si les virements sont déjà désactivés et que le compte ne répond pas à nos demandes, Stripe peut également désactiver le traitement des paiements.

Par ailleurs, la propriété requirements.disabled_reason peut avoir une valeur. La valeur est une chaîne décrivant la raison pour laquelle ce compte n’est pas en mesure d’effectuer des virements ou des paiements. Dans certains cas, les plateformes et les comptes connectés peuvent soumettre un formulaire pour résoudre le problème ou faire appel.

• Les comptes connectés ayant accès au Dashboard de Stripe complet, y compris les comptes Standard, peuvent accéder à des informations supplémentaires (le cas échéant) dans leur Dashboard.
• Les plateformes peuvent rechercher un compte sur la page Comptes connectés pour déterminer le motif de sa désactivation (disabled_reason). Vous pouvez fournir des informations supplémentaires au nom de vos comptes connectés. Si le motif de désactivation est associé à un appel, vous pouvez générer un lien vers un formulaire permettant au compte de résoudre l’appel.

Erreurs de validation et de vérification

L’objet Account contient un tableau requirements.errors qui explique pourquoi les exigences de validation ou de vérification nécessaires à l’activation de votre compte et ses fonctionnalités ne sont pas remplies. Le tableau errors possède les attributs suivants :

• requirement : indique quelles informations de la table currently_due sont requises.
• code: Indique le type d’erreur qui s’est produite. Voir la documentation relative à l’API pour connaître tous les codes d’erreur possibles.
• reason : explique pourquoi l’erreur s’est produite et comment la résoudre.

L’exemple ci-dessous montre à quoi peut ressembler le tableau errors pour un compte dont les exigences sont définies sur currently_due. Cet exemple montre la raison pour laquelle les informations envoyées ne peuvent pas être utilisées pour activer le compte et explique comment résoudre l’erreur. Si la vérification ou la validation échoue, les exigences peuvent réapparaître dans currently_due avec des informations sur les erreurs. Définissez un webhook Connect pour recevoir l’événement account.updated et obtenir ces mises à jour.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "company.address.line1",
          "{{PERSON_ID}}.verification.document",
      ],
      "errors": [
          {
            "requirement": "company.address.line1",
            "code": "invalid_street_address",
            "reason": "The provided street address cannot be found. Please verify the street name and number are correct in \"10 Downing Street\"",
          },
          {
            "requirement": "{{PERSON_ID}}.verification.document",
            "code": "verification_document_failed_greyscale",
            "reason": "Greyscale documents cannot be read. Please upload a color copy of the document.",
          }
      ]
  },
  ...
}

Si la vérification ou la validation échoue, mais qu’aucune exigence n’est requise actuellement, un webhook se déclenche pour signaler une information requise dans le futur.

Informations sur l’entreprise

Lorsque des informations sont soumises sur une entreprise, Stripe vérifie les nouvelles informations. Par exemple, Stripe peut vérifier que l’URL de l’entreprise fournie est valide, accessible et qu’elle contient des informations sur l’entreprise. Pour vérifier l’état des informations de vérification concernant une personne, récupérez le hachage requirements de l’objet Account.

Vous trouverez ci-dessous une liste d’erreurs liées à la vérification des informations de l’entreprise :

Libellés de relevé bancaire

Stripe valide le libellé de relevé bancaire et son préfixe lorsqu’ils sont configurés pour un compte. Par exemple, Stripe peut vérifier que le libellé fourni correspond à la description de l’entreprise. Pour ce faire, Stripe examine les 22 premiers caractères du libellé de relevé bancaire, représentant la partie transmise aux réseaux de cartes. La description de l’entreprise doit être presque identique au business_profile.name, à l’URL business_profile.url du compte ou au nom de l’entreprise ou du particulier titulaire du compte.

Pour récupérer l’état des informations de vérification concernant les libellés de relevé bancaire, vérifiez les requirements sur l’objet Account. Vous trouverez ci-dessous une liste d’erreurs liées à la vérification des libellés de relevé bancaire :

Représentants de l’entreprise

Vous devez collecter et soumettre les informations relatives aux personnes associées à un compte connecté. Le processus varie selon que vos comptes connectés sont des entreprises ou des particuliers :

• Entreprises uniquement : utilisez l’API Persons pour ajouter les informations à un objet Person associé à l’objet Account.
• Particuliers uniquement : Vous pouvez utiliser l’API Persons ou le hachage individual de l’objet Account.
• Une combinaison de particuliers et d’entreprises : utilisez l’API Persons pour ajouter les informations à un objet Person associé au compte. Cela vous permet d’utiliser le même processus pour tous vos comptes connectés, quel que soit leur type.

Pour connaître l’état des informations de vérification concernant une personne, utilisez le hachage requirements.

Vous trouverez ci-dessous une liste d’erreurs liées à la vérification des personnes :

Documents de vérification valides par pays

Pour en savoir plus sur les exigences spécifiques en matière de documents, consultez la page Documents de vérification acceptables par pays.

Informations sur l’entreprise

Lors du processus de vérification, vous serez peut-être amené à recueillir des informations sur l’entreprise d’un compte.

Pour connaître l’état des informations de vérification concernant une entreprise, utilisez le sous-hachage company.verification du compte :

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  ...
  "company": {
    "verification": {
      "document": null
    },
    ...
  },
  ...
}

Vous pouvez rechercher la définition de chaque attribut de vérification dans l’objet Account.

Gérer les problèmes de vérification des documents

Les problèmes liés aux pièces d’identité, qu’il s’agisse des fichiers téléchargés eux-mêmes ou de leur utilisation pour valider d’autres informations, entraînent de nombreuses erreurs de vérification des exigences. Pour vous aider à identifier et gérer les problèmes les plus courants, les tableaux ci-dessous répertorient les valeurs de code d’erreur liées aux problèmes de document et fournissent des conseils pour les résoudre.

Les erreurs suivantes sont liées aux fichiers de documents chargés :

Les erreurs suivantes sont liées à la vérification d’identité :

Les erreurs suivantes sont liées à la vérification des entreprises :

Les erreurs suivantes sont liées à la vérification des relations :

Gérer les erreurs de vérification des URL

Les URL des entreprises d’e-commerce doivent se conformer à certaines normes des réseaux de cartes. Afin de respecter ces normes, Stripe effectue un certain nombre de vérifications lors de l’examen des URL. Pour en savoir plus sur les bonnes pratiques en matière d’URL et sur les composants communs aux entreprises d’e-commerce, consultez la liste de contrôle des sites Web.

Dans de nombreux cas, vous pouvez résoudre les erreurs de vérification des URL d’entreprise en générant un lien de rectification depuis le Dashboard de votre plateforme. Sinon, mettez à jour le business_profile.url. de l’objet Account. Si vous corrigez l’erreur d’une autre manière, par exemple en passant par le site Web de l’entreprise, déclenchez la nouvelle vérification en remplaçant l’URL de l’objet Account par une autre valeur, puis en la remplaçant immédiatement.

L’API ne permet pas de résoudre tous les problèmes liés aux URL. Certains types d’erreurs de vérification d’URL nécessitent des informations supplémentaires sur la manière d’accéder au site Web du compte connecté ou pour attester que le compte est exempté des exigences relatives aux URL. Ce type de problème nécessite que vous ou votre compte connecté fournissiez des informations supplémentaires.

Si vous ne parvenez pas à résoudre le problème, demandez à votre compte connecté de contacter le service d’assistance Stripe.

Pour vous aider à identifier et à gérer les problèmes les plus courants, le tableau suivant répertorie les valeurs de code d’erreur liées aux problèmes liés à l’URL de l’entreprise et propose des conseils pour les résoudre.

Gérer les exigences en matière de preuves d’existence

Un compte peut avoir une ou plusieurs personnes avec une exigence proof_of_liveness. Une exigence proof_of_liveness peut imposer la collecte d’une pièce d’identité électronique telle que MyInfo à Singapour, ou l’utilisation de Stripe Identity pour collecter un document ou un selfie. Nous vous recommandons d’utiliser l’inscription hébergée par Stripe ou l’inscription intégrée pour répondre à toutes les variantes de l’exigence proof_of_liveness.

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/refresh" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]"=currently_due

Gérer la vérification d’identité

Dans certains cas, en fonction du nombre d’informations d’identité d’un compte que Stripe a pu vérifier, nous pouvons vous demander d’importer un ou plusieurs documents. Les documents requis apparaissent dans l’algorithme de hachage requirements de Account.

Les entrées suivantes dans requirements.currently_due identifient les documents que vous devez importer :

• person.verification.document : nécessite une photographie ou une copie numérisée en couleur d’une pièce d’identité acceptée.
• person.verification.additional_document : nécessite une photographie ou une copie numérisée en couleur d’un document confirmant l’adresse de l’utilisateur, par exemple une facture d’eau ou d’électricité.
• company.verification.document : nécessite un justificatif sur lequel figure l’identifiant de l’entité commerciale, par exemple les statuts de l’entreprise.

Le chargement d’un document s’effectue en deux étapes :

1. Charger le fichier sur Stripe
2. Associer le fichier au compte

Charger un fichier

Pour charger un fichier, utilisez l’API Create File en utilisant un POST pour envoyer les données du fichier dans le cadre d’une requête multipart/form-data.

Le fichier chargé doit respecter les critères suivants :

• Image en couleur (de 8 000 pixels par 8 000 pixels maximum)
• 10 Mo maximum
• Pièces d’identité au format JPG ou PNG
• Justificatifs d’adresse ou d’entité juridique au format JPG, PNG ou PDF

Transmettez les données du fichier dans le paramètre file et définissez le paramètre purpose en fonction de la propriété Account ou Person qui tiendra le document. Pour identifier l’objectif, recherchez la propriété dans la documentation de l’API.

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="identity_document" \
  -F "file"="@/path/to/a/file"

Cette requête charge le ficher et renvoie un token :

{
  "id": 
"{{FILE_ID}}",
  "created": 1403047735,
  "size": 4908
}

Utilisez la valeur id du token pour associer le fichier à un compte connecté à des fins de vérification d’identité.

Joindre un fichier

Une fois que vous avez chargé le fichier et reçu un token représentatif, mettez à jour le Account ou la Person et fournissez l’ID du fichier dans le paramètre approprié.

L’exemple ci-dessous concerne une pièce d’identité :

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "verification[document][front]"=
{{FILE_ID}}

L’exemple ci-dessous concerne un justificatif d’entreprise :

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[verification][document][front]"=
{{FILE_ID}}

Cette mise à jour fait passer l’attribut verification.status à l’état pending. Si vous devez vérifier une personne supplémentaire, mettez-la à jour à l’aide de l’API Persons.

Confirmer la vérification d’identité

Le respect de toutes les exigences de vérification d’identité pour une personne ou une entreprise déclenche une notification de webhook v2.core.account_person.updated ou v2.core.account[identity].updated, indiquant que le processus de vérification est terminé.

La vérification d’une image par Stripe peut prendre de quelques minutes à quelques jours ouvrables, en fonction de sa lisibilité.

Si la tentative de vérification échoue, l’entrée de l’exigence associée contient une erreur avec un code et une description décrivant la cause. La description contient un message lisible par l’utilisateur, tel que « L’image fournie n’est pas lisible », que vous pouvez présenter à l’utilisateur de votre compte en toute sécurité, mais qui n’est pas localisé. La valeur code est une chaîne telle que verification_document_not_readable, que vous pouvez utiliser pour localiser les messages d’erreur destinés aux utilisateurs de votre compte.

L’échec de la vérification déclenche également une notification de webhook v2.core.account_person.updated ou v2.core.account[identity].updated.

Collecte de documents hébergée avec Stripe Identity

Vous pouvez utiliser Stripe Identity pour répondre à une exigence person.verification.document afin de recueillir un document et de le joindre directement au compte.

Créer une VerificationSession. Précisez le paramètre related_person pour associer les données de vérification collectées à l’objet 'Person nécessitant le paramètre document, comme illustré dans l’exemple suivant.

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document \
  -d "related_person[account]"=
{{CONNECTED_ACCOUNT_ID}} \
  -d "related_person[person]"=
{{PERSON_ID}}

Une fois que vous avez créé la VerificationSession, utilisez le client_secret renvoyé pour présenter la fenêtre modale Identity à l’utilisateur ou redirigez celui-ci vers l’url. Une fois la vérification terminée, le compte est automatiquement mis à jour.

Nous envoyons un événement account.updated à votre endpoint de webhook lorsque le compte termine la vérification d’identité et met à jour ses informations.

Traiter les vérifications des risques

Stripe signale les exigences en matière de risque et de conformité dans l’attribut accounts.requirements.. Ces exigences suivent le schéma : <id>.<requirement_description>.<resolution_path> :

• id identifie de manière unique les informations dont Stripe ou nos partenaires financiers ont besoin. Cet identifiant est toujours préfixé par interv_ pour indiquer qu’il s’agit d’une exigence de vérification du risque.
• requirement_description décrit spécifiquement les informations nécessaires à la résolution de l’exigence, telles que identity_verification, rejection_appeal, etc.
• resolution_path indique comment vous ou votre compte connecté pouvez fournir les informations demandées :
  • challenge : les comptes connectés doivent répondre directement aux demandes d’informations. Celles-ci exigent souvent des informations sensibles, comme un compte bancaire, ou des informations que seul le propriétaire du compte peut fournir, comme un selfie.
  • form : les comptes connectés peuvent remplir des demandes de formulaire, ou vous pouvez les remplir en leur nom.
  • support : l’exigence n’est pas directement exploitable. Contactez le service Support de Stripe.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.form"
      ],
      "pending_verification": [],
      ...
  },
  ...
}

Après avoir satisfait une résolution, la valeur du chemin de résolution utilisé peut passer à l’état support et l’exigence apparaît également dans la section pending_verification du hachage des exigences. Stripe vérifie les informations soumises et rejette l’exigence comme étant résolue ou publie une nouvelle exigence en attente de résolution.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [],
      "pending_verification": [
        "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.support"
      ],
      ...
  },
  ...
}

Vous pouvez répondre aux exigences en matière de risque et de conformité de l’une des manières suivantes, selon le type d’exigence :

• Composants Connect intégrés : vous pouvez directement intégrer des composants Connect à votre site Web. Lorsqu’une exigence apparaît, dirigez vos utilisateurs vers le composant intégré d’inscription des utilisateurs, qui les invite directement à satisfaire aux exigences en attente dans votre interface utilisateur. Vous pouvez également utiliser le composant intégré bannière de notification pour inviter vos utilisateurs à satisfaire aux exigences en attente.
• Inscription hébergée par Stripe : vous pouvez générer des liens pour permettre à vos comptes connectés de remplir les exigences auxquels ils sont soumis de manière programmatique via les liens de compte ou manuellement dans le Dashboard de votre plateforme.
• Remplir au nom de vos comptes : vous pouvez utiliser le Dashboard de votre plateforme pour identifier les exigences liées aux risques de vos comptes connectés et remplir les formulaires correspondants en leur nom.

Le tableau suivant fournit plus de détails sur les descriptions possibles des exigences liées aux risques et à la conformité.