Elements mit Checkout Sessions API-Änderungsprotokoll (Beta)

Verfolgen Sie Änderungen an der Beta-Integration der Elements with Checkout Sessions API.

Warnung

Dieses Dokument enthält Änderungsprotokolle im Zusammenhang mit Beta-Versionen von Elements mit der Checkout Sessions API.

Sollten Sie bereits die Clover-Version von Elements mit Checkout Sessions API verwenden, betrifft dieses Änderungsprotokoll Sie nicht.

Umstellung auf Clover

Clover-Änderungen

Breaking Die Methode stripe.initCheckout ist nun synchron statt asynchron. Dies reduziert die Render-Latenz und ermöglicht es Elements, Skeleton Loader früher anzuzeigen. Weitere Informationen zur Migration finden Sie unter Updates initCheckout to be synchronous.
Breaking Gespeicherte Zahlungsmethoden werden nun automatisch im Zahlungselement aktiviert, wenn sie in der Checkout-Sitzung konfiguriert sind, ohne dass eine zusätzliche Konfiguration auf Kundenseite erforderlich ist. Weitere Informationen finden Sie unter Aktualisiertes Standardverhalten für gespeicherte Zahlungsmethoden.
Breaking Postleitzahlen werden bei Kartenzahlungen in Kanada, dem Vereinigten Königreich und Puerto Rico nicht mehr automatisch erfasst. Bitte beachten Sie den Abschnitt Entfernen der Postleitzahl bei Kartenzahlungen, falls Sie auf diese Daten angewiesen sind.
Breaking Für React-Integrationen:
- Die Importpfade wurden von @stripe/react-stripe-js zu @stripe/react-stripe-js/checkout geändert.
- useCheckout gibt nun eine disjunkte Vereinigung zurück, die den asynchronen Status ({type: 'loading'}, {type: 'success', checkout: ...} oder {type: 'error', error: ...}) beschreibt anstatt einen Fehler auszulösen.
- CheckoutProvider rendert nun untergeordnete Elemente bedingungslos, anstatt null zu rendern, wenn initCheckout nicht erfolgreich war

Clover-Aktualisierung

Bevor Sie zu Clover migrieren, aktualisieren Sie zunächst Ihre Integration auf Basil.

Sollten Sie Stripe-NPM-Pakete verwenden, ist es erforderlich, @stripe/stripe-js auf mindestens 8.0.0 und @stripe/react-stripe-js auf mindestens 5.0.0 zu aktualisieren. .
Wenn Sie Stripe.js über das Script-Tag laden, aktualisieren Sie das Tag, um auf Clover zu verweisen, indem Sie die versionierte Stripe.js-Nomenklatur wie folgt verwenden:

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Aktualisieren Sie die API-Version in Ihrer Backend-Integration auf mindestens 2025-09-30.clover.

Aktualisieren Sie Ihre Integration wie folgt:

Entfernen Sie alle mit initCheckout verknüpften Aufrufe von wait oder .then().
Ersetzen Sie Ihre fetchClientSecret-Funktion durch eine Client-Geheimnis-Zeichenfolge oder ein Promise, das in eine Client-Geheimnis-Zeichenfolge aufgelöst wird.
Rufen Sie die neue asynchrone Funktion checkout.loadActions() auf, um auf Aktionen wie getSession() zuzugreifen, die session() ersetzt oder confirm(). Sie müssen loadActions() nur einmal aufrufen.
Wenn Sie zuvor initCheckout in einen try...catch-Block eingebunden haben, überprüfen Sie stattdessen den aufgelösten type-Wert von loadActions(), um Fehler zu erkennen.

checkout.js
const clientSecret = fetch("/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})
  .then((r) => r.json())
  .then((r) => r.clientSecret);

const checkout = await stripe.initCheckout({
  fetchClientSecret: () => clientSecret
});
const checkout = stripe.initCheckout({
  clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

const session = checkout.session();
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
}

Weitere Informationen finden Sie im Changelog-Eintrag Updates initCheckout synchronisieren.

Umstellung auf Basil

Basil-Änderungen

Breaking Asynchrone Methoden, z. B. „bestätigen“ oder applyPromotionCode, werden mit einem anderen Schema aufgelöst:
- Bei erfolgreicher Ausführung wird der aktualisierte Sitzungsstatus unter dem Schlüssel session aufgelistet. Zuvor befand sich dies unter dem Schlüssel success.
Breaking Bei der Übergabe von returnUrl auf confirm wird jetzt ein Fehler ausgegeben, wenn return_url bereits für die Checkout-Sitzung festgelegt wurde.
Breaking Die Rückgabe-URL, auf die nach einer erfolgreichen Bestätigung umgeleitet wurde, enthielt zuvor inkonsistente Abfrageparameter. Zusätzliche Parameter wurden jetzt entfernt und die URL enthält nur das, was in returnUrl on confirm oder return_url in der Checkout-Sitzung angegeben ist.
Breaking Verbessert die Latenz der Checkout Session API für Sitzungen im Abonnementmodus und behebt einen Fehler, durch den Ihre Kundinnen/Kunden eine Sitzung nach dem ersten Zahlungsversuch nicht aktualisieren konnten
- Bei der Änderung wird das Abonnement erstellt, nachdem der/die Nutzer/in die Zahlung abgeschlossen hat, sodass checkout_session.invoice und checkout_session.subscription bis zum Abschluss der Checkout-Sitzung null sind.
- Wenn Sie derzeit das abgeschaffte Feld payment_intent.invoice verwenden, empfehlen wir die Verwendung des Webhooks checkout_session.completed, der sicherstellt, dass eine Rechnung vorhanden ist, und checkout_session.invoice oder die Rechnungszahlungsliste, um die zugehörige Rechnung zu finden.
- Um mehr zu erfahren, lesen Sie den 2025-03-31.basil API changelog.
percentOff zu discountAmounts als Option hinzugefügt, um Rabatte anzuzeigen.

Basil-Aktualisierung

Vor der Migration zu Basil müssen Sie zuerst Ihre Integration auf custom_checkout_beta_6 aktualisieren.

Wenn Sie ein Stripe NPM-Paket verwenden, müssen Sie zuerst @stripe/stripe-js auf mindestens 7.0.0 und @stripe/react-stripe-js auf mindestens 3.6.0 aktualisieren.
Wenn Sie Stripe.js über das Skript-Tag laden und noch v3 oder acacia verwenden, aktualisieren Sie das Tag, um auf basil zu verweisen, indem Sie die versionierte Stripe.js-Nomenklatur wie folgt verwenden:

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/stripe.js"></script>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Entfernen Sie den Beta-Header von Stripe.js beim Initialisieren von Stripe.js.

checkout.js
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);

Entfernen Sie den Beta-Header der API-Version und geben Sie als API-Version mindestens 2025-03-31.basil für Ihre Backend-Integration an.

Vorher

Nachher

Beta-Änderungsprotokoll

Die Beta der Elements with Checkout Sessions API verwendet zwei Arten von Beta-Versionen:

Ein Stripe.js-Beta-Header (z. B. custom_checkout_beta_6), der in Ihrer Frontend-Integration festgelegt ist.
Eine API-Version des Beta-Headers (z. B. Custom_Checkout_beta=v1), die in Ihrer Backend-Integration festgelegt ist.

Beta-Versionen des Frontends

Geben Sie bei der Initialisierung von Stripe.js die Frontend-Beta-Version an.

custom_checkout_beta_6

Wenn Sie ein Stripe NPM-Paket verwenden, müssen Sie zuerst @stripe/stripe-js auf mindestens 6.1.0 und @stripe/react-stripe-js auf mindestens 3.5.0 aktualisieren.

Breaking Das Vorzeichen von total.appliedBalance wurde umgekehrt. Eine positive Zahl erhöht nun den zu zahlenden Betrag und eine negative Zahl verringert den zu zahlenden Betrag.
Breaking clientSecret wurde durch fetchClientSecret ersetzt. Aktualisieren Sie Ihre Integration, um anstelle eines statischen Werts eine asynchrone Funktion zu übergeben, die in das Client-Geheimnis aufgelöst wird.
Breaking Elements-Methoden wurden umbenannt.
- Wenn Sie React Stripe.js verwenden, müssen Sie nichts weiter tun, als @stripe/react-stripe-js zu aktualisieren.
- Wenn Sie HTML/JS verwenden:
  - Verwenden Sie createPaymentElement() statt createElement('payment').
  - Verwenden Sie createBillingAddressElement() statt createElement('address', {mode: 'billing'}).
  - Verwenden Sie createShippingAddressElement() statt createElement('address', {mode: 'shipping'}).
  - Verwenden Sie createExpressCheckoutElement() statt createElement('expressCheckout').
  - Verwenden Sie getPaymentElement() statt getElement('payment').
  - Verwenden Sie getBillingAddressElement() statt getElement('address', {mode: 'billing'}).
  - Verwenden Sie getShippingAddressElement() statt getElement('address', {mode: 'shipping'}).
  - Verwenden Sie getExpressCheckoutElement() statt getElement('expressCheckout').
Breaking Die Felder für die Bestätigung wurden aktualisiert, um den Sitzungsstatus genauer wiederzugeben.
- canConfirm reagiert jetzt auf jedes verbundene Billing Address Element oder Shipping Address Element.
- canConfirm wird jetzt false, wenn eine Bestätigung während der Übertragung vorliegt.
- confirmationRequirements wurde entfernt.
Breaking updateEmail gibt jetzt einen Fehler aus, wenn customer_email beim Erstellen der Checkout-Sitzung angegeben wurde. Wenn Sie beabsichtigen, eine E-Mail-Adresse, die Ihre Kundinnen/Kunden aktualisieren können, vorab anzugeben, rufen Sie updateEmail auf, sobald die Seite geladen ist, statt customer_email zu übergeben.
Breaking returnUrl muss eine absolute URL sein (beginnt beispielsweise mit https:// und nicht mit einer relativen URL, wie /success).
Breaking Preisfelder wurden zur Vereinfachung des Renderings in ein verschachteltes Objekt geändert.
- Numerische Werte wurden durch ein Objekt ersetzt, das amount (eine formatierte Währungszeichenfolge, z. B. $10.00) und minorUnitsAmount, eine Ganzzahl, die den Wert in der kleinsten Währungseinheit darstellt, enthält. Wenn Sie den Betrag bereits lesen, lesen Sie stattdessen minorUnitsAmount.
  - Ersetzen Sie beispielsweise total.total durch total.total.minorUnitsAmount.
- Sie müssen entweder total.total.amount oder total.total.minorUnitsAmount und currency und minorUnitsAmountDivisor aus dem checkout-Objekt lesen und in Ihrer Nutzeroberfläche anzeigen. Andernfalls wird ein Fehler ausgegeben. Dies hilft Ihnen, Ihre Bezahlseite mit Aktualisierungen der CheckoutSession zu synchronisieren, einschließlich des Hinzufügens zukünftiger Stripe-Funktionen mit minimalen Änderungen am Nutzeroberflächencode.
Steuer-IDs von Kundinnen/Kunden können jetzt erfasst werden. Erfahren Sie, wie Sie Steuer-IDs erfassen.
Unten auf Ihrer Bezahlseite ist jetzt ein Assistent nur für den Test-Modus verfügbar, der Anleitungen für Ihre Integration und Tastenkombinationen für gängige Testszenarien bietet.

custom_checkout_beta_5

Breaking Die Funktion initCustomCheckout wurde in initCheckout umbenannt
- In React Stripe.js wurde CustomCheckoutProvider in CheckoutProvider und useCustomCheckout in useCheckout umbenannt.
Breaking Um das Express Checkout Element zu bestätigen, rufen Sie confirm auf und übergeben Sie das Bestätigungsereignis als expressCheckoutConfirmEvent.
- Zuvor wurde das Express Checkout Element durch Aufrufen von event.confirm() bestätigt.
Breaking Wenn „bestätigen“ aufgerufen wird, validieren das Payment Element und das Address Element die Formulareingaben und geben etwaige Fehler aus.
Breaking Fehlermeldungen wurden vereinheitlicht und verbessert.
- Fehler, die von einer Funktion zurückgegeben/behoben werden, stellen bekannte Szenarien dar, wie z. B. ungültige Zahlungsdetails oder unzureichende Deckung. Dies sind vorhersehbare Probleme, die Sie Ihren Kundinnen/Kunden mitteilen können, indem Sie die message auf der Bezahlseite anzeigen.
- Fehler, die von einer Funktion ausgelöst/zurückgewiesen werden, stellen Fehler in der Integration selbst dar, z. B. ungültige Parameter oder eine ungültige Konfiguration. Diese Fehler sollen Ihren Kundinnen und Kunden nicht angezeigt werden.
Breaking Asynchrone Methoden, z. B. „bestätigen“ oder applyPromotionCode, werden mit einem anderen Schema aufgelöst:
- Das Diskriminatorfeld type="success"|"error" wurde hinzugefügt.
- Bei erfolgreicher Ausführung wird der aktualisierte Sitzungsstatus unter dem Schlüssel success aufgelistet. Zuvor befand sich dies unter dem Schlüssel session.
- Andernfalls wird der Fehler weiterhin unter dem Schlüssel error ausgefüllt.
Die Optionen email, phoneNumber, billingAddress und shippingAddress wurden zu „bestätigen“ hinzugefügt.
Breaking Das Address Element aktualisiert die Felder billingAddress oder shippingAddress in der Sitzung nicht mehr automatisch.
- Solange das Address Element verbunden ist, werden beim Aufruf von „bestätigen“ automatisch Formularwerte verwendet.
- Überwachen Sie das Änderungsereignis, um den Wert des Address Elements vor der Bestätigung zu verwenden.

custom_checkout_beta_4

Bilder zum Sitzungs-Objekt hinzugefügt.
Felder wurde als Option beim Erstellen des Payment Element hinzugefügt.
paymentMethods wurde als Option beim Erstellen des Express Checkout Element hinzugefügt.
Breaking Das Übergeben ungültiger Optionen an createElement löst jetzt einen Fehler aus. Zuvor wurden nicht erkannte Optionen stillschweigend ignoriert.
Breaking updateE-Mail und updatePhoneNumber wenden Änderungen asynchron an. Das Aufrufen dieser Methoden, bevor der Kunde/die Kundin die Eingabe vollständiger Werte abgeschlossen hat, kann zu beeinträchtigter Leistung führen.
- Anstatt updateEmail oder updatePhoneNumber bei jedem Änderungsereignis der Eingabe aufzurufen, warten Sie, bis Ihr Kunde/Ihre Kundin die Eingabe abgeschlossen hat, zum Beispiel bei einer unscharfen Eingabe oder wenn er/sie das Formular zur Zahlung einreicht.
- updateEmail überprüft jetzt, ob es sich bei der Eingabe um eine ordnungsgemäß gebildete E-Mail-Adresse handelt, und gibt einen Fehler zurück, wenn eine ungültige Eingabe verwendet wird.
- updatePhoneNumber führt immer noch keine Validierung der Eingabezeichenfolge durch.

custom_checkout_beta_3

Die folgenden Felder wurden zum Sitzungsobjekt hinzugefügt:
Gespeicherte Karten können nun wiederverwendet werden. Erfahren Sie, wie Sie Zahlungsmethoden speichern und wiederverwenden.
Breaking Das Standardlayout des Payment Element wurde in accordion geändert.
- Um das vorherige Standardlayout weiterhin zu verwenden, müssen Sie explizit layout='tabs' angeben.
Breaking Das Standardverhalten von confirm wurde so geändert, dass es nach einer erfolgreichen Bestätigung immer an Ihre return_url weitergeleitet wird.
- Bisher wurde confirm nur dann weitergeleitet, wenn der Kunde/die Kundin eine auf Weiterleitung basierende Zahlungsmethode gewählt hat. Um das bisherige Verhalten beizubehalten, müssen Sie redirect=‘if_required’ an confirm übergeben.

custom_checkout_beta_2

Breaking Das Feld lineItem.recurring.interval_count wurde entfernt und durch lineItem.recurring.intervalCount ersetzt.
Breaking Das Feld lineItem.amount wurde entfernt und durch Folgendes ersetzt:

custom_checkout_beta_1

Dies ist die erste Frontend-Betaversion.

Backend-Versionen

Geben Sie beim Einrichten Ihrer Server-Bibliothek die Backend-Beta-Version an.

Es werden keine Änderungen an der Betaversion vorgenommen.