# Gestion des tokens Comment gérer les tokens réseau de vos cartes à l'aide d'Issuing. 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 les plus pertinents si vous : - Autorisez 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) - Souhaitez intégrer le comportement des tokens dans la logique de votre entreprise ## 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](https://docs.stripe.com/api/issuing/tokens.md). 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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider) qui demande le token. - **Le niveau de risque prévu d’un token :** l’évaluation par le réseau de cartes du [risque](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-visa-token_risk_score) et sa [recommandation](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-suggested_decision) 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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-device-type) qui demande le token, et l’[évaluation du risque](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-device_trust_score) 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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_name) et son [adresse](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_address) 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](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-status) est `requested` jusqu’à la fin de l’authentification supplémentaire. - Rejeter la demande de tokenisation, empêchant ainsi la création du token. Vous pouvez également mettre en place vos propres contrôles de risque en complément de ceux de Stripe. L’API Tokens ne permet pas de rejeter directement une demande de tokenisation au moment de sa création, mais vous pouvez désactiver ou suspendre les tokens peu 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 Stripe, un fournisseur de wallet, 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 wallet 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. Aperçu du flux de demande de mise en service réussie (See full diagram at https://docs.stripe.com/issuing/controls/token-management) ### 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. diagramme d'état du cycle de vie du token (See full diagram at https://docs.stripe.com/issuing/controls/token-management) 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](https://docs.stripe.com/api/issuing/tokens/list.md). ### 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 commerçant en ligne (par exemple, un titulaire de la carte enregistrant ses informations de carte pour un paiement chez 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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider). Pour évaluer l’entreprise sous-jacente à l’origine du token, examinez les [informations de l’entreprise](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-merchant_data) associées aux autorisations effectuées à l’aide du token. Si vous émettez des cartes à partir de MasterCard, les tokens qui en proviennent peuvent remplir un nom lisible dans le [champ network_data.mastercard.token_requestor_name](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-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](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider) de l’objet Token, pour déterminer si un token de portefeuille électronique a été utilisé. Voir les [autorisations](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-token) et les [transactions](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-token) pour plus de détails. ## Restrictions relatives aux données du réseau L’objet token Issuing contient un [champ développable](https://docs.stripe.com/api/expanding_objects.md) facultatif appelé [network_data](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-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](https://docs.stripe.com/keys.md#create-restricted-api-secret-key) 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](https://docs.stripe.com/api/issuing/tokens/retrieve.md) et l’API permettant de [mettre à jour l’état d’un token](https://docs.stripe.com/api/issuing/tokens/update.md). 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](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address) 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](https://docs.stripe.com/issuing/cards/digital-wallets.md) pour la mise en service manuelle. Si vous préférez utiliser l’API Tokens de test, vous pouvez créer une autorisation en de test en définissant le [champ du wallet](https://docs.stripe.com/api/issuing/authorizations/test_mode_create.md#test_mode_create_authorization-wallet) 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 : ```json { "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r", "object": "event", "api_version": "2026-03-25.dahlia", "created": 1691100189, "data": { "object": { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "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 : ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` Cela produit la réponse suivante : ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "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`. ```json { "object": { "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "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. ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` Cela donne la réponse : ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "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. ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <> \ -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.