Gestion des tokens

À propos des tokens

Les tokens sont des représentations virtuelles de cartes émises qui sont créées lorsqu’un titulaire de carte :

• Ajoute une carte à un portefeuille électronique comme Apple Pay ou Google Pay

• Enregistre un moyen de paiement pour son compte sur une vitrine en ligne ou un moyen de paiement intermédiaire

Vos clients peuvent utiliser des tokens lors du paiement sans exposer leurs informations de carte sensibles à chaque utilisation. Les tokens remplacent les informations de la carte, y compris le numéro, la date d’expiration et le code de vérification, réduisant ainsi le risque de vol des informations de la carte en cas de transaction frauduleuse. Puisque les informations de carte bancaire sensibles sont protégées, les tokens sont généralement considérés comme étant plus sûrs que les cartes physiques, ou la saisie manuelle des informations d’une carte dans un formulaire de paiement.

Les tokens sont pertinents pour les utilisateurs qui :

• Autorisent les titulaires de carte à dépenser avec Apple Pay, Google Pay ou Samsung Pay
• Ont un volume d’émission important pour les transactions en l’absence de carte (comme les achats en ligne)
• Souhaitent intégrer le comportement des tokens dans leur logique métier

Gestion des tokens

Stripe Issuing vous permet d’afficher et de gérer les informations associées à tous les tokens émis via votre programme à l’aide de l’API Tokens. Nous fournissons ces informations pour vous aider à mieux comprendre les caractéristiques de vos tokens et la façon dont ils sont utilisés. Vous trouverez par exemple des informations sur les principales caractéristiques suivantes :

• L’émetteur d’un token : indique si c’est un fournisseur de portefeuille électronique ou une entreprise qui demande le token.
• Le niveau de risque prévu d’un token : l’évaluation par le réseau de cartes du risque et sa recommandation pour un token donné.
• L’appareil associé à un token : indique s’il s’agit d’une montre, d’un téléphone ou de tout autre appareil qui demande le token, et l’évaluation du risque que représente cet appareil.
• Les caractéristiques du titulaire de la carte de l’émetteur du token : indiquent si les valeurs du titulaire de la carte, telles que son nom et son adresse correspondent à celles figurant sur son compte Stripe pour une vérification supplémentaire.

Outre la visibilité sur les caractéristiques des tokens, l’API Tokens vous permet d’activer, de suspendre ou de désactiver les tokens en fonction des workflows souhaités. Par exemple, vous pouvez choisir de le faire pour :

• Lorsque votre programme remplace une carte, vérifiez quels tokens existants sont migrés vers une nouvelle carte.
• Désactiver les tokens potentiellement associés à des activités frauduleuses sans affecter la carte sous-jacente.

L’objet issuing.authorization possède également un champ token qui se remplit s’il utilise un token.

Contrôles des risques

Lorsque nous recevons une demande de tokenisation, nous évaluons diverses variables pour déterminer si la demande doit être approuvée. À la suite de cette évaluation, nous choisissons l’une des solutions suivantes :

• Approuver la demande de tokenisation, créer le token et l’ajouter à un portefeuille électronique.
• Exiger une authentification supplémentaire, déclenchant une étape de vérification à l’aide d’un code secret à usage unique via le fournisseur de portefeuille électronique. Une fois l’authentification terminée, nous créons le token et l’ajoutons au portefeuille électronique correspondant. Dans ces scénarios, le champ d’état est requested jusqu’à la fin de l’authentification supplémentaire.
• Rejeter la demande de tokenisation, empêchant ainsi la création du token.

Les utilisateurs ont également la possibilité de mettre en place leurs propres contrôles de risque en plus de ceux de Stripe. L’API Tokens ne permet pas de rejeter purement et simplement une requête de tokenisation au moment de sa création, mais les utilisateurs peuvent désactiver ou suspendre les tokens peu de temps après leur création.

Fonctionnement des tokens

Découvrez le fonctionnement des tokens pour comprendre la façon dont ils sont créés et leur cycle de vie.

Créer un token

La création de tokens, ou tokenisation, est un processus en plusieurs étapes impliquant les titulaires de carte, les utilisateurs, un fournisseur de portefeuille électronique, Stripe et un réseau de cartes. L’exemple de scénario ci-dessous montre les étapes que le titulaire de la carte doit suivre et les processus impliqués lors de l’utilisation de l’API Tokens dans le cadre de votre programme.

Exemple de scénario

Un titulaire de carte participant à votre programme Issuing souhaite ajouter sa carte émise par Stripe à un portefeuille électronique, comme Apple Pay. Pour ce faire, il ouvre l’application de son portefeuille électronique et répond à des invites afin de saisir ses informations de titulaire de carte (comme son nom et son adresse de facturation) et les informations de sa carte (comme le numéro et la date d’expiration).

Ces informations sont ensuite soumises au fournisseur du portefeuille (dans ce cas, Apple Pay) qui est enregistré auprès du réseau sous-jacent de la carte (par exemple, Visa ou Mastercard) en tant que « demandeur de tokens » au sein du réseau. Ensuite, le réseau de cartes effectue une série de validations par rapport à ces données, les combine avec ses propres données dans une demande de tokenisation, et la transmet à Stripe afin qu’elle l’approuve ou la refuse. Stripe effectue sa propre validation supplémentaire pour déterminer comment traiter la requête. Comme indiqué précédemment sur cette page, cette étape de validation peut aboutir à trois résultats :

• Stripe approuve la tokenisation, ce qui active le token dans le portefeuille et le rend prêt à l’emploi. Stripe envoie l’événement issuing_token.created à tous les endpoints de webhook en écoute.
• Stripe exige une vérification supplémentaire, qui entraîne une demande d’authentification pour le titulaire de la carte. Stripe envoie l’événement issuing_token.created à tous les endpoints de webhook en écoute. Le token devient actif lorsque le titulaire de la carte finalise cette étape. Stripe envoie l’événement issuing_token.updated à tous les endpoints de webhook en écoute dès que le token est activé.
• Stripe refuse la demande de tokenisation, ce qui empêche l’ajout du token au portefeuille. Stripe n’envoie pas l’événement issuing_token.created aux endpoints de webhook en écoute.

Le fournisseur de portefeuille ou le réseau de cartes peuvent interrompre la poursuite d’une demande de tokenisation à n’importe quelle étape du processus. Dans ce cas, Stripe ne reçoit pas toujours de notification.

Le diagramme de séquence ci-dessous permet d’illustrer davantage le processus de tokenisation.

Cycle de vie du token

Une fois qu’un token est créé, il peut présenter quatre états distincts dans le portefeuille électronique :

• Inactif : la demande de token est en attente et le token ne peut pas encore être utilisé pour des autorisations. S’il est inactif dans l’API Tokens, il est à l’état requested.
• Suspendu : l’utilisation du token dans le portefeuille est momentanément indisponible. Un titulaire de carte ou un utilisateur Stripe utilisant l’API Tokens peut déclencher une suspension de token. Les titulaires de carte ne peuvent pas annuler les suspensions effectuées par un utilisateur Stripe (c’est-à-dire via une application de portefeuille électronique). Les utilisateurs peuvent uniquement réactiver les cartes suspendues directement via l’API Tokens.
• Actif : le token peut être utilisé dans le portefeuille auquel il a été ajouté.
• Supprimé : le token a été supprimé du portefeuille et vous ne pouvez plus l’utiliser. Vous ne pouvez pas modifier les tokens qui sont à cet état.

Le diagramme d’état ci-dessous montre les différents états, comment ils sont reflétés dans l’API et comment vous pouvez utiliser nos API pour les modifier.

Stripe synchronise automatiquement l’état du token avec l’état du titulaire de la carte et l’état de la carte lorsqu’ils changent. Stripe migre également les tokens entre les remplacements de carte si la carte d’origine n’est pas annulée en premier lieu. Pour voir quels tokens sont associés à quelle carte, utilisez l’API List.

Tokens de marchand

Les entreprises peuvent également créer des tokens lors de l’enregistrement d’un moyen de paiement pour une utilisation ultérieure chez un marchand (par exemple, un titulaire de carte enregistrant les informations de sa carte pour effectuer des paiements sur Amazon). Dans ces scénarios, l’entreprise est à l’origine de la création du token, et l’API Tokens n’aura pas le champ wallet_provider. Pour évaluer l’entreprise sous-jacente à l’origine du token, nous vous recommandons d’examiner les informations sur l’entreprise associées aux autorisations effectuées à l’aide du token. Si vous émettez des cartes Mastercard, les tokens qui en sont issus peuvent renseigner un nom lisible dans le fichier network_data.mastercard.token_requestor_name.

Les tokens de marchand sont liés à l’entreprise spécifique (le demandeur de token au sein du réseau de cartes) qui en est à l’origine et ne peuvent pas être utilisés par d’autres entreprises.

Déterminer quand un token a été utilisé pour une transaction

Les autorisations ou les transactions qui ont utilisé un token ont une référence extensible à l’objet Token dans l’attribut token. Ce champ est nul pour les autorisations ou les transactions qui n’ont pas utilisé de token. Combinez ce champ avec l’attribut wallet de l’objet Authorization ou Transaction, ou avec l’attribut wallet_provider de l’objet Token, pour déterminer si un token de portefeuille électronique a été utilisé.

Voir les autorisations et les transactions pour plus de détails.

Restrictions relatives aux données du réseau

L’objet token Issuing contient un champ développable facultatif appelé network_data. Il contient d’autres informations sensibles du réseau de cartes sur vos tokens, principalement liées au processus de création des tokens. Ces données étant très sensibles, vous devez disposer d’une clé d’accès restreint contenant les autorisations nécessaires pour accéder aux données, et vous pouvez uniquement afficher les données sur un token au cours des 24 heures suivant la création du token en question (en fonction de la valeur created). Ces données sont uniquement disponibles dans l’API permettant de récupérer un token et l’API permettant de mettre à jour l’état d’un token.

Pour accéder à ces données, configurez vos clés d’accès limité avec les autorisations suivantes :

• Accès en écriture aux tokens Issuing pour les méthodes Retrieve et List
• Accès en écriture aux tokens Issuing pour la méthode Update Status
• Accès en lecture aux données réseau du token Issuing pour accéder à network_data dans un délai de 24 heures

Si vous avez besoin d’accéder aux données network_data après la période initiale de disponibilité de 24 heures, vous devez limiter les addresses IP que vos clés d’accès limité utiliseront.

Tests

Le titulaire de carte d’un émetteur peut créer des tokens gratuitement dans des vitrines en ligne ou des portefeuilles électroniques. Nous vous recommandons d’en créer un dans le portefeuille électronique de votre choix pour comprendre les événements de webhook, les champs d’API et les effets de la mise à jour d’un token. Pour ce faire, suivez d’abord le guide sur les portefeuilles électroniques pour la mise en service manuelle.

Si vous préférez utiliser l’API Tokens en mode test, vous pouvez créer une autorisation en mode test en définissant le champ du portefeuille sur l’un des choix disponibles. Le champ token est défini sur l’autorisation résultante. Vous pouvez ensuite utiliser normalement les méthodes d’API sur ce token. Dans ces scénarios, tous les champs ne sont pas définis, y compris network_data, et ce token n’est pas utilisé pour les autorisations de test suivantes.

L’API Tokens

Les données des tokens sont uniquement accessibles via l’API Tokens. Voici quelques exemples d’applications.

Vérifier un exemple de mise en service manuelle réussie

• Dans cet exemple, vous vous abonnez aux événements issuing_token.created et issuing_token.updated.
• Lorsque vous recevez un événement issuing_token.created, utilisez l’API Retrieve et développez network_data pour afficher les détails de la mise en service. Voici un exemple :

{
  "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r",
  "object": "event",
  "api_version": "2024-11-20.acacia",
  "created": 1691100189,
  "data": {
    "object": {
      "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
      "object": "issuing.token",
      "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
      "created": 1691100179,
      "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs",
      "last4": "9203",
      "livemode": true,
      "network": "mastercard",
      "network_updated_at": 1691100170,
      "status": "requested",
      "wallet_provider": "apple_pay"
    }
  },
  "livemode": true,
  "pending_webhooks": 0,
  "request": {
    "id": "req_ARTvFhTufhHna9",
    "idempotency_key": "49a40678-8f45-4c91-9d6f-98a5bd569f9d"
  },
  "type": "issuing_token.created"
}

• Vérifiez que le champ ** wallet_provider ** est renseigné, ce qui vous indique qu’il provient d’un portefeuille électronique, et notez l’id de l’objet. Utilisez-le dans l’appel à l’API Retrieve :

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -d "expand[]"=network_data \
 -G

Cela donne la réponse suivante :

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "created": 1691100159,
  "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs",
  "last4": "9203",
  "livemode": true,
  "network": "mastercard",
  "network_data": {
    "device": {
      "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs",
      "ip_address": null,
      "location": "+30.22/-89.10",
      "name": "AB's phone",
      "phone_number": null,
      "type": "phone"
    },
    "mastercard": {
      "card_reference_id": "...",
      "token_reference_id": "...",
      "token_requestor_id": "...",
      "token_requestor_name": "APPLE PAY"
    },
    "type": "mastercard",
    "wallet_provider": {
      "account_id": null,
      "account_trust_score": null,
      "card_number_source": "manual",
      "cardholder_address": null,
      "cardholder_name": null,
      "device_trust_score": null,
      "hashed_account_email_address": null,
      "reason_codes": [],
      "suggested_decision": null,
      "suggested_decision_version": null
    }
  },
  "network_updated_at": 1691100170,
  "status": "requested",
  "wallet_provider": "apple_pay"
}

• Dans l’exemple, card_number_source est manual, l’état du token status est défini sur requested et il s’agit d’un portefeuille Apple Pay. Cela signifie que le titulaire de la carte avait les informations de la carte sur lui lorsqu’il a ajouté la carte à son portefeuille Apple, et qu’il doit effectuer une vérification supplémentaire avant de pouvoir utiliser la carte dans le portefeuille.
• Quelques secondes plus tard, vous pouvez voir un événement issuing_token.updated pour le même token. L’état du token est désormais active. Cela signifie que le titulaire de la carte a effectué la vérification avec succès et qu’il peut utiliser sa carte pour Apple Pay.

Exemple : supprimer un token de marchand suspect

• Dans cet exemple, vous vous abonnez à l’événement issuing_token.created.
• Le webhook reçoit un événement issuing_token.created.

{
  "object": {
    "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t",
    "object": "issuing.token",
    "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
    "created": 1691100179,
    "device_fingerprint": null,
    "last4": "9203",
    "livemode": true,
    "network": "visa",
    "network_updated_at": 1691100170,
    "status": "active"
  }
}

• Le token ne présente pas de champ wallet_provider, il s’agit donc d’un token de marchand. Utilisez l’API Retrieve et développez network_data pour afficher les détails de la mise en service.

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -d "expand[]"=network_data \
 -G

Cela donne la réponse :

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "created": 1691100186,
  "device_fingerprint": null,
  "last4": "4674",
  "livemode": true,
  "network": "visa",
  "network_data": {
    "visa": {
      // ...other fields
    },
    "type": "visa",
    "wallet_provider": {
      "card_number_source": "manual",
      "cardholder_address": null,
      "cardholder_name": "abc",
      // ...other fields
    }
  },
  "network_updated_at": 1691100170,
  "status": "active",
}

• Vous pouvez constater que la valeur nom du titulaire de la carte n’est pas valide et ne correspond pas au nom attendu du titulaire de la carte.
• Pour éviter toute activité frauduleuse, utilisez l’API Update Status pour supprimer le token avant de pouvoir l’utiliser. Ensuite, contactez le titulaire de la carte pour voir s’il a effectivement demandé le token. S’il ne l’a pas demandé, annulez la carte et remplacez-la si le numéro a été volé ou si le compte est compromis.

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -d status=deleted

Exemple de surveillance d’appareil

Comme dans les exemples précédents, abonnez-vous aux événements de token et effectuez une requête API Retrieve sur l’ID lorsque vous recevez un événement. Dans ce cas, vous constatez qu’une balise device_fingerprint est renseignée et vérifiez le champ network_data .device.location. Vous voyez que l’appareil a été configuré dans un autre pays à l’aide des coordonnées de localisation. Vous constatez que vous avez reçu une notification préalable vous informant que ce titulaire de carte voyageait à l’étranger et que le pays correspond au pays vers lequel il a indiqué se rendre.