Métadonnées
Comment utiliser des métadonnées pour enregistrer des informations supplémentaires.
Metadata est un attribut qui vous permet de stocker plus d’informations, structurées comme des paires clé-valeur, sur des objets Stripe, pour votre propre utilisation et référence. Par exemple, vous pouvez stocker l’identifiant unique correspondant de votre système sur un objet Stripe Customer.
Configuration
Données
Vous pouvez ajouter 50 paires clé-valeur au total dans ces limites de données :
- clé : limite de 40 caractères. Les crochets (
[]) ne peuvent pas être inclus dans les clés. - valeur : 500 caractères maximum.
Si votre système nécessite plus d’espace que cela, stockez vos données dans votre base de données externe et utilisez une paire clé-valeur pour stocker l’ID de l’objet externe dans metadata.
À moins que vous n’utilisiez des métadonnées avec Radar, Stripe n’utilise pas de métadonnées, par exemple, pour autoriser ou refuser un paiement. De plus, les métadonnées ne sont pas visibles par vos clients, sauf si vous choisissez de les afficher.
Conseil en matière de sécurité
Ne stockez jamais d’informations sensibles, que ce soit des informations bancaires ou de cartes, dans les métadonnées.
Demandes
Stripe ne renvoie des métadonnées que lorsque vous utilisez une clé secrète dans vos demandes. Nous expurgeons les métadonnées des objets en réponse aux demandes de clés publiables, telles que les demandes côté client de Stripe.js ou de SDK Mobile.
Ajouter et mettre à jour des métadonnées
Ajoutez des paires clé-valeur aux métadonnées, mettez à jour les valeurs des métadonnées et remplacez les clés à l’aide de l’API. Vous pouvez combiner différentes actions en une seule requête pour effectuer simultanément plusieurs ajouts, mises à jour et suppressions de métadonnées.
Ajouter des paires clé-valeur
Pour ajouter des paires clé-valeur aux métadonnées lors de la création d’un objet, fournissez les clés et les valeurs dans la requête de création d’objet.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573" } ... }
Ajouter des paires clé-valeur aux métadonnées existantes
Pour ajouter des paires clé-valeur aux métadonnées d’un objet existant, fournissez les clés et les valeurs dans une requête de mise à jour.
Note
Ce paramètre utilise un mécanisme de fusion qui vous permet d’ajouter de nouvelles paires clé-valeur à un objet lors d’un appel de mise à jour sans affecter les métadonnées existantes. Par exemple, si un objet Customer possède les key1 et key2, lorsque que vous le mettez à jour en ajoutant la key3, l’objet mis à jour contient les trois clés.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573", } ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no", "cms_id": "6573", } ... }
Mettre à jour des valeurs de métadonnées
Pour mettre à jour la valeur d’une clé existante dans les métadonnées, transmettez la nouvelle valeur à l’aide de la clé existante. Par exemple, vous pouvez mettre à jour un objet Customer avec une paire clé-valeur existante de "loyalty_ à"loyalty_.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no" } ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", } ... }
Mettre à jour des clés de métadonnées
Pour mettre à jour une clé ayant une valeur existante, supprimez-la et transmettez sa valeur à une nouvelle clé. Par exemple, vous pouvez mettre à jour un objet Customer en supprimant sa clé "loyalty_ et en transmettant la valeur "yes" de cette clé à une nouvelle clé "rewards_.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" } ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "rewards_program": "yes" } ... }
Supprimer des métadonnées
Supprimez une seule clé ou un ensemble de clés à l’aide de l’API.
Supprimer une seule clé
Transmettez la clé avec une chaîne vide en tant que valeur pour la supprimer des métadonnées.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" } ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", } ... }
Supprimer toutes les clés
Transmettez un objet vide en tant que valeur de l’attribut metadata pour supprimer toutes les clés simultanément.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" } ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": {} ... }
Copier les métadonnées vers un autre objet
Les métadonnées d’un objet ne sont pas automatiquement copiées dans les objets associés. Pour afficher les métadonnées d’un objet, vous devez l’inspecter. Pour récupérer les métadonnées d’un objet associé, vous devez développer une logique personnalisée afin de trouver et d’inspecter l’objet. Pour copier explicitement des métadonnées d’un objet à un autre, vous devez créer votre propre flux.
Exceptions
Dans certains cas, nous copions les métadonnées d’un objet à un autre à des fins de rétrocompatibilité et dans d’autres scénarios uniques.
| Mappage d’objets | Description |
|---|---|
| Payment Intent à Charge | Lorsqu’un Payment Intent crée un paiement, les métadonnées sont copiées dans le paiement sous la forme d’un aperçu unique. Les mises à jour des métadonnées du Payment Intent ne s’appliquent pas au paiement. |
| Payment Link à Checkout Session | Lorsqu’un Payment Link crée une session Checkout, les métadonnées sont copiées dans la session Checkout sous la forme d’un aperçu unique. Les mises à jour des métadonnées du Payment Link ne s’appliquent pas à la session Checkout. |
| Subscription à Invoice | Lorsqu’un abonnement crée une facture, les métadonnées sont copiées dans l’attribut subscription_details.metadata de l’objet Invoicing sous la forme d’un aperçu unique. Les mises à jour des métadonnées de l’abonnement ne s’appliquent pas à la facture. |
| Subscription à Invoice Line Item | Lorsqu’un type de poste de facture est défini sur subscription, il présente les métadonnées actuelles de l’abonnement. |
Définir indirectement des métadonnées
Certains endpoints acceptent un paramètre metadata imbriqué dans un autre paramètre. Vous pouvez utiliser ces paramètres lorsque vous créez un objet pour définir les métadonnées d’un objet sous-jacent. Par exemple, vous pouvez utiliser payment_ lorsque vous créez une session Checkout pour fournir et définir les métadonnées du Payment Intent sous-jacent créé par la session.
| Mappage d’objets | Description |
|---|---|
| Checkout Session à Payment Intent | Les données envoyées avec l’attribut payment_intent_data.metadata sont enregistrées dans les métadonnées du Payment Intent sous-jacent. |
| De la session d’achat à l’abonnement | Data sent with the subscription_data.metadata attribute saves to the underlying Subscription’s metadata. |
| Payment Link à Payment Intent | Les données envoyées avec l’attribut payment_intent_data.metadata sont enregistrées dans les métadonnées de chaque objet Payment Intent créé par l’objet Payment Link. |
| Payment Link à Subscription | Les données envoyées avec l’attribut subscription_data.metadata sont enregistrées dans les métadonnées de chaque objet Subscription créé par l’objet Payment Link. |
| Prices à Products | Les données envoyées avec l’attribut product_data.metadata sont enregistrées dans les métadonnées du produit associé. |
| Subscription Schedule à Subscription | Les données envoyées avec l’attribut phases.metadata sont enregistrées dans les métadonnées de l’objet Subscription sous-jacent lors de l’entrée dans la phase. |
| Quote à Subscription | Data sent with the subscription_data.metadata attribute saves to the Subscription’s metadata when a Quote is accepted. |
Événements et endpoints de webhook
Lorsque Stripe envoie un événement à votre endpoint de webhook, il inclut l’objet correspondant et toutes les métadonnées que l’objet contient. Cela permet à votre gestionnaire de webhooks de recevoir toutes les métadonnées que vous définissez sur les objets Stripe et de les transmettre aux processus en aval, tels que le traitement des commandes.
Par exemple, pour inclure un ID de panier lorsqu’un client effectue un achat à l’aide d’une session Checkout, indiquez-le en tant que métadonnées lors de la création du de la session Checkout :
Lorsque le client termine le processus de paiement, nous envoyons un événement checkout.session.completed contenant les métadonnées de l’objet Checkout Session à votre endpoint de webhook. Vous devez configurer votre webhook pour qu’il écoute cet événement afin de pouvoir accéder aux métadonnées et les utiliser lors du traitement des données.
{ "id": "evt_1P8pqUAgEBCHsfP6JfNctbLv", "object": "event", "api_version": "2022-11-15", "created": 1713903702, "data": { "object": { "id": "cs_test_a1aDQuoXLoddIOV9iOvZRgKAtPoRIfFkYHBWxF9AQAPlGG3STB1ndqqaUw", "object": "checkout.session", ... "metadata": { "cart_id": "6943" },
Rechercher des métadonnées
Vous pouvez rechercher des métadonnées existantes sur des objets pris en charge en utilisant un formatage spécifique. Il s’agit notamment de rechercher des enregistrements ayant une valeur spécifique pour un champ de métadonnées ou de vérifier si une clé de métadonnées est présente sur un objet. En savoir plus sur la recherche de métadonnées.
Éviter la fraude grâce aux métadonnées et à Radar
Utilisez des métadonnées avec Radar pour créer des règles personnalisées qui aident à éviter la fraude. En savoir plus sur les attributs de métadonnées de Radar.