Cas d'usage des métadonnées
Utilisez ces exemples pour enregistrer vos données sur des objets Stripe.
Utilisez metadata pour enregistrer vos données importantes sur les objets Stripe à l’aide de ces exemples courants. Les cas d’usage suivants ne sont pas exhaustifs ; la façon dont vous utilisez les métadonnées dépend de vos cas d’usage spécifiques.
Conseil en matière de sécurité
N’incluez pas d’informations sensibles dans metadata, telles que des données personnelles, des coordonnées bancaires ou des informations de cartes personnelles.
Enregistrer les ID des objets ou des enregistrements
Vous pouvez utiliser les métadonnées dans les objets Stripe pour enregistrer les ID qui appartiennent aux objets ou aux enregistrements de vos autres systèmes. Cela vous permet d’établir des références entre les objets Stripe et les ressources connexes de vos autres systèmes.
ID de commande ou de panier
Lorsque vous créez des ID pour suivre les paniers de vos clients, vous pouvez les enregistrer en tant que métadonnées sur les sessions Checkout. Cela vous permet d’utiliser l’objet Stripe associé pour localiser le panier associé dans votre système une fois le processus de paiement terminé.
Enregistrez l’ID du panier dans les métadonnées de la session Checkout après l’avoir créé :
Vous pouvez ensuite consulter, mettre à jour ou supprimer l’ID de l’objet Checkout Session. Il apparaît également dans les événements envoyés à votre endpoint webhook qui contiennent cette session Checkout (y compris l’événement checkout.).
{ "id": "evt_1PYCL6CzbZon1zn9VivIehz7", "object": "event", "api_version": "2024-06-20", "created": 1719948368, "data": { "object": { "id": "cs_test_a1Znb7gdtlLEPzSi8qMIJzvsSPpIBMKFWovXx0h0O43WS411PpICgCqKjw", "object": "checkout.session", ... "metadata": { "cart_id": "cart_6943" }, ... } }, ... "type": "checkout.session.completed", }
ID du client ou du CMS
Vous pouvez associer les objets Customer que vous créez dans Stripe aux enregistrements de votre système de gestion des clients (CMS) afin de faciliter le suivi et la gestion de vos clients.
Enregistrez l’ID de l’enregistrement client de votre CMS dans les métadonnées de l’objet Customer que vous créez dans Stripe.
Stripe inclut cette information dans les événements envoyés à votre endpoint webhook qui contiennent cet objet Customer. Par exemple, lorsque vous recevez des événements customer., vous pouvez utiliser l’ID enregistré afin d’identifier l’enregistrement que vous devez mettre à jour dans votre CMS.
{ "id": "evt_1PajAGCzbZon1zn9FUsn7IoG", "object": "event", "api_version": "2024-06-20", "created": 1720551204, "data": { "object": { "id": "cus_QRcNyZh9aZHXnI", "object": "customer", ... "metadata": { "cms_id": "cust_6573" }, ... } }, ... "type": "customer.updated" }
Suivi du traitement des commandes
Utilisez les métadonnées pour enregistrer des données qui facilitent vos processus de traitement des commandes ou permettent leur suivi.
ID de tarif ou de produit au niveau d’un Payment Intent
Lorsque vous créez directement des Payment Intents, vous pouvez les associer à vos products ou à vos prices à l’aide de métadonnées. Cela vous permet d’enregistrer l’ID des objets associés sur le Payment Intent, qui ne dispose pas d’un champ existant qui les associe à un tarif ou à un produit.
Vous pouvez localiser l’ID de l’objet associé dans les événements qui incluent ce Payment Intent, tels que les événements payment_. Transmettez ensuite les métadonnées de l’événement à vos processus en aval (par exemple, le traitement des commandes ou la gestion des stocks).
{ "id": "evt_3PajIyCzbZon1zn90b9Wvsqf", "object": "event", "api_version": "2024-06-20", "created": 1720551759, "data": { "object": { "id": "pi_3PajIyCzbZon1zn901xQeOdi", "object": "payment_intent", ... "metadata": { "price_id": "price_1MoBy5LkdIwHu7ixZhnattbh", "product_id": "prod_NWjs8kKbJWmuuc" }, ... } }, ... "type": "payment_intent.succeeded", }
État et suivi du traitement
Après avoir lancé votre flux de traitement des commandes, vous pouvez utiliser les métadonnées pour enregistrer l’état actuel du traitement sur l’objet Stripe associé. Cela vous permet de récupérer un objet de Stripe et de recevoir simultanément l’état du paiement et celui du traitement.
Pour mettre à jour l’état actuel du traitement :
Suivre les liens d’affiliation
Dans certains cas, Stripe copie metadata à partir de l’objet original vers un objet lié. Si vous avez des affiliés qui hébergent des Payment Links sur leur site et offrent des incitations pour les ventes provenant de ces liens, vous pouvez utiliser ce comportement dans votre suivi des affiliés.
Lorsque vous créez des liens de paiement, vous pouvez renseigner metadata en vue de suivre votre affilié :
Chaque fois qu’un client effectue un achat à partir de ce lien, Stripe crée une session Checkout qui hérite des métadonnées que vous avez fournies sur le lien de paiement. Vous pouvez surveiller les événements checkout. en vue de recevoir des notifications de Stripe lorsqu’un client effectue un achat. Vous pouvez alors extraire les détails de suivi de votre affilié à partir des métadonnées de la session Checkout afin d’attribuer la vente avec précision.
{ "id": "evt_1PajfeCzbZon1zn9S7pNlQkU", "object": "event", "api_version": "2024-06-20", "created": 1720553150, "data": { "object": { "id": "cs_test_a1zgRtgzjvamTgTnqMqIaqP6zehBIkaM03iYzxNjZiJ7FMDRRhibd5w3gL", "object": "checkout.session", ... "metadata": { "affiliate": "afl_7920" }, ... } }, ... "type": "checkout.session.completed", }
Notes du magasin
Vous pouvez utiliser les métadonnées pour enregistrer des notes sur les objets. Par exemple, pour créer une note indiquant l’heure d’appel préférée d’un client, ajoutez des métadonnées à l’objet Customer :
Pour enregistrer une note expliquant pourquoi une Invoice a été annulée, vous pouvez utiliser metadata au niveau de l’objet Invoice :
Définir indirectement des métadonnées
L’emplacement de vos métadonnées détermine les types d’événements qui contiennent les informations que vous indiquez. De même, si vous suivez certains types d’événements dans votre intégration, cela détermine l’endroit où vous placez vos métadonnées.
Certains points de terminaison de création d’objets contiennent plusieurs champs pour vos métadonnées : un pour enregistrer les métadonnées directement sur l’objet créé, et d’autres pour les définir sur les objets créés en aval. En savoir plus sur les champs de métadonnées indirects.
L’exemple suivant crée une session Checkout qui génère un abonnement lorsqu’elle est terminée. Il utilise le champ metadata de niveau supérieur et le champ subscription_ :
Vous pouvez définir des métadonnées sur l’objet que vous créez (dans ce cas, la session Checkout). Une fois que le client a terminé le processus de paiement, les métadonnées fournies précédemment dans subscription_ sont définies sur l’objet Subscription qui vient d’être créé. Cela détermine les événements qui incluent les métadonnées. Par exemple, les événements qui comprennent une session Checkout, tels que checkout., contiennent les valeurs fournies par le paramètre metadata de niveau supérieur.
{ "id": "evt_1PakshCzbZon1zn9PlQwJYn0", "object": "event", "api_version": "2024-06-20", "created": 1720557803, "data": { "object": { "id": "cs_test_a1lsYmNYnEqQAxHT9knVy8v7u7m5ChjKtyB3M68ovMCjUQgCADsCkUviUU", "object": "checkout.session", ... "metadata": { "checkout_metadata": "Checkout Session metadata goes here" }, ... } }, ... "type": "checkout.session.completed", }
Les événements qui incluent un objet Subscription, tels que customer., contiennent les valeurs fournies par subscription_. Cependant, comme cet événement comprend un objet Subscription, Stripe fournit les valeurs dans le champ metadata de niveau supérieur sur l’objet Subscription.
{ "id": "evt_1PaksgCzbZon1zn9x9u3MTSC", "object": "event", "api_version": "2024-06-20", "created": 1720557800, "data": { "object": { "id": "sub_1PaksdCzbZon1zn9D6DQjr9L", "object": "subscription", ... "metadata": { "subscription_metadata": "Subscription metadata goes here" }, ... } }, ... "type": "customer.subscription.created", }
Vous pouvez accéder aux métadonnées que vous avez fournies dans subscription_ dans les événements invoice. En effet, les métadonnées de l’abonnement sont transférées dans subscription_ sur les objets Invoice créés par l’abonnement.
{ "id": "evt_1PaksgCzbZon1zn9wD24BlvY", "object": "event", "api_version": "2024-06-20", "created": 1720557800, "data": { "object": { "id": "in_1PaksdCzbZon1zn9Z4bl0z7k", "object": "invoice", ... "subscription_details": { "metadata": { "subscription_metadata": "Subscription metadata goes here" } ... }, } }, ... "type": "invoice.finalized", }
Enregistrer de grandes quantités de métadonnées
Utilisez les champs de métadonnées dans Stripe pour enregistrer des données directement ou stocker une clé de recherche externe de façon à accéder à des données supplémentaires à partir de votre propre base de données. Cela limite les informations que vous devez récupérer.
Enregistrer des données structurées
Les métadonnées peuvent accepter n’importe quelle chaîne, y compris celles représentant des données structurées comme le format JSON, jusqu’à 500 caractères. Vous pouvez les utiliser pour enregistrer davantage de données dans vos champs de métadonnées. Cela réduit le nombre de clés auxquelles vous devez accéder pour récupérer toutes vos informations.
Enregistrer des métadonnées en externe
Pour associer à un objet des données dépassant les 500 caractères autorisés par les champs de métadonnées fournis, stockez les données excédentaires dans votre propre base de données. Vous pouvez ensuite utiliser les métadonnées pour enregistrer l’ID ou la clé de recherche permettant d’accéder à ces informations. Cette approche est similaire à l’enregistrement de l’ID de tout autre enregistrement dans votre système.
Utiliser les métadonnées avec d’autres API et produits Stripe
Vous pouvez utiliser les métadonnées avec d’autres API et produits Stripe afin d’améliorer leur flexibilité et leur extensibilité.
Radar
Vous pouvez définir des règles Radar pour faire référence à des valeurs de métadonnées et les utiliser afin de déterminer si une règle déclenche l’action qui lui est associée pour une transaction.
Effectuer un premier examen des transactions clients
Vous pouvez mettre en place un flux qui marque la première transaction d’un client pour examen, puis mettre à jour les informations du client afin de ne pas examiner les transactions suivantes.
Review if != 'true'
Stripe ne déclenche cette règle pour les paiements que si verified_ est défini sur false pour le client. Les clients pour lesquels ce paramètre est réglé sur true ne sont pas concernés.
Règles de tests A/B
Vous pouvez utiliser des métadonnées avec Radar pour créer des scénarios de test A/B pour les nouvelles règles. Cela vous permet d’évaluer l’efficacité d’une nouvelle règle avant de la mettre en œuvre pour l’ensemble de votre clientèle.
Block if = 'treatment' and :card_funding: = 'prepaid'
Stripe déclenche cette règle uniquement pour les paiements que vous désignez comme faisant partie du groupe de traitement. Cela n’affecte pas les paiements dont le paramètre experiment_ est défini sur control.
L’API Search
Utilisez l’API Search pour interroger et filtrer les résultats en fonction des métadonnées que vous avez définies pour les objets pris en charge que vous recherchez.
Par exemple, vous pouvez suivre vos clients « premium » en ajoutant des métadonnées à l’objet Customer. Pour leur proposer des promotions exclusives, utilisez l’API Search en vue d’identifier les clients marqués comme premium, puis contactez-les pour leur proposer la promotion.
Les objets doivent être indexés pour apparaître dans les résultats de l’API Search. Ils n’apparaîtront pas dans les résultats de recherche tant que l’indexation ne sera pas terminée.