Metadaten

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

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.

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.

{
  "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.

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.

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.

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.

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.

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.

Objektzuordnung	Beschreibung
Payment Intent und Zahlung	Wenn 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-Sitzung	Wenn 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 Rechnung	Wenn 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 Rechnungsposten	Wenn 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.

Objektzuordnung	Beschreibung
Checkout-Sitzung und Payment Intent	Die mit dem Attribut payment_intent_data.metadata gesendeten Daten werden in den Metadaten des zugrundeliegenden Payment Intent gespeichert.
Checkout-Sitzung und Abonnement	Daten, die mit dem Attribut subscription_data.metadata gesendet werden, werden in den Metadaten des zugrunde liegenden Abonnements gespeichert.
Zahlungslink mit Payment Intent	Daten, 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 Abonnement	Daten, die mit dem Attribut subscription_data.metadata gesendet werden, werden in den Metadaten jedes Abonnements gespeichert, das über den Zahlungslink erstellt wurde.
Preise und Produkte	Die mit dem Attribut product_data.metadata gesendeten Daten werden in den Metadaten des zugehörigen Produkts gespeichert.
Abonnementplan und Abonnement	Mit dem Attribut phases.metadata gesendete Daten werden in den Metadaten des zugrundeliegenden Abonnements gespeichert, wenn die Phase erreicht wird.
Angebot und Abonnement	Mit 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:

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.