Utilisation de tokens pour sécuriser la transmission des données des comptes

Pour que nous puissions activer les paiements et les virements pour vos comptes connectés, vous devez remplir les conditions Know Your Customer (KYC). Pour cela, vous devez communiquer à Stripe les informations de vérification d’identité de vos comptes, qui seront ensuite vérifiées. Les tokens de compte et les tokens de personne sont un moyen fiable de le faire. Les tokens vous permettent d’isoler les informations d’identification personnelle (PII) de vos serveurs, de sorte que votre intégration reste sécurisée. Ces tokens permettent aussi à Stripe de détecter plus précisément les fraudes potentielles.

L’utilisation de tokens n’est possible que pour :

• Les informations requises sur l’entité juridique (informations sur l’entreprise ou l’individu)
• Les informations requises sur la personne
• Recueillir l’acceptation du Contrat relatif aux comptes connectés Stripe

L’utilisation de tokens n’est possible pour aucune autre information concernant le compte, y compris :

• Les paramètres de configuration du compte (par exemple, la fréquence des virements)
• Les données non sensibles du compte (par exemple, URL du service d’assistance, le numéro de téléphone du service d’assistance)
• Le pays du compte connecté

Les tokens sont créés à l’aide de Stripe.js, l’API ou de l’une des bibliothèques client mobiles. Le processus est le même que pour la tokenisation des détails de paiement ou des comptes externes. Les informations du compte connecté sont envoyées directement à Stripe et échangées contre un token qui peut être utilisé dans les appels à l’API create et update.

Création et utilisation des tokens

Les tokens nécessitent du code côté client et côté serveur :

1. Créez le formulaire HTML dans lequel l’utilisateur renseignera ses données.
2. Ajoutez le code JavaScript voulu pour envoyer les données du formulaire à Stripe, recevoir un token en retour, et soumettre ce token à votre serveur.
3. Utilisez le token dans un appel à l’API Stripe côté serveur.

L’exemple ci-après vous montre comment s’utilisent les tokens de compte et les tokens de personne. Ces deux types de tokens sont nécessaires pour la fourniture des renseignements voulus sur l’entité juridique et la personne dans le cas des entreprises. Si vous n’inscrivez que des particuliers, vous n’avez pas besoin de tokens de personne. Créez en revanche des tokens de compte et transmettez le hachage individuel sur l’objet Account pour fournir les informations requises.

Étape 1 : Créer un formulaire HTML

La première étape consiste à créer un formulaire HTML qui recueillera les informations requises pour le compte et la personne, y compris l’acceptation du Contrat relatif aux comptes connectés Stripe.

Collecte des renseignements sur le compte et la personne

Créez des éléments de formulaire pour recueillir les renseignements requis tels que le nom, l’adresse et toute autre information requise dans le pays de l’utilisateur.

<form class="my-form" action="/create-person" method="post">
  <input type="hidden" name="token-account" id="token-account">
  <input type="hidden" name="token-person" id="token-person">
  <label>
    <span>Business Name</span>
    <input class="inp-company-name">
  </label>
  <fieldset>
    <legend>Business Address</legend>
    <label>
      <span>Street Address Line 1</span>

Présentation du Contrat relatif aux comptes connectés Stripe

En tant que plateforme, vous devez indiquer clairement à vos utilisateurs que le traitement des paiements est soumis aux conditions du Contrat relatif aux comptes connectés Stripe. La collecte de l’acceptation du Contrat relatif aux comptes connectés Stripe est obligatoire lors de l’utilisation d’un token de compte pour créer un nouveau compte connecté.

Nous vous recommandons d’inclure un bloc de texte tel que celui qui suit, incluant des liens vers notre contrat et vos conditions d’utilisation du service.

<p>By clicking, you agree to <a href="#">our terms</a> and the <a href="https://stripe.com/connect-account/legal">Stripe Connected Account Agreement</a>.</p>

Étape 2 : Ajouter votre code JavaScript

Ensuite, la page a besoin du code JavaScript requis pour :

1. Interrompre la soumission du formulaire.
2. Appeler la méthode stripe.createToken() pour demander les tokens de compte et de personne.
3. Envoyer les ID des tokens reçus à votre serveur.

Dans un souci de simplification, la validation des données et la gestion des erreurs sont omises dans le code ci-dessous, mais n’oubliez pas de prendre en compte ces deux aspects dans votre intégration réelle.

Fournissez deux arguments à la méthode stripe.createToken() :

• La valeur account ou person, pour spécifier le type de token à créer
• Un objet générique d’information

L’objet JavaScript fourni en tant que deuxième argument doit respecter la structure de l’objet Account ou Person que vous voulez tokeniser. Les tokens de compte nécessitent une propriété company ou individual de haut-niveau, et les tokens de personne nécessitent une propriété de haut niveau person. Suivez la structure de l’objet pour tous les attributs requis. Par exemple, la line1 de l’address dans le bloc de code ci-dessous prend la forme person.address.line1.

Pour représenter l’acceptation par l’utilisateur du Contrat relatif aux comptes connectés Stripe, prévoyez une propriété de niveau supérieur tos_shown_and_accepted avec une valeur true (seuls des tokens de compte sont utilisés à cette fin).

Vous devez utiliser les tokens pour la création ou la mise à jour d’une personne à l’aide de code côté serveur. Vous pouvez envoyer l’ID du token à votre serveur en utilisant l’approche la plus pertinente pour votre application (par exemple, une requête XHR). Pour simplifier, cet exemple de code stocke l’ID du token dans un champ de formulaire caché, puis soumet le formulaire.

// Assumes you've already included Stripe.js!
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const myForm = document.querySelector('.my-form');
myForm.addEventListener('submit', handleForm);

async function handleForm(event) {
  event.preventDefault();

  const accountResult = await stripe.createToken('account', {
    business_type: 'company',
    company: {
      name: document.querySelector('.inp-company-name').value,
      address: {
        line1: document.querySelector('.inp-company-street-address1').value,
        city: document.querySelector('.inp-company-city').value,
        state: document.querySelector('.inp-company-state').value,
        postal_code: document.querySelector('.inp-company-zip').value,
      },
    },
    tos_shown_and_accepted: true,
  });

  const personResult = await stripe.createToken('person', {
    person: {
      first_name: document.querySelector('.inp-person-first-name').value,
      last_name: document.querySelector('.inp-person-last-name').value,
      address: {
        line1: document.querySelector('.inp-person-street-address1').value,
        city: document.querySelector('.inp-person-city').value,
        state: document.querySelector('.inp-person-state').value,
        postal_code: document.querySelector('.inp-person-zip').value,
      },
    },
  });

  if (accountResult.token && personResult.token) {
    document.querySelector('#token-account').value = accountResult.token.id;
    document.querySelector('#token-person').value = personResult.token.id;
    myForm.submit();
  }
}

Après réception des tokens envoyés par Stripe, le code JavaScript stocke les ID de token dans un champ de formulaire caché, puis soumet le formulaire (à votre serveur). Les dernières étapes permettent l’utilisation des tokens par votre code côté serveur pour la création du compte et de la personne.

Étape 3 : Créer un compte

Utilisez l’ID du token de compte pour créer le compte. Le pays et le type d’entreprise sont fournis en dehors du token.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

Lors de la création d’un token de compte, paramétrez tos_shown_and_accepted sur true remplit automatiquement les attributs date, ip et user_agent de l’objet Account tos_acceptance. Si vous créez un compte sans utiliser de token de compte, vous devez fournir des valeurs pour ces attributs.

Veillez à noter l’ID de compte renvoyé afin de pouvoir l’utiliser pour créer des objets Person pour le compte.

Étape 4 : Créer une personne

Créez une personne en fournissant l’ID du token de personne comme valeur du paramètre person_token (vous avez également besoin de l’ID de compte pour lequel vous créez la personne). Vous pouvez utiliser le hachage des exigences sur l’objet Account pour déterminer quelles informations sont à collecter et auprès de quelles personnes.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d first_name=Jane \
  -d last_name=Diaz \
  -d person_token=
{{PERSON_ID}}

Création de tokens de compte avec les SDK mobiles

Vous pouvez également créer un token de compte avec nos SDK Android ou iOS. Notez qu’actuellement, seuls les tokens de compte sont pris en charge sur mobile. Cela vous suffit pour créer un compte de particulier, mais vous devez utiliser Stripe.js pour créer le token de personne dont vous avez besoin pour un compte d’entreprise. La prise en charge des tokens de personne dans les SDK mobiles sera disponible dans une prochaine version.

import UIKit
import StripePayments

let companyParams = STPConnectAccountCompanyParams()
companyParams.name = company.name
companyParams.address = STPConnectAccountAddress()
companyParams.address.line1 = company.address_line_1
companyParams.address.city = company.address_city
companyParams.address.state = company.address_state
companyParams.address.country = company.address_country
companyParams.address.postalCode = company.address_postal_code

guard let accountParams = STPConnectAccountParams(tosShownAndAccepted: true, company: companyParams) else {
  // The TOS was not accepted
  return
}

STPAPIClient.shared.createToken(withConnectAccount: accountParams) { (accountToken, error) in
    if let error = error {
        // display an error to your user
    }
    else {
        // use account token to create a Connect account server-side
    }
}

Gestion d’un chargement de fichier

Lorsqu’un compte connecté doit fournir à Stripe une copie d’une pièce d’identité (un passeport, par exemple), il est possible d’utiliser un token de compte. Cependant, le code JavaScript est un peu plus complexe, car le fichier doit être envoyé à Stripe dans le cadre d’une requête XHR. Dans ce flux, le code JavaScript effectue ce qui suit :

1. Interrompre la soumission du formulaire.
2. Si un fichier a été chargé, il l’envoie à Stripe et reçoit en retour un token de fichier.
3. Il ajoute l’ID du token de fichier à l’objet générique pour la requête de token de compte.
4. Il appelle la méthode stripe.createToken() pour demander un token.
5. Il envoie l’ID du token de compte reçu à votre serveur pour utilisation.

Pour commencer, ajoutez un élément fichier à votre formulaire. Le fichier chargé doit être une image en couleur (d’une taille inférieure à 8 000 px par 8 000 px), au format JPG, PNG ou PDF, et d’une taille inférieure à 10 Mo.

<input type="file" id="id-file" name="id-file" accept=".jpeg,.jpg,.png">

Ensuite, dans votre code JavaScript qui gère la soumission du formulaire, envoyez le fichier chargé à Stripe. Cet envoi doit intervenir avant la création du token de compte.

const data = new FormData();
data.append('file', document.querySelector('#id-file').files[0]);
data.append('purpose', 'identity_document');
const fileResult = await fetch('https://uploads.stripe.com/v1/files', {
  method: 'POST',
  headers: {'Authorization': 'Bearer 
pk_test_TYooMQauvdEDq54NiTphI7jx
'},
  body: data,
});
const fileData = await fileResult.json();

Enfin, insérez l’ID de fichier renvoyé dans l’attribut verification.document.front de l’objet générique fourni à l’appel createToken() :

const result = await stripe.createToken('account', {
  person: {
    first_name: document.querySelector('.inp-first-name').value,
    last_name: document.querySelector('.inp-last-name').value,
    address: {
      line1: document.querySelector('.inp-street-address1').value,
      city: document.querySelector('.inp-city').value,
      state: document.querySelector('.inp-state').value,
      postal_code: document.querySelector('.inp-zip').value,
    },
    verification: {
        document: {
            front: fileData.id,
            },
        },
    },
  tos_shown_and_accepted: true,
});

Mise à jour des renseignements sur l’entité juridique et la personne

Vous pouvez utiliser des tokens pour mettre à jour de manière sécurisée les informations relatives à l’entité juridique et à la personne d’un compte existant. Pour cela, il vous suffit de créer les tokens dont vous avez besoin en utilisant le même mixte de code HTML et de code JavaScript que ci-dessus, puis d’effectuer un appel de mise à jour de compte ou de mise à jour de personne en fournissant le nouvel ID de token.

Vous devez créer et fournir un nouveau token lorsque vous mettez à jour des données d’entité juridique précédemment définies à l’aide d’un token de compte.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

Pour vos mises à jour à l’aide de tokens, notez ce qui suit :

• Les nouvelles valeurs remplacent les valeurs existantes.
• Si aucune nouvelle valeur n’est fournie, la valeur existante est conservée.
• Vous ne pouvez pas supprimer une valeur existante.
• Le paramètre tos_shown_and_accepted est ignoré et peut être omis.
• Vous pouvez utiliser un token de compte ou de personne pour effectuer une mise à jour, indépendamment du fait qu’un token ait été utilisé ou non à l’origine lors de la création du compte ou de la personne.
• Si le compte ou la personne a été créé à l’origine à l’aide d’un token de compte, vous ne pouvez mettre à jour les valeurs qu’au moyen d’un autre token.

Par exemple, si vous créez un compte avec un token contenant simplement un nom et une date de naissance, vous pourrez créer ultérieurement un autre token contenant uniquement les informations d’adresse du client, puis effectuer un appel de mise à jour du compte pour ajouter les détails de l’adresse au compte.

Suppression des renseignements sur l’entité juridique et la personne

Pour effacer les informations sur une entité juridique ou une personne physique, ou pour définir explicitement une valeur nulle, transmettez une chaîne vide de mise à jour de compte ou de mise à jour de personne. Utilisez un appel de mise à jour et non un token, même si vous avez utilisé un token à l’origine. Vous pouvez uniquement affecter des chaînes vides à des attributs facultatifs (p. ex., la deuxième ligne d’une adresse). Vous ne pouvez pas les affecter à des attributs obligatoires.