Weiter zum Inhalt
Konto erstellen
 oder
anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellen
Anmelden
ÜbersichtAktualisieren Sie Ihre Integration
Online-Zahlungen
ÜbersichtIhren Use case findenZahlungen verwalten
Zahlungsmethoden
Zahlungsschnittstellen
Zahlungsszenarien
Präsenzzahlungen
Andere Stripe-Produkte

Elements mit Checkout Sessions API-Änderungsprotokoll (Beta)

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

Seite kopieren

Achtung

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

Wenn Sie bereits die Basil-Version von Elements mit der Checkout Sessions API verwenden, gilt diese Dokumentation nicht für Sie.

Umstellung auf 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.
    • Weitere Informationen finden Sie im API-Änderungsprotokoll.
  • percentOff zu discountAmounts als Option hinzugefügt, um Rabatte anzuzeigen.

Upgrade

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, aktualisieren Sie das Skript-Tag, um versioniertes Stripe.js zu verwenden, indem Sie das Tag wie folgt ersetzen:
checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></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
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-05-28.basil; custom_checkout_beta=v1' as any,
});
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil' as any,
});

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 für Ihre Frontend-Integration festgelegt wird.
  • Eine API-Version des Beta-Header (z. B. custom_checkout_beta=v1), die in Ihrer Backend-Integration festgelegt ist.

Beta-Versionen des Frontends

Geben Sie beim Initiieren von Stripe.js die Beta-Version des Frontends 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.
    • 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 „bestätigen“ 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

custom_checkout_beta_1

Dies ist die erste Frontend-Betaversion.

Änderungsprotokoll des Backend

Geben Sie die Beta-Version des Backends an, wenn Sie Ihre Serverbibliothek einrichten.

Es werden keine Änderungen an der Betaversion vorgenommen.

War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unser Änderungsprotokoll an.
Fragen? Sales-Team kontaktieren.
LLM? Lesen Sie llms.txt.
Unterstützt von Markdoc