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-Auslöser und Stripe-Überwachung, um die Handhabung von Ereignissen Ihrer Integration zu testen. Sie können mit der Stripe-CLI nicht auf APIs im Namespace /v2 zugreifen.

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
}

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.

Zwei Anfragen werden als idempotent betrachtet, wenn Folgendes auf sie zutrifft:

• Verwenden Sie denselben Idempotenz-Schlüssel für dieselbe API
• Sie finden im Geltungsbereich desselben Kontos oder derselben Sandbox statt
• Finden innerhalb der letzten 30 Tage der jeweils anderen statt

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.
• Wenn Folgendes zutrifft, werden zwei Anfragen als idempotent betrachtet:
  • API v1, wenn sie denselben Idempotenz-Schlüssel verwenden und innerhalb von 24 Stunden auftreten.
  • API v2, wenn sie denselben Idempotenz-Schlüssel verwenden, auf dieselbe API zugreifen, im Rahmen des Kontos oder der Sandbox auftreten und innerhalb von 30 Tagen erfolgen.
• 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

• Der Test-Modus unterstützt /v2 nicht. Sie können jedoch eine Sandbox verwenden, um in diesem Namespace zu 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.