Weiter zum Inhalt
Konto erstellen
oder
anmelden
Das Logo der Stripe-Dokumentation
/
KI fragen
Konto erstellen
Anmelden
Jetzt starten
Zahlungen
Finanzautomatisierung
Plattformen und Marktplätze
Geldmanagement
Entwickler-Tools
Jetzt starten
Zahlungen
Finanzautomatisierung
Jetzt starten
Zahlungen
Finanzautomatisierung
Plattformen und Marktplätze
Geldmanagement
Übersicht
Versionierung
Änderungsprotokoll
Aktualisieren Sie Ihre API-Version
Ihre SDK-Version aktualisieren
Entwickler-Tools
SDKs
API
    API v2
    API-Schlüssel
    Stripe-Context-Header
    Tägliches Änderungsprotokoll
    Ratenbegrenzungen
    Automatische Tests
    Metadaten
      Use cases für Metadaten
    Erweiterung der Antworten
    Paginierung
    Domains und IP-Adressen
    Suchen
    Lokalisierung
    Fehlerbehandlung
    Fehlercodes
Tests
Workbench
Ereignisziele
Arbeitsabläufe
Stripe-CLI
Stripe Shell
Entwickler-Dashboard
Agent-Toolkit
Mit LLMs entwickelnStripe für Visual Studio CodeStripe-StatuswarnungenHochgeladene Dateien
Sicherheit und Datenschutz
Sicherheit
Datenschutz
Extend Stripe
Stripe-Apps
Stripe Connectors
Partner
Partner-Ecosystem
Partner-Zertifizierung
StartseiteEntwickler-ToolsAPI

Metadaten

Erfahren Sie mehr darüber, wie Sie mit Metadaten zusätzliche Informationen speichern können.

Seite kopieren

Metadaten sind ein Attribut für bestimmte Stripe-Objekte, mit denen Sie weitere Informationen, strukturiert als Schlüssel-Wert-Paare, zu diesen Objekten für Ihre eigene Verwendung und Referenz speichern können. Beispielsweise können Sie die entsprechende eindeutige Nutzerkennung aus Ihrem System in einem Stripe-Kundenobjekt speichern.

Konfiguration

Daten

Innerhalb dieser Datengrenzen können Sie insgesamt 50 Schlüssel-Wert-Paare hinzufügen:

  • Schlüssel: Zeichenbegrenzung von 40 Zeichen. Eckige Klammern ([ ]) dürfen in Schlüsseln nicht enthalten sein.
  • Wert: Begrenzung auf 500 Zeichen.

Wenn Ihr System mehr Speicherplatz benötigt, speichern Sie Ihre Daten in Ihrer externen Datenbank und verwenden Sie ein Schlüssel-Wert-Paar, um die ID des externen Objekts in metadata zu speichern.

Wenn Sie auf Kundenseite ein einzelnes Feld anzeigen möchten, verwenden Sie description.

Stripe verwendet keine Metadaten, es sei denn, Sie verwenden Metadaten mit Radar, zum Beispiel um eine Zahlung zu autorisieren oder abzulehnen. Darüber hinaus sind Metadaten für Ihre Kundinnen/Kunden nicht sichtbar, es sei denn, Sie zeigen sie an.

Sicherheitshinweis

Speichern Sie niemals vertrauliche Informationen wie Bankkontodaten oder Kreditkartendaten in Metadaten.

Anfragen

Stripe gibt nur dann Metadaten zurück, wenn Sie in Ihren Anfragen einen geheimen Schlüssel verwenden. Wir entfernen Metadaten aus Objekten als Reaktion auf Anfragen nach veröffentlichbaren Schlüsseln, wie beispielsweise clientseitige Stripe.js- oder Mobile SDK-Anfragen.

Metadaten hinzufügen und aktualisieren

Fügen Sie mit der API Schlüssel-Wert-Paare zu Metadaten hinzu, aktualisieren Sie Metadatenwerte und ersetzen Sie Schlüssel. Sie können verschiedene Aktionen in einer einzigen Anfrage kombinieren, um mehrere Metadaten gleichzeitig hinzuzufügen, zu aktualisieren oder zu löschen.

Schlüssel-Wert-Paare hinzufügen

Um beim Erstellen eines Objekts Schlüssel-Wert-Paare zu Metadaten hinzuzufügen, geben Sie die Schlüssel und Werte in der Objekterstellungsanfrage an.

Command Line
cURL
curl https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d name="Jenny Rosen" \ -d "metadata[cms_id]"=6573
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573" }, ... }

Schlüssel-Wert-Paare zu bestehenden Metadaten hinzufügen

Um Schlüssel-Wert-Paare zu den Metadaten eines vorhandenen Objekts hinzuzufügen, geben Sie die Schlüssel und Werte in einer Aktualisierungsanfrage an.

Notiz

Dieser Parameter verwendet einen Mechanismus zum Zusammenfügen, mit dem Sie einem Objekt in einem Aktualisierungsaufruf neue Schlüssel-Wert-Paare hinzufügen können, ohne dass sich dies auf bestehende Metadaten auswirkt. Wenn ein Customer-Objekt beispielsweise key1 und key2 hat und Sie dieses so aktualisieren, dass key3 hinzugefügt wird, enthält das aktualisierte Objekt anschließend alle drei Schlüssel.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=no
Vorher
Nachher
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no", "cms_id": "6573" }, ... }

Metadatenwerte aktualisieren

Um den Wert für einen vorhandenen Schlüssel in den Metadaten zu aktualisieren, übergeben Sie den neuen Wert mit dem vorhandenen Schlüssel. Beispielsweise können Sie ein Customer-Objekt mit einem vorhandenen Schlüssel-Wert-Paar von "loyalty_program": "no" in"loyalty_program": "yes" aktualisieren.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=yes
Vorher
Nachher
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }

Metadatenschlüssel aktualisieren

Um einen Schlüssel mit einem vorhandenen Wert zu aktualisieren, löschen Sie den Schlüssel und übergeben Sie seinen Wert an einen neuen Schlüssel. Sie können beispielsweise ein Customer-Objekt aktualisieren, um den Schlüssel seines "loyalty_program" zu löschen und den Wert des Schlüssels "yes" an einen neuen Schlüssel "rewards_program"-Schlüssel übergeben.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"= \ -d "metadata[rewards_program]"=yes
Vorher
Nachher
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "rewards_program": "yes" }, ... }

Metadaten löschen

Löschen Sie einen einzelnen Schlüssel oder einen ganzen Satz von Schlüsseln mithilfe der API.

Einzelnen Schlüssel löschen

Übergeben Sie den Schlüssel mit einer leeren Zeichenfolge als Wert, um den Schlüssel aus den Metadaten zu entfernen.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=yes \ -d "metadata[loyalty_member_id]"=
Vorher
Nachher
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }

Alle Schlüssel löschen

Übergeben Sie ein leeres Objekt als Wert für das Attribut metadata, um alle Schlüssel gleichzeitig zu löschen.

Command Line
curl
curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
-u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
-d "metadata"=""
Vorher
Nachher
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": {} ... }

Metadaten in ein anderes Objekt kopieren

Die Metadaten eines Objekts werden nicht automatisch in zugehörige Objekte kopiert. Um die Metadaten eines Objekts anzuzeigen, müssen Sie dieses Objekt überprüfen. Um Metadaten von einem zugehörigen Objekt abzurufen, erstellen Sie eine nutzerdefinierte Logik, um das zugehörige Objekt zu finden und zu untersuchen. Um Metadaten explizit von einem Objekt in ein anderes zu kopieren, müssen Sie Ihren eigenen Ablauf erstellen.

Ausnahmen

In bestimmten Fällen kopieren wir Metadaten von einem Objekt in ein anderes, um Abwärtskompatibilität zu gewährleisten und andere individuelle Szenarien zu unterstützen.

ObjektzuordnungBeschreibung
Payment Intent und ZahlungWenn ein Payment Intent eine Zahlung erstellt, werden die Metadaten in einem einmaligen Snapshot in die Zahlung kopiert. Aktualisierungen an den Metadaten des Payment Intent gelten nicht für die Zahlung.
Zahlungslink und Checkout-SitzungWenn ein Zahlungslink eine Checkout-Sitzung erstellt, werden die Metadaten in einem einmaligen Snapshot in die Checkout-Sitzung kopiert. Aktualisierungen der Metadaten des Zahlungslinks gelten nicht für die Checkout-Sitzung.
Abonnement und RechnungWenn eine Rechnung für ein Abonnement erstellt wird, werden die Metadaten in einem einmaligen Snapshot in das Attribut parent.subscription_details.metadata des Rechnungsobjekts kopiert. Aktualisierungen an den Metadaten des Abonnements gelten nicht für die Rechnung.
Abonnement und RechnungspostenWenn der Typ eines Rechnungspostens auf subscription festgelegt wird, stellt er die aktuellen Metadaten des Abonnements dar.

Metadaten indirekt einrichten

Einige Endpoints akzeptieren einen metadata-Parameter, der in einem anderen Parameter verschachtelt ist. Sie können diese Parameter verwenden, wenn Sie ein Objekt erstellen, um Metadaten für ein zugrundeliegendes Objekt festzulegen. Beispielsweise können Sie payment_intent_data.metadata nutzen, wenn Sie eine Checkout-Sitzung erstellen, um Metadaten für den zugrundeliegenden Payment Intent bereitzustellen und festzulegen, der die Sitzung erstellt.

ObjektzuordnungBeschreibung
Checkout-Sitzung und Payment IntentDie mit dem Attribut payment_intent_data.metadata gesendeten Daten werden in den Metadaten des zugrundeliegenden Payment Intent gespeichert.
Checkout-Sitzung und AbonnementDaten, die mit dem Attribut subscription_data.metadata gesendet werden, werden in den Metadaten des zugrunde liegenden Abonnements gespeichert.
Zahlungslink mit Payment IntentDaten, die mit dem Attribut payment_intent_data.metadata gesendet werden, werden in den Metadaten jedes Payment Intent gespeichert, der über den Zahlungslink erstellt wurde.
Zahlungslink mit AbonnementDaten, die mit dem Attribut subscription_data.metadata gesendet werden, werden in den Metadaten jedes Abonnements gespeichert, das über den Zahlungslink erstellt wurde.
Preise und ProdukteDie mit dem Attribut product_data.metadata gesendeten Daten werden in den Metadaten des zugehörigen Produkts gespeichert.
Abonnementplan und AbonnementMit dem Attribut phases.metadata gesendete Daten werden in den Metadaten des zugrundeliegenden Abonnements gespeichert, wenn die Phase erreicht wird.
Angebot und AbonnementMit dem Attribut subscription_data.metadata gesendete Daten werden in den Metadaten des Abonnements gespeichert, wenn ein Angebot akzeptiert wird.

Ereignisse und Webhook-Endpoints

Wenn Stripe ein Ereignis an Ihren Webhook-Endpoint sendet, enthält es das entsprechende Objekt und alle Metadaten, die das Objekt enthält. Auf diese Weise kann Ihr Webhook-Handler alle Metadaten empfangen, die Sie für Stripe-Objekte festgelegt haben, und an nachgelagerte Prozesse wie die Bestellabwicklung übergeben.

Um beispielsweise eine Warenkorb-ID anzugeben, wenn ein Kunde/eine Kundin einen Kauf über eine Checkout-Sitzung tätigt, geben Sie diese beim Erstellen der Checkout-Sitzung als Metadaten an:

Command Line
cURL
curl https://api.stripe.com/v1/checkout/sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --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

Wenn der Kunde/die Kundin den Bezahlvorgang abschließt, senden wir das Ereignis checkout.session.completed, das die Metadaten des Checkout-Sitzungsobjekt enthält, an Ihren Webhook-Endpoint. Sie müssen Ihren Webhook so konfigurieren, dass er dieses Ereignis überwacht, damit Sie auf die Metadaten zugreifen und sie bei der Datenverarbeitung verwenden können.

{ "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" },

Metadaten durchsuchen

Sie können mithilfe einer bestimmten Formatierung nach vorhandenen Metadaten zu unterstützten Objekten suchen. Dazu gehört die Suche nach Datensätzen mit einem bestimmten Wert für ein Metadatenfeld oder die Überprüfung, ob ein Metadatenschlüssel für ein Objekt vorhanden ist. Hier erfahren Sie mehr über die Suche nach Metadaten.

Mit Metadaten und Radar Betrug verhindern

Verwenden Sie Metadaten mit Radar, um nutzerdefinierte Regeln zu erstellen, die dazu beitragen, Betrug zu verhindern. Erfahren Sie mehr über Radar-Metadatenattribute.

War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unser Änderungsprotokoll an.
Fragen? Sales-Team kontaktieren.
LLM? Lesen Sie llms.txt.
Unterstützt von Markdoc