Mit der Checkout Sessions API zum Payment Element migrieren

Zeigen Sie Ihre Einstellungen für Zahlungsmethoden an und aktivieren Sie die Zahlungsmethoden, die Sie unterstützen möchten. Sie müssen mindestens eine Zahlungsmethode aktiviert haben, um eine Checkout-Sitzung zu erstellen.

Standardmäßig aktiviert Stripe Karten und andere gängige Zahlungsmethoden, mit denen Sie mehr Kundinnen/Kunden erreichen können. Wir empfehlen jedoch, zusätzliche Zahlungsmethoden zu aktivieren, die für Ihr Unternehmen und Ihre Kundinnen/Kunden relevant sind. Weitere Informationen zur Unterstützung von Produkten und Zahlungsmethoden finden Sie auf der Seite Unterstützte Zahlungsmethoden und der Preisseite für Gebühren.

Legen Sie im SDK fest, dass mindestens die API-Version 2025-03-31.basil verwendet wird.

// 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,
});

Da Sie mit dem Payment Element mehrere Zahlungsmethoden akzeptieren können, empfehlen wir die Verwendung dynamischer Zahlungsmethoden, die automatisch aktiviert werden, wenn Sie payment_method_types nicht in der Checkout-Sitzung übergeben. Wenn diese Funktion aktiviert ist, wertet Stripe die Währung, Einschränkungen für Zahlungsmethoden und andere Parameter aus, um die Liste der für Ihre Kundinnen/Kunden verfügbaren Zahlungsmethoden zu ermitteln. Wir priorisieren Zahlungsmethoden, die die Konversionsrate erhöhen und für die Währung und den Standort der Kundinnen/Kunden am relevantesten sind.

Aktualisieren Sie Ihren Erstellungsaufruf für PaymentIntents, um stattdessen eine Checkout-Sitzung zu erstellen. In der Checkout Sessions-Instanz übergeben Sie:

• line_items: Stellt den Inhalt der Bestellung dar
• ui_mode: custom: Gibt an, dass Sie eingebettete Komponenten verwenden
• mode: payment: Gibt an, dass Sie einmalige Zahlungen für die Checkout-Sitzung akzeptieren
• return_url: Stellt die URL dar, an die Ihre Kundinnen/Kunden weitergeleitet werden, nachdem sie ihre Zahlung in der App oder auf der Website der Zahlungsmethode authentifiziert oder abgebrochen haben

Geben Sie außerdem die client_secret der Checkout-Sitzung für die spätere Verwendung an den Client zurück.

Jede Checkout-Sitzung generiert nach Bestätigung einen PaymentIntent. Wenn Sie zusätzliche Parameter aus Ihrer aktuellen Integration beim Erstellen eines PaymentIntent beibehalten möchten, sehen Sie sich die unter payment_intent_data verfügbaren Optionen an.

intent = Stripe::PaymentIntent.create({
  amount: 1099,
  currency: 'usd',
  payment_method_types: ['card'],
})

session = Stripe::Checkout::Session.create({
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {name: 'T-shirt'},
        unit_amount: 1099,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'custom',
  return_url: '{{RETURN_URL}}',
})

{
  clientSecret: session.client_secret,
}.to_json

Die Umstellung auf eingebettete Komponenten erfordert einen zusätzlichen Schritt, in dem die E-Mail-Adresse Ihrer Kundinnen/Kunden erfasst wird.

<input type="text" id="email" />
<div id="email-errors"></div>

stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    checkout.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
});

Sie können jetzt das Card Element und die Elemente der einzelnen Zahlungsmethoden durch das Payment Element ersetzen. Das Payment Element passt basierend auf der Zahlungsmethode und dem Land die zu erfassenden Eingabefelder automatisch an (z. B. Erfassung der vollständigen Rechnungsadresse), sodass Sie keine nutzerdefinierten Eingabefelder pflegen müssen.

Im folgenden Beispiel wird CardElement durch PaymentElement ersetzt:

<form id="payment-form">
  <div id="card-element">
  </div>
  <div id="payment-element">
    <!-- Mount the Payment Element here -->
  </div>
  <button id="submit">Submit</button>
</form>

const cardElement = elements.create("card");
cardElement.mount("#card-element");
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

Statt einzelne Bestätigungsmethoden wie stripe.confirmCardPayment oder stripe.confirmP24Payment zu verwenden, nutzen Sie checkout.confirm, um Zahlungsinformationen zu erfassen und an Stripe zu übermitteln.

Um die Checkout-Sitzung zu bestätigen, aktualisieren Sie Ihren Submit-Handler, sodass er checkout.confirm anstelle einzelner Bestätigungsmethoden verwendet.

Beim Aufruf versucht checkout.confirm, alle erforderlichen Aktionen durchzuführen, wie z. B. das Anzeigen eines 3DS-Dialogfelds oder die Weiterleitung an eine Bankautorisierungsseite. Nach der Bestätigung werden die Kundinnen/Kunden an die von Ihnen konfigurierte return_url weitergeleitet. Dies entspricht in der Regel einer Seite auf Ihrer Website, die den Status der Zahlung angibt.

Wenn Sie den gleichen Bezahlvorgang für Kartenzahlungen beibehalten möchten und Weiterleitungen nur für Zahlungsmethoden mit Weiterleitung vornehmen möchten, können Sie die Weiterleitung auf if_required festlegen.

Im folgenden Codebeispiel wird stripe.confirmCardPayment durch checkout.confirm ersetzt:

// Create the PaymentIntent and obtain clientSecret
const res = await fetch("/create-intent", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
});

const {client_secret: clientSecret} = await res.json();

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: elements.getElement(CardElement)
    }
  });

  if (error) {
    handleError(error);
  }
};

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await checkout.confirm();

  if (error) {
    handleError(error);
  }
};

Stripe sendet das Ereignis checkout.session.completed, wenn die Zahlung abgeschlossen ist. Verwenden Sie das Webhook-Tool im Dashboard oder folgen Sie dem Leitfaden für Webhooks, um diese Ereignisse zu empfangen und Aktionen auszuführen. Dazu zählen beispielsweise der Versand von Bestellbestätigungen per E-Mail, das Protokollieren des Verkaufs in der Datenbank und die Einführung eines Versand-Workflows.

Überwachen Sie diese Ereignisse, statt auf einen Callback vom Client zu warten. Auf dem Client könnte der Kunde/die Kundin das Browserfenster schließen oder die App beenden, bevor der Callback erfolgt ist und böswillige Clients die Antwort manipulieren könnten. Wenn Sie Ihre Integration so einrichten, dass sie asynchrone Ereignisse überwacht, können Sie verschiedene Arten von Zahlungsmethoden mit einer einzigen Integration akzeptieren.

Neben der Abwicklung des checkout.session.completed-Ereignisses empfehlen wir die Abwicklung von diesen weiteren Ereignissen, wenn Sie Zahlungen mit dem Payment Element erfassen:

1. Navigieren Sie zu Ihrer Bezahlseite.
2. Geben Sie in den Zahlungsdetails eine Zahlungsmethode aus der folgenden Tabelle ein. Für Kartenzahlungen:
   • Geben Sie für die Karte ein beliebiges Ablaufdatum in der Zukunft ein.
   • Geben Sie als Prüfziffer/CVC eine 3-stellige Zahl ein.
   • Geben Sie eine beliebige Postleitzahl ein.
3. Zahlung an Stripe senden.
4. Gehen Sie zum Dashboard und suchen Sie auf der Seite Transaktionen nach der Zahlung. Wenn Ihre Zahlung erfolgreich war, wird sie in dieser Liste angezeigt.
5. Klicken Sie auf Ihre Zahlung, um weitere Details wie Rechnungsinformationen und die Liste der gekauften Artikel anzuzeigen. Sie können diese Informationen verwenden, um die Bestellung abzuwickeln.

Hier finden Sie weitere Informationen zum Testen Ihrer Integration.