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 /v2-Namespace.

API v2 mit der Stripe CLI verwenden

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.

Stripe-Version ohne SDK oder CLI einschließen

Alle API-Anfragen an den API-/v2-Namespace müssen den Stripe-Version-Header 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/events \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \
  -d object_id=fa_123

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
Event event = stripe.v2().core().events().retrieve("evt_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/events?object_id=mtr_123

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

Listenpaginierung

APIs im Namespace /v2 (zum Beispiel GET /v2/core/events) 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 verwenden. Wenn Sie jedoch unsere SDKs verwenden, müssen Sie diese URLs nicht verwenden, da die SDKs die automatische Paginierung durchführen.

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

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

EventListParams params =
  EventListParams.builder()
    .setObjectId("mtr_123")
    .build();

for (Event event : stripe.v2().core().events().list(params).autoPagingIterable()) {
  // process event 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 Idempotency-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.
• Zwei Anfragen werden als idempotent betrachtet, wenn:
  • 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 Idempotency-Key-Header 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>

Beschränkungen

• Der Testmodus 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.