API v2-Übersicht

Die Stripe-API bietet zwei Namespaces, die verschiedene Sätze von Endpoints enthalten:

• API v1: Der /v1-Namespace umfasst den größten Teil der bestehenden Stripe API.
• API v2: Der /v2-Namespace enthält Endpoints, die /v2-Designmuster verwenden.

Wesentliche Unterschiede zwischen dem v1- und dem v2-Namespace

SDKs, die API v2 unterstützen

Alle serverseitigen SDKs unterstützen APIs im Namespace /v2:

Verwenden Sie API v2 mit der Stripe-CLI

Verwenden Sie Stripe-Trigger und den Stripe-Listener, um die Ereignisbehandlung Ihrer Integration zu testen.

Verwenden Sie den Befehl /v2, um über die Stripe-CLI auf APIs im Namespace /v2 zuzugreifen. Um beispielsweise alle v2-Konten aufzulisten, können Sie die v2-Kernkontenliste von Stripe verwenden.

SDK-, CLI- und API -Versionierung

SDKs und die Stripe-CLI enthalten automatisch eine API-Version für alle Anfragen. Nachdem Sie Ihre SDK- oder CLI-Version aktualisiert haben, aktualisiert Stripe gleichzeitig die API-Version Ihrer Anfragen und Antworten.

Schließen Sie Stripe-Version ohne SDK oder CLI ein

Alle API-Anfragen an den API-/v2-Namespace müssen den Header Stripe-Version enthalten, um die zugrunde liegende API-Version anzugeben.

Eine Curl-Anfrage mit der API-Version 2024-09-30.acacia sieht beispielsweise wie folgt aus:

curl -G https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \

Verwenden von APIs aus den v1- und v2-Namespaces in derselben Integration

Sie können jede Kombination von APIs im Namespace /v1 oder /v2 in derselben Integration verwenden.

import com.stripe.StripeClient;

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

// Call a v2 API
EventDestination eventDestination = stripe.v2().core().eventDestinations().retrieve("ed_123");

// Call a v1 API
Customer customer = stripe.customers().retrieve("cus_123");

Wenn Sie weder ein offizielles SDK noch die CLI verwenden, nehmen Sie immer den Namespace in den URL-Pfad für Ihre API-Aufrufe auf. Beispiel:

# Call a v2 API
curl https://api.stripe.com/v2/core/event_destinations

# Call a v1 API
curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd

Listenpaginierung

APIs im Namespace /v2 (z. B. GET /v2/core/event_destinations) enthalten eine andere Paginierungsschnittstelle als diejenigen im Namespace /v1.

• Die Eigenschaft previous_page_url gibt eine URL zum Aufrufen der nächsten Seite der Liste zurück. Wenn es keine vorherigen Seiten gibt, ist der Wert null.
• Die Eigenschaft next_page_url gibt eine URL zurück, um die nächste Seite der Liste abzurufen. Wenn keine Seiten mehr vorhanden sind, ist der Wert null.

Sie können diese URLs verwenden, um Anfragen zu stellen, ohne unsere SDKs zu nutzen. Wenn Sie hingegen unsere SDKs nutzen, müssen Sie diese URLs nicht verwenden, da die SDKs die automatische Paginierung automatisch verarbeiten.

Sie können die Listenfilter nach der ersten Anfrage nicht mehr ändern.

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

EventDestinationListParams params = EventDestinationListParams.builder().build();

for (EventDestination eventDestination : stripe.v2().core().eventDestinations().list(params).autoPagingIterable()) {
  // process event destination object
}

Abfragen in API Anfragen verwenden

Verwenden Sie Filter für Listen-Endpoints, um die Ergebnisse einzuschränken. Verwenden Sie Include-Parameter für unterstützte GET-Endpoints, um zusätzliche Felder in der Antwort zurückzugeben. Mit Filtern und Include-Parametern können Sie ein Array von Werten übergeben. Wenn Sie direkte API-Anfragen stellen (keine serverseitigen SDKs oder die CLI verwenden), müssen Sie den Index des Array-Werts immer in Klammernotation angeben, auch wenn Sie nur einen einzigen Wert übergeben.

Um beispielsweise alle Konten aufzulisten, bei denen die applied_configuration merchant ist, übergeben Sie Folgendes:

curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

Verwenden Sie die folgende Syntax, um alle Konten aufzulisten, bei denen die Konfiguration merchant oder customer ist:

curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant&applied_configurations[1]=customer
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

Sie können dasselbe Muster für Include-Parameter verwenden. Um beispielsweise mehrere Felder in eine Antwort aufzunehmen, verwenden Sie die folgende Syntax:

curl -G https://api.stripe.com/v2/core/accounts/:id?include[0]=requirements&include[1]=defaults&include[2]=identity
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

In einigen Fällen ist ein Array innerhalb eines Abfrage-Parameters verschachtelt. Um beispielsweise eine Liste von Auszahlungen abzurufen, können Sie ein Array mit Werten angeben, die im verschachtelten Feld usage_status[payments] gefiltert werden sollen:

curl -G https://api.stripe.com/v2/money_management/payout_methods?usage_status[payments][0]=eligible&usage_status[payments][1]=invalid
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.preview" \

Idempotenz

Die APIs im /v2-Namespace bieten eine verbesserte Unterstützung für das Idempotenz-Verhalten. So werden unbeabsichtigte Nebeneffekte verhindert, wenn Anfragen mehrfach mit demselben Idempotenz-Schlüssel ausgeführt werden. Wenn die API zwei Anfragen mit demselben Idempotenz-Schlüssel erhält:

• Wenn die erste Anfrage erfolgreich war, überspringt die API neue Änderungen und gibt eine aktualisierte Antwort zurück.
• Wenn die erste Anfrage fehlgeschlagen ist (oder teilweise fehlgeschlagen ist), führt die API die fehlgeschlagenen Anfragen erneut aus und gibt die neue Antwort zurück.
• In dem seltenen Fall, dass eine idempotente Wiedergabe nicht mehr erfolgreich sein kann, gibt die API eine Fehlermeldung mit dem Grund für das Fehlschlagen zurück.

Eine Anfrage gilt als idempotente Wiederholung einer anderen Anfrage, wenn alle folgenden Bedingungen erfüllt sind:

• Sie denselben Idempotenzschlüssel für dieselbe API verwenden
• Sie treten im Rahmen desselben Kontos oder derselben Sandbox auf.
• Sie innerhalb von 30 Tagen nacheinander auftreten

Um einen Idempotenz-Schlüssel anzugeben, verwenden Sie den Header Idempotency-Key und geben einen eindeutigen Wert an, der den Vorgang darstellt (wir empfehlen eine UUID). Wenn kein Schlüssel angegeben wird, generiert Stripe automatisch eine UUID für Sie.

Alle API-API v2-Anfragen des Typs POST und DELETE akzeptieren Idempotenz-Schlüssel und verhalten sich idempotent. GET-Anfragen sind per Definition idempotent, sodass das Senden eines Idempotenz-Schlüssels keine Auswirkung hat.

Idempotenz-Unterschiede zwischen API v1 und API v2

Es gibt einige wichtige Idempotenz-Unterschiede zwischen API v1 und API v2:

• API v1 unterstützt nur die idempotente Wiedergabe für POST-Anfragen. API v2 unterstützt alle POST- und DELETE-Anfragen.
• Eine Anfrage wird als idempotente Wiederholung einer anderen Anfrage betrachtet, wenn:
  • API v1, wenn sie denselben Idempotenz-Schlüssel verwenden und innerhalb von 24 Stunden auftreten.
  • API v2 wenn sie denselben Idempotenzschlüssel verwenden, an dieselbe API gesendet werden, innerhalb desselben Kontos oder derselben Sandbox erfolgen und innerhalb von 30 Tagen nacheinander auftreten.
• Wenn Sie den gleichen Idempotenz-Schlüssel für zwei Anfragen angeben:
  • API v1 gibt immer die zuvor gespeicherte Antwort auf die erste API-Anfrage zurück, selbst wenn diese falsch war.
  • API v2 versucht, alle fehlgeschlagenen Anfragen zu wiederholen, ohne dass Nebeneffekte auftreten (jegliche unwesentliche Änderung oder beobachtbares Verhalten, die/das als Ergebnis eines API -Aufrufs auftreten) und eine aktualisierte Antwort zu liefern.

Idempotente Anfragen durchführen

Geben Sie mithilfe des SDK in API-Anfragen einen Idempotenz-Schlüssel mit der Eigenschaft idempotencyKey an.

So stellen Sie beispielsweise eine API-Anfrage mit einem bestimmten Idempotenz-Schlüssel:

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

String idempotencyKey = "unique-idempotency-key";
Example result = stripe.v2().examples().create(
        ExampleCreateParams.builder()
          .setName("My example")
          .build(),

        RequestOptions.builder()
          .setIdempotencyKey(idempotencyKey)
          .build());

Wenn Sie weder ein SDK noch eine CLI verwenden, können Anfragen den Header Idempotency-Key enthalten:

curl https://api.stripe.com/v2/examples \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Idempotency-Key: unique-idempotency-key" \
  -d <JSON request body>

Einschränkungen

• Sie können/v2-Endpoints jederzeit in einer Sandbox testen. Sie können auch einige v2-APIs, wie z. B. Nutzungsbasierte Abrechnung und Ereignisziele, im Test-Modus testen.
• Derzeit generiert Stripe nur Thin-Ereignisse mit den /v2-Endpoints und Ressourcen.
• Sie können nur Anforderungsprotokolle sehen, die von API v2 in Workbench generiert wurden, nicht im Entwickler-Dashboard.