# Métadonnées Comment utiliser des métadonnées pour enregistrer des informations supplémentaires. [Metadata](https://docs.stripe.com/api/metadata.md) 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](https://docs.stripe.com/api/customers.md). ## Configuration ### Données Si vous souhaitez afficher un seul champ aux clients, envisagez l’utilisation du paramètre `description`. 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](https://docs.stripe.com/radar.md), 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. > 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](https://docs.stripe.com/keys.md#obtain-api-keys) 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. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ -d "metadata[cms_id]=6573" ``` ```json { "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 valeurs dans une requête de mise à jour. Ce paramètre utilise un mécanisme de fusion, qui 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 `key1` et `key2`, et que vous ajoutez `key3`, l’objet mis à jour contient les trois clés. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ -d "metadata[loyalty_program]=no" ``` ### Before ```json { "id": "cus_NffrFeUfNV2Hib", "object": "customer", ..."metadata": { "cms_id": "6573" }, ... } ``` ### After ```json { "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](https://docs.stripe.com/api/customers.md) avec une paire clé-valeur existante de `"loyalty_program" : "no"` à`"loyalty_program" : "oui"`. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ -d "metadata[loyalty_program]=yes" ``` ### Before ```json { "id": "cus_NffrFeUfNV2Hib", "object": "customer", ..."metadata": { "loyalty_program": "no" }, ... } ``` ### After ```json { "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](https://docs.stripe.com/api/customers.md) en [supprimant](https://docs.stripe.com/metadata.md#delete-single-key) sa clé `"loyalty_program"` et en transmettant la valeur `"yes"` de cette clé à une nouvelle clé `"rewards_program"`. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ -d "metadata[loyalty_program]=" \ -d "metadata[rewards_program]=yes" ``` ### Before ```json { "id": "cus_NffrFeUfNV2Hib", "object": "customer", ..."metadata": { "loyalty_program": "yes" }, ... } ``` ### After ```json { "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. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ -d "metadata[loyalty_program]=yes" \ -d "metadata[loyalty_member_id]=" ``` ### Before ```json { "id": "cus_NffrFeUfNV2Hib", "object": "customer", ..."metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... } ``` ### After ```json { "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. #### curl ```bash curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} -u <> -d "metadata"="" ``` ### Before ```json { "id": "cus_NffrFeUfNV2Hib", "object": "customer", ..."metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... } ``` ### After ```json { "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 | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) vers [débit](https://docs.stripe.com/api/charges.md) | Lorsque qu’un PaymentIntent crée un débit, les métadonnées sont copiées dans le paiement sous forme de snapshot unique. Les mises à jour des métadonnées du PaymentIntent ne s’appliquent pas au paiement déjà créé. | | [Payment Link](https://docs.stripe.com/api/payment_links/payment_links.md) à [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) | 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](https://docs.stripe.com/api/subscriptions.md) à [Invoice](https://docs.stripe.com/api/invoices.md) | Lorsqu’un abonnement crée une facture, les métadonnées sont copiées dans l’attribut [parent.subscription_details.metadata](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-subscription_details-metadata) de l’objet Invoice dans un instantané ponctuel. Les mises à jour des métadonnées de l’abonnement ne s’appliquent pas à la facture. | | [Abonnement](https://docs.stripe.com/api/subscriptions.md) au [sous-poste de facture](https://docs.stripe.com/api/invoice-line-item/object.md) | Lorsque le [type](https://docs.stripe.com/api/invoice-line-item/object.md#invoice_line_item_object-type) d’un sous-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 lors de la création d’un objet pour définir des métadonnées sur un objet sous-jacent. Par exemple, vous pouvez utiliser `payment_intent_data.metadata` lors de la création d’une Checkout Session pour fournir et définir des métadonnées sur le PaymentIntent sous-jacent créé par la session. | Mappage d’objets | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Paiement](https://docs.stripe.com/api/checkout/sessions.md) vers [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Les données que vous incluez dans l’attribut [payment_intent_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-metadata) sont enregistrées dans les métadonnées du PaymentIntent correspondant. | | De la [session d’achat](https://docs.stripe.com/api/checkout/sessions.md) à l’[abonnement](https://docs.stripe.com/api/subscriptions.md) | Les données que vous incluez dans l’attribut [subscription_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-metadata) sont enregistrées dans les métadonnées de l’abonnement correspondant. | | [Lien de paiement](https://docs.stripe.com/api/payment_links/payment_links.md) vers [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Les données que vous incluez dans l’attribut [payment_intent_data.metadata](https://docs.stripe.com/api/payment-link/create.md#create_payment_link-payment_intent_data) sont enregistrées dans les métadonnées de chaque PaymentIntent créé par lien de paiement. | | [Payment Link](https://docs.stripe.com/api/payment_links/payment_links.md) à [Subscription](https://docs.stripe.com/api/subscriptions.md) | Les données que vous incluez dans l’attribut [subscription_data.metadata](https://docs.stripe.com/api/payment-link/create.md#create_payment_link-subscription_data) sont enregistrées dans les métadonnées de chaque abonnement créé par le lien de paiement. | | [Prices](https://docs.stripe.com/api/prices.md) à [Products](https://docs.stripe.com/api/products.md) | Les données que vous incluez dans l’attribut [product_data.metadata](https://docs.stripe.com/api/prices/create.md#create_price-product_data-metadata) sont enregistrées dans les métadonnées du produit associé. | | [Subscription Schedule](https://docs.stripe.com/api/subscription_schedules.md) à [Subscription](https://docs.stripe.com/api/subscriptions.md) | Les données que vous incluez dans l’attribut [phases.metadata](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-metadata) sont enregistrées dans les métadonnées de l’abonnement sous-jacent lorsque la phase est atteinte. | | [Quote](https://docs.stripe.com/api/quotes.md) à [Subscription](https://docs.stripe.com/api/subscriptions.md) | Les données que vous incluez dans l’attribut [subscription_data.metadata](https://docs.stripe.com/api/quotes/create.md#create_quote-subscription_data-metadata) sont enregistrées dans les métadonnées de l’abonnement lorsque le devis est accepté. | ## Événements et endpoints de webhook Lorsque Stripe envoie un [événement](https://docs.stripe.com/api/events.md) à votre [endpoint de webhook](https://docs.stripe.com/webhooks.md), 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](https://docs.stripe.com/api/checkout/sessions.md), indiquez-le en tant que métadonnées lors de la création du de la session Checkout : ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ --data-urlencode "success_url=https://example.com/success" \ -d mode=payment \ -d "line_items[0][price]=price_1MotwRLkdIwHu7ixYcPLm5uZ" \ -d "line_items[0][quantity]=1" \ -d "metadata[cart_id]=6943" ``` Lorsque le client termine le processus de paiement, Stripe envoie un événement [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) contenant les métadonnées de l’objet Checkout Session à votre endpoint webhook. Vous devez configurer votre webhook pour écouter cet événement afin de pouvoir accéder aux métadonnées et les utiliser lors du traitement des données. ```json { "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" }, ... } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "checkout.session.completed" } ``` ## 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](https://docs.stripe.com/search.md#metadata). ## É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](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes).