Gérer la vérification avec l'API

Les plateformes dont les comptes ont été créés à l’aide de l’API sont en mesure de fournir à Stripe les informations nécessaires dans le cadre des exigences Know Your Customer (KYC). Les plateformes peuvent utiliser le flux d’inscription Connect Onboarding pour collecter les informations KYC, ou les API Accounts et Persons pour fournir à Stripe les informations requises. Nous procéderons ensuite à la vérification puis demanderons des informations supplémentaires si nécessaire.

Le reste de cette page explique comment les plateformes peuvent :

• Exigences de vérification des comptes connectés
• Fournir les informations requises à Stripe

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
• Type (par exemple particulier ou entreprise) et structure de l’entreprise (par exemple, société anonyme ou société de personnes)

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 d’assistance.

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 ainsi que les comptes Standard peuvent accéder à des informations supplémentaires (le cas échéant) dans leur Dashboard.
• Quelle que soit la configuration de Connect, les plateformes peuvent accéder aux comptes à vérifier pour comprendre le disabled_reason d’un compte. 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 concernant 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 récupérer l’état des informations de vérification concernant une entreprise, utilisez l’attribut 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 :

Informations sur les personnes

Lors du processus de vérification, des informations concernant la personne associée au compte doivent être recueillies. Si vous inscrivez :

• Entreprises uniquement, utilisez l’API Persons pour recueillir ces informations.
• Uniquement des particuliers, utilisez l’API Persons ou l’algorithme de hachage individual de l’objet Account.
• À la fois des particuliers et des entreprises, utilisez l’API Persons pour recueillir ces informations. Cela vous permettra d’utiliser la même méthode de collecte des informations, quel que soit le type de structure de l’entreprise.

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

De nombreux problèmes de vérification sont dus au chargement du document. Afin de vous aider à reconnaître et traiter les problèmes les plus courants, le tableau ci-dessous liste toutes les valeurs possibles du code d’erreur (dans le tableau requirements.errors) et indique la solution probable de chacune de ces erreurs.

Les erreurs ci-dessous sont liées au chargement du document :

Les erreurs ci-dessous sont liées à la vérification d’identité :

Les erreurs ci-dessous sont liées à la vérification d’entreprise :

Gérer les erreurs de vérification d’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. Il existe deux méthodes pour résoudre les erreurs de vérification d’URL :

• Utilisation de l’API : veuillez consulter la liste des codes d’erreur ci-dessous afin de comprendre et de résoudre le problème en question. Si vous devez mettre à jour l’URL, utilisez l’API Update Account, ce qui déclenchera la vérification de la nouvelle URL par Stripe. Si vous avez apporté des modifications au site Web sur l’URL fournie afin de résoudre une erreur, mais que vous n’avez pas besoin de modifier l’URL elle-même, vous pouvez déclencher la revérification en utilisant l’API pour modifier l’URL vers n’importe quelle autre valeur, puis revenir à l’URL initiale.
• Utilisation du Dashboard : les plateformes peuvent utiliser la page Comptes à vérifier ou la liste Actions requises sur la page Détails du compte dans le Dashboard Stripe pour comprendre l’impact sur leurs comptes connectés et les mesures à prendre.

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.

Dans le Dashboard, rendez-vous sur votre page Comptes à vérifier ou vérifiez la liste Actions requises (si présente) sur la page Détails du compte pour résoudre l’erreur. Si vous ne parvenez pas à résoudre le problème, demandez à votre compte connecté de contacter le service d’assistance Stripe. Pour obtenir des conseils sur la façon de vérifier vos comptes, consultez la rubrique Vérifier les comptes pour lesquels des mesures peuvent être prises.

Pour vous aider à gérer les erreurs les plus courantes associées au champ business_profile.url, le tableau suivant présente les codes d’erreur associés (dans le tableau requirements.errors) et les résolutions possibles.

Gérer la vérification d’identité

Vous pouvez réagir de deux manières à des modifications de vérification d’identité. La première option consiste à effectuer un appel Update Account pour corriger ou ajouter des informations.

Pour la deuxième méthode, nous vous demanderons probablement de charger un document. Selon le nombre d’informations utilisateur que Stripe aura pu vérifier, nous pourrons vous demander trois différents types de documents. Pour savoir quel document charger, vous pouvez vous référer aux champs listés dans requirements.currently_due :

• person.verification.document : nécessite une photographie ou copie numérisée en couleur d’une pièce d’identité acceptée.
• person.verification.additional_document : nécessite une photographie ou copie numérisée en couleur d’un document qui confirme 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 de type 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 puis définissez le paramètre purpose sur identity_document :

curl https://files.stripe.com/v1/files \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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
}

Vous pouvez ensuite utiliser 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, indiquez l’ID du fichier dans le champ adéquat de votre appel Update Account.

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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é

Si la photographie ou la copie numérisée en couleur de la pièce d’identité passe les contrôles de Stripe, l’exigence relative au document est supprimée de requirements.currently_due. Répondre à toutes les exigences de vérification d’une personne ou d’une entreprise déclenche une notification de webhook account.updated, indiquant que le processus de vérification est terminé.

Le temps nécessaire aux vérifications de Stripe va de quelques minutes à quelques jours, en fonction de la lisibilité de l’image fournie.

Si une tentative de vérification échoue, le tableau requirements.errors contient une erreur spécifiant la cause de l’échec. La valeur error[reason], par exemple « The image supplied isn’t not readable » (L’image fournie n’est pas lisible), peut être communiquée en toute sécurité à votre utilisateur, mais n’est pas localisée. La réponse contient par ailleurs une valeur error[code], comme verification_document_not_readable, que vous pouvez utiliser afin de localiser les erreurs pour vos utilisateurs. En cas d’échec, requirements.currently_due indique qu’un nouveau chargement de pièce d’identité est requis. Si la date limite de la vérification est proche, une date pourra figurer dans requirements.current_deadline. L’échec de la vérification déclenche également une notification de webhook account.updated.

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 d’assistance 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.

Les valeurs de requirement_description suivantes sont liées aux exigences indiquées dans l’attribut account.requirements.