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.

Les plateformes responsables doivent également surveiller l’état des exigences de leurs comptes connectés et gérer rapidement toute mise à jour.

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’onboarding adapté à leur entreprise et à leurs comptes connectés. Ceci signifie le besoin de fournir toutes les informations requises d’emblée ou progressivement. Dans tous les cas, configurez votre intégration de sorte qu’elle identifie les demandes de Stripe et y réponde.

1. Configurez une adresse URL pour le webhook Connect dans vos paramètres de webhook pour pouvoir surveiller l’activité, en particulier les événements account.updated. Lorsque vous utilisez l’API Persons, surveillez également les événements person.updated.
2. Immédiatement après la création d’un compte, vérifiez l’attribut requirements.currently_due de l’objet Account pour détecter d’éventuelles exigences supplémentaires. Obtenez les informations requises auprès du compte connecté et mettez à jour Account. Tant que requirements.currently_due n’est pas vide, Account a des exigences en suspens pouvant limiter ses fonctionnalités.
3. Continuez à surveiller les notifications d’événement account.updated pour vérifier si le hachage requirements change, et demandez au compte connecté des informations supplémentaires si nécessaire.

Lorsque vous fournissez des informations supplémentaires, vous n’avez pas besoin de renvoyer les détails déjà vérifiés. Par exemple, si la dob est déjà vérifiée, vous n’avez pas besoin de la fournir de nouveau, sauf si elle change.

Exigences liées aux vérifications de risque Stripe

Les vérifications de risques effectuées par Stripe sur un compte connecté peuvent imposer des exigences supplémentaires, que vous ne pouvez pas fournir via l’API. Vous pouvez intervenir depuis votre Dashboard, ou le compte connecté peut les soumettre via un composant intégré de Connect, un onboarding hébergé par Stripe ou un lien de rectification.

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

Les attributs charges_enabled et Payouts_enabled d’un objet Accountindiquent s’il peut créer des frais et accepter des paiements.

Si l’un de ces attributs est faux, vérifiez le hachage des requirements de cet Account pour déterminer quelles informations sont nécessaires à l’activation des frais et des paiements.

Le hachage requirements contient les propriétés suivantes :

L’exemple ci-dessous montre à quoi pourrait ressembler le hachage requirements pour un compte dont certaines informations figurent dans currently_due et d’autres dans eventually_due, ainsi que d’autres informations ayant généré des errors de vérification.

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "alternatives": [],
      "current_deadline": 1529085600,
      "currently_due": [
          "company.tax_id",
          "company.verification.document",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "disabled_reason": null,
      "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"
          },
      ]
      "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"
      ],
      "past_due": [],
      "pending_verification": []
  },
  ...
}

Si requirements.currently_due contient des entrées, vérifiez requirements.current_deadline qui correspond à un horodatage Unix. Stripe désactive généralement les paiements sur le compte si nous ne recevons pas les informations avant la date limite current_deadline. Cependant, d’autres conséquences pourraient s’appliquer dans certaines situations. Par exemple, si les paiements sont déjà désactivés et que le compte ne répond pas à nos demandes, Stripe pourrait également désactiver la possibilité de traiter les frais.

Par ailleurs, la propriété requirements.disabled_reason peut contenir une chaîne de caractères expliquant pourquoi certaines fonctionnalités du compte sont désactivées. Dans certains cas, les plateformes et les comptes connectés peuvent soumettre un formulaire pour résoudre le problème ou contester cette désactivation.

• 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 consulter le disabled_reason d’un compte sur la page Comptes connectés. Vous pouvez éventuellement fournir des informations supplémentaires concernant vos comptes connectés. Si le motif de désactivation est lié à un recours, vous pouvez générer un lien vers un formulaire permettant au compte de résoudre ce recours.

Erreurs de validation et de vérification

L’objet Account inclut un tableau requirements.errors qui explique pourquoi les exigences de validation ou de vérification n’ont pas été satisfaites. Vous devez remplir ces exigences pour activer les fonctionnalités du compte.

Le tableau des errors présente les attributs suivants :

L’exemple suivant présente un tableau des errors pour un compte dont les exigences sont currently_due, en plus de la raison pour laquelle les informations envoyées ne peuvent pas être utilisées pour activer le compte et de la marche à suivre pour résoudre l’erreur.

{
  "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.",
          }
      ]
  },
  ...
}

En cas d’échec de la vérification ou de la validation, les exigences peuvent réapparaître dans currently_due, alternative_fields_due ou eventually_due avec des informations d’erreur. Pour recevoir une notification de ces exigences, définissez un webhook Connect pour écouter l’événement account.updated.

Informations sur l’entreprise

Stripe vérifie toutes les informations envoyées concernant une entreprise. Par exemple, nous pourrions vérifier si l’adresse URL de l’entreprise est valide, accessible et si elle contient des informations sur l’entreprise. Pour consulter l’état de la vérification, vous pouvez récupérer le hachage requirements sur l’objet Account.

Les erreurs suivantes concernent la vérification des informations de l’entreprise :

Consultez Gérer les erreurs de vérification des adresses URL pour résoudre les erreurs d’URL suivantes :

• invalid_url_denylisted
• invalid_url_format
• invalid_url_web_presence_detected
• invalid_url_website_business_information_mismatch
• invalid_url_website_empty
• invalid_url_website_inaccessible
• invalid_url_website_inaccessible_geoblocked
• invalid_url_website_inaccessible_password_protected
• invalid_url_website_incomplete
• invalid_url_website_incomplete_cancellation_policy
• invalid_url_website_incomplete_customer_service_details
• invalid_url_website_incomplete_legal_restrictions
• invalid_url_website_incomplete_refund_policy
• invalid_url_website_incomplete_return_policy
• invalid_url_website_incomplete_terms_and_conditions
• invalid_url_website_incomplete_under_construction
• invalid_url_website_other

Représentants de l’entreprise

Vous devez collecter et envoyer des informations sur les personnes associées à un compte connecté. Le processus varie selon que vos comptes connectés sont des entreprises, des particuliers ou les deux.

Pour les entreprises, utilisez l’API Persons pour ajouter les informations à un objet Person associé à l’objet Account. Pour ajouter des documents au hachage de vérification de l’objet Person, utilisez d’abord l’API Files pour télécharger les fichiers de documents sur les serveurs de Stripe.

Pour les entrepreneurs individuels, vous pouvez soit créer une Person ou ajouter les informations au hachage entrepreneur individuel de l’objet Account.

Si vos comptes connectés comprennent à la fois des entreprises et des entrepreneurs individuels, créez des objets Person pour que vous puissiez les traiter tous de la même manière.

Pour consulter l’état de vérification d’un Account, vous pouvez récupérer le hachage de ses exigences.

Les erreurs qui suivent concernent la vérification des personnes :

Documents de vérification acceptables

Les types de pièces d’identité acceptées par Stripe pour les comptes connectés varient selon les pays et sont les mêmes que pour les autres comptes Stripe.

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 consulter l’état de la vérification, vous pouvez récupérer le sous-hachage company.verification sur l’objet Account.

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

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

Libellés de relevé bancaire

Stripe valide le libellé de relevé bancaire et le préfixe du libellé de relevé bancaire lorsque vous les définissez dans un Account. Par exemple, nous vérifions que les 22 premiers caractères, transmis aux réseaux de cartes bancaires, correspondent à la description de l’entreprise. Nous vérifions également s’ils correspondent bien au business_profile.name, au business_profile.url ou au nom de l’entreprise ou de l’entrepreneur individuel titulaire du Account.

Pour consulter l’état de vérification du libellé de relevé bancaire, vous pouvez récupérer le hachage requirements de l’objet Account.

Les erreurs suivantes concernent la vérification du libellé de relevé bancaire :

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

Consultez le tableau suivant pour résoudre les erreurs courantes de vérification des exigences liées aux fichiers de documents téléchargés.

Si la vérification échoue, ne renvoyez pas le même fichier. Les chargements en double échouent automatiquement.

Gérer les erreurs de vérification des adresses URL

Les conditions d’utilisation du service de Stripe exigent que toutes les entreprises d’e-commerce renseignent la propriété business_profile.url sur leur Account avec l’URL fonctionnelle de leur site Web commercial lorsqu’elles demandent la fonctionnalité card_payments. Un compte connecté est considéré comme une entreprise d’e-commerce s’il promeut ou vend des produits ou services via un site Web, un profil sur les réseaux sociaux ou une application mobile. Pour plus d’informations, consultez la FAQ sur l’activation d’un compte au moyen du site Web de l’entreprise.

Lorsqu’un compte connecté ne dispose pas d’un site Web pour promouvoir son activité, vendre des produits ou accepter des paiements, il est nécessaire de renseigner la propriété business_profile.product_description. La description doit détailler le type de produits proposés ainsi que le mode de facturation des clients (par exemple, des transactions en personne).

Les adresses URL des entreprises d’e-commerce doivent être conformes à certaines normes des réseaux de cartes bancaires. Pour garantir cette conformité, Stripe effectue un certain nombre de vérifications lors de l’examen des adresses URL. Découvrez les bonnes pratiques en matière d’URL et d’éléments communs pour les entreprises d’e-commerce.

Dans de nombreux cas, vous pouvez résoudre les erreurs de vérification d’URL en procédant de l’une des manières suivantes :

• Génération d’un lien de rectification depuis le Dashboard de votre plateforme.
• Mise à jour de business_profile.url de l’objet Account.

Si vous résolvez l’erreur d’une autre manière (par exemple, en utilisant le site Web de l’entreprise pour résoudre un problème), vous devez déclencher une nouvelle vérification en modifiant l’adresse URL de l’objet Account par n’importe quelle autre valeur, puis en la rétablissant immédiatement.

Vous ne pouvez pas utiliser l’API pour résoudre tous les problèmes liés aux adresses URL. Certaines erreurs de vérification d’adresse URL nécessitent des informations complémentaires, comme la procédure d’accès au site Web du compte connecté ou la confirmation que ce compte est exempté des exigences relatives aux adresses URL. Ces problèmes nécessitent que vous ou votre compte connecté fournissiez des informations complémentaires.

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

Consultez le tableau suivant pour résoudre les erreurs de vérification de l’URL.

Gérer les exigences de vérification de vivacité

Un compte peut comporter un ou plusieurs objets Person avec une exigence proof_of_liveness. Une exigence proof_of_liveness peut impliquer la collecte d’un identifiant électronique, tel que MyInfo à Singapour, ou l’utilisation de Stripe Identity pour collecter un document ou un selfie.Nous recommandons d’utiliser l’onboarding hébergé ou embarqué par Stripe afin de 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é

En fonction des informations d’identité que nous avons vérifiées pour un compte, nous pourrions vous demander de télécharger un ou plusieurs documents. Les documents requis sont affichés dans le hachage requirements de l’objet Account.

Vous devez télécharger les documents qui s’affichent dans requirements.currently_due :

• person.verification.document : veuillez télécharger une numérisation couleur ou une photo d’une pièce d’identité acceptable.
• person.verification.additional_document : veuillez télécharger une numérisation couleur ou une photo d’un document confirmant l’adresse de l’utilisateur, telle qu’une facture d’eau ou d’électricité.
• company.verification.document : téléchargez un document attestant de l’existence de l’entreprise et établissant son numéro d’identification, tel que les statuts de l’entreprise.

Lorsque requirements.alternatives.alternative_fields_due inclut des exigences verification.document, vous pouvez les utiliser comme alternative à requirements.alternatives.original_fields_due.

Pour des raisons de sécurité, Stripe n’accepte pas les documents d’identité par e-mail. Le chargement d’un document se fait en deux étapes :

1. Télécharger le fichier sur Stripe.
2. Joindre le fichier au compte.

Charger un fichier

Pour télécharger un fichier, appelez l’API Files afin de créer un fichier.

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

Passez les données du fichier dans le paramètre file et définissez le paramètre purpose en fonction de l’objet Account ou Person qui contiendra le document. Pour identifier le but, recherchez la propriété dans la référence 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"

La requête suivante provoque le téléchargement du fichier et le renvoi d’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

Après avoir téléchargé le fichier et reçu un jeton représentatif, mettez à jour l’objet Account ou Person et fournissez l’ID du fichier dans le paramètre approprié.

L’exemple qui suit concerne une pièce d’identité officielle :

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 qui suit concerne un document 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 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é.

En cas d’échec de la tentative de vérification, l’entrée de l’exigence associée contient une erreur accompagnée d’un code et d’une description expliquant la cause. La description est un message en langage clair non localisé, tel que « L’image fournie est illisible », que vous pouvez afficher à l’utilisateur de votre compte. La valeur du code est une chaîne de caractères, 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 satisfaire une exigence person.verification.document en collectant un document et en le rattachant directement au compte. Cependant, vous ne pouvez pas utiliser Stripe Identity pour satisfaire les exigences person.verification.additional_document ou company.verification.document.

Créer une VerificationSession. Spécifiez le paramètre related_person pour associer les données de vérification collectées à l’objet Person qui exige la disponibilité du document, comme indiqué 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 la VerificationSession créée, utilisez le client_secret renvoyé pour afficher la fenêtre modale Identity à l’utilisateur ou rediriger l’utilisateur vers l’adresse URL. La fin de la vérification met automatiquement le compte à 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.

Gérer les exigences provenant de formulaires ou du service d’assistance

Stripe signale les exigences en matière de risques et de conformité dans le hachage des exigences. Ces exigences sont au format <id><requirement_description>.<resolution_path>.

• id : permet d’identifier de manière unique les informations dont Stripe ou nos partenaires financiers ont besoin. Cet identifiant est toujours précédé de interv_ pour indiquer qu’il s’agit d’une exigence pour la vérification des risques.
• requirement_description : décrit précisément les informations nécessaires pour satisfaire à 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 : le compte connecté doit réagir directement aux demandes de vérification, qui nécessitent souvent des informations sensibles (comme un compte bancaire) ou des informations que seul le titulaire du compte peut fournir (comme un selfie).
  • form : le compte connecté peut remplir les demandes de formulaires, ou vous pouvez les remplir en son nom.
  • support : cette 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 intégrés de Connect : intégrez des composants Connect à votre site Web, et dirigez vos utilisateurs vers le composant intégré onboarding du compte où ils seront invités à renseigner les informations manquantes dans votre interface utilisateur. Vous pouvez également utiliser le composant intégré bannière de notification pour inviter vos utilisateurs à répondre à toute exigence en attente.
• Onboarding hébergé par Stripe : vous pouvez générer des liens pour diriger vos comptes connectés afin qu’ils remplissent les exigences en suspens, soit par voie programmatique via des liens de compte, soit manuellement dans le Dashboard de votre plateforme.
• Remplir au nom de vos comptes : vous pouvez utiliser le Dashboard de votre plateforme pour identifier et remplir, au nom de vos comptes, les exigences relatives aux risques provenant des formulaires, et ce, à partir de la page des informations du compte connecté.

Le tableau suivant fournit davantage d’informations sur les exigences liées aux risques et à la conformité.