# Auf das Express Checkout Element umstellen

Stellen Sie Ihre bestehende Integration mit dem Payment Request Button Element auf das Express Checkout Element um.

Mit dem [Payment Request Button Element](https://docs.stripe.com/stripe-js/elements/payment-request-button.md) können Sie Kartenzahlungen über [Apple Pay](https://docs.stripe.com/apple-pay.md), [Google Pay](https://docs.stripe.com/google-pay.md) oder [Link](https://docs.stripe.com/payments/link.md) annehmen. Wenn Sie zum [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) migrieren, können Sie Zahlungen mit Karten oder [Wallet](https://docs.stripe.com/payments/wallets.md) über eine oder mehrere Zahlungsschaltflächen akzeptieren, einschließlich [PayPal](https://docs.stripe.com/payments/paypal.md).

| Wenn Ihre bestehende Integration Folgendes verwendet                                                                                                                 | Gehen Sie wie folgt vor                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API zum Erstellen und Verfolgen von Zahlungen oder Speichern von Kartendaten während einer Zahlung | Befolgen Sie die Schritte in diesem Leitfaden, um das Express Checkout Element zu verwenden.                                      |
| [Charges](https://docs.stripe.com/api/charges.md) API mit Token                                                                                                      | Migrieren Sie zur [Payment Intents API](https://docs.stripe.com/payments/payment-intents/migration.md#web), bevor Sie fortfahren. |

## Zahlungsmethoden aktivieren

Aktivieren Sie die Zahlungsmethoden, die Sie unterstützen möchten, in Ihren [Einstellungen für Zahlungsmethoden](https://dashboard.stripe.com/settings/payment_methods). Sie müssen mindestens eine Zahlungsmethode aktivieren.

Standardmäßig aktiviert Stripe Karten und andere gängige Zahlungsmethoden. Sie können zusätzliche Zahlungsmethoden aktivieren, die für Ihr Unternehmen und Ihre Kundinnen und Kunden relevant sind. Informationen zur Unterstützung von Produkten und Zahlungsmethoden finden Sie auf der Seite [Unterstützung der Zahlungsmethode](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) und der [Preisseite](https://stripe.com/pricing/local-payment-methods) für Gebühren.

## Eine Elements-Instanz aktualisieren [Clientseitig]

Aktualisieren Sie als Nächstes Ihren clientseitigen Code, um den Modus (Zahlung), den Betrag und die Währung zu übergeben. Diese Werte bestimmen, welche Zahlungsmethoden Sie Ihren Kundinnen/Kunden anzeigen möchten.

Wenn Sie beispielsweise die Währung `eur` für die `PaymentIntent` übergeben und OXXO im Dashboard aktivieren, wird Ihrem Kunden/Ihrer Kundin OXXO nicht angezeigt, da OXXO keine `eur`-Zahlungen unterstützt.

Stripe überprüft die Währung, Einschränkungen der Zahlungsmethode und andere Parameter, um eine Liste der unterstützten Zahlungsmethoden zu erstellen. Wir priorisieren Zahlungsmethoden, die die Konversion erhöhen und für die Währung und den Standort der/s Kund/in am relevantesten sind.

#### HTML + JS

### Before

```javascript
const stripe =
    Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const elements = stripe.elements();
```

### After

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};
const elements = stripe.elements(options);
```

#### React

### Before

```jsx
 const stripePromise =
     loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

 function App() {
  return (
    <Elements stripe={stripePromise}>
      <CheckoutForm />
    </Elements>
  );
};
```

### After

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## Optional: Zahlungsdaten beim Bezahlvorgang speichern

Wenn Ihre bestehende Integration Kartenangaben während einer Zahlung speichert, verwenden Sie beim Erstellen der Elements-Instanz die Option `setup_future_usage`, anstatt sie bei der Zahlungsbestätigung mit `stripe.confirmCardPayment` zu übergeben.

Bestimmte Zahlungsmethoden können während der Zahlung nicht gespeichert werden. Sie können diese [Zahlungsmethoden](https://docs.stripe.com/payments/payment-methods/integration-options.md) weiterhin für andere Anwendungsszenarien aktivieren, aber Kundinnen/Kunden werden sie nicht sehen, wenn sie zukünftige Zahlungen einrichten.

#### HTML + JS

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};
const elements = stripe.elements(options);
```

#### React

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## Aktualisieren Sie Ihren Erstellungsaufruf für PaymentIntents [Serverseitig]

Der `PaymentIntent` enthält die Zahlungsmethoden, die Ihren Kundinnen und Kunden während des Bezahlvorgangs angezeigt werden. Zahlungsmethoden können Sie über das [Dashboard](https://dashboard.stripe.com/settings/payment_methods) verwalten. Stripe handhabt die Rückgabe geeigneter Zahlungsmethoden basierend auf Faktoren wie Betrag, Währung und Zahlungsablauf der Transaktion.

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-03-25.dahlia" \
  -d "amount"=1099 \
  -d "currency"="usd" \-d "automatic_payment_methods[enabled]"=true \
```

Wenn Ihre bestehende Integration mehrere Zahlungsmethoden unterstützt oder Sie zusätzlich zu Karten weitere Zahlungsmethoden nutzen möchten, können Sie im Dashboard [weitere Zahlungsmethoden aktivieren](https://dashboard.stripe.com/settings/payment_methods).

## Das Express Checkout Element hinzufügen [Clientseitig]

Wenn Sie [React Stripe.js](https://github.com/stripe/react-stripe-js) verwenden, führen Sie eine Aktualisierung auf das neuste Paket durch, um das Express Checkout Element zu nutzen.

Ersetzen Sie das Payment Request Button Element durch das Express Checkout Element. Die folgenden Beispiele zeigen, wie `PaymentRequestButtonElement` durch `ExpressCheckoutElement` ersetzt wird.

Sie müssen kein `paymentRequest`-Objekt mehr erstellen. Übergeben Sie stattdessen die Optionen beim Erstellen von `ExpressCheckoutElement`.

#### HTML + JS

### Before

```html
<div id="payment-request-button">
</div>
```

### After

```html
<div id="express-checkout-element">
  <!-- Mount the Express Checkout Element here -->
</div>
```

### Before

```javascript
const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1099,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});
const paymentRequestButton = elements.create('paymentRequestButton', {
  paymentRequest: paymentRequest,
});
paymentRequestButton.mount("#payment-request-button");
paymentRequest.canMakePayment().then(function(result) {
  if (result) {
    paymentRequestButton.mount('#payment-request-button');
  } else {
    document.getElementById('payment-request-button').style.display = 'none';
  }
});
```

### After

```javascript
const expressCheckoutElement = elements.create("expressCheckout", {
  emailRequired: true
});
expressCheckoutElement.mount("#express-checkout-element");
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const [paymentRequest, setPaymentRequest] = useState(null);

  useEffect(() => {
    if (stripe) {
      const pr = stripe.paymentRequest({
        country: 'US',
        currency: 'usd',
        total: {
          label: 'Demo total',
          amount: 1099,
        },
        requestPayerName: true,
        requestPayerEmail: true,
      });

      pr.canMakePayment().then(result => {
        if (result) {
          setPaymentRequest(pr);
        }
      });
    }
  }, [stripe]);

  return (
    paymentRequest && <PaymentRequestButtonElement options={{paymentRequest}} />
  );
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    emailRequired: true
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElement
        options={options}
        onConfirm={onConfirm}
      />
    </div>
  );
};
```

## Optional: Apple Pay-Händler-Token (MPAN) anfordern

Das Express Checkout Element unterstützt Apple Pay-Händler-Token, die wir gegenüber Geräte-Tokens empfehlen, um vom Händler initiierte Transaktionen (MIT) wie wiederkehrende und verzögerte Zahlungen und automatische Aufladungen zu ermöglichen. Händler-Token (MPANs) verbinden Ihr Unternehmen mit der Zahlungsmethode der Apple Wallet Ihrer Kundinnen und Kunden. Dadurch funktionieren die Zahlungsmethoden geräteübergreifend und Zahlungsinformationen bleiben auch auf neuen Geräten aktiv – selbst dann, wenn diese von einem verloren gegangenen oder gestohlenen Gerät entfernt wurden. Weitere Informationen zur Integration finden Sie unter [ApplePay Händler-Token](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=ece).

## Optional: Überwachen Sie das Ereignis „Ready“

Nach der Bereitstellung zeigt das Express Checkout Element für kurze Zeit keine Schaltflächen an. Sie können das Element animieren, wenn Schaltflächen angezeigt werden. Überwachen Sie dazu das [Ereignis „Ready“](https://docs.stripe.com/js/element/events/on_ready) und prüfen Sie den Wert von `availablePaymentMethods`, um zu bestimmen, welche Schaltflächen gegebenenfalls im Express Checkout Element angezeigt werden.

#### HTML + JS

```javascript
// Optional: If you're doing custom animations, hide the Element
const expressCheckoutDiv = document.getElementById('express-checkout-element');
expressCheckoutDiv.style.visibility = 'hidden';

expressCheckoutElement.on('ready', ({availablePaymentMethods}) => {
  if (!availablePaymentMethods) {
    // No buttons will show
  } else {
    // Optional: Animate in the Element
    expressCheckoutDiv.style.visibility = 'initial';
  }
});
```

#### React

```jsx
import React, {useState} from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';
import {onConfirm} from './confirmHandler';

const CheckoutPage = () => {
  // Optional: If you're doing custom animations, hide the Element
  const [visibility, setVisibility] = useState('hidden');
const onReady = ({availablePaymentMethods}) => {
    if (!availablePaymentMethods) {
      // No buttons will show
    } else {
      // Optional: Animate in the Element
      setVisibility('initial');
    }
  };

  return (
    <div id="checkout-page">
      <div id="express-checkout-element" style={{visibility}}>
        <ExpressCheckoutElement
          onConfirm={onConfirm}onReady={onReady}
        />
      </div>
    </div>
  );
};
```

## Optional: Gestalten Sie das Express Checkout Element

Sie können die Schaltflächen für jede Schaltfläche für Zahlungsmethoden mit verschiedenen Designs oder Typen [anpassen](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme) (z. B. [Google Pay](https://developers.google.com/pay/api/web/guides/resources/customize) oder [Apple Pay](https://developer.apple.com/design/human-interface-guidelines/technologies/apple-pay/buttons-and-marks/)).

Sie können auch die Variable `borderRadius` in der [Appearance](https://docs.stripe.com/elements/appearance-api.md?platform=web#commonly-used-variables) API verwenden.

#### HTML + JS

### Before

```javascript
elements.create('paymentRequestButton', {
  paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'book',
      theme: 'dark',
      height: '55px',
    },
  },
});
```

### After

```javascript
const appearance = {
  variables: {
    // This controls the border-radius of the rendered Express Checkout Element.
    borderRadius: '4px',
  }
};
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  appearance,
};
// Pass the appearance object to the Elements instance.
const elements = stripe.elements(options);
elements.create('expressCheckout', {
  layout: 'auto',
  buttonType: {
    googlePay: 'book',
    applePay: 'book',
    paypal: 'buynow',
  },
  buttonTheme: {
    applePay: 'black'
  },
  buttonHeight: 55
});
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const options = {
    paymentRequest,
    style: {
      paymentRequestButton: {
        type: 'book',
        theme: 'dark',
        height: '55px',
      },
    }
  };

  return <PaymentRequestButtonElement options={options} />;
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    layout: 'auto',
    buttonType: {
      googlePay: 'book',
      applePay: 'book',
      paypal: 'buynow',
    },
    buttonTheme: {
      applePay: 'black'
    },
    buttonHeight: 55
  }

  return (
    <ExpressCheckoutElementoptions={options}
      onConfirm={onConfirm}
    />
  );
};
```

## Die Bestätigung der Zahlungsmethode aktualisieren [Clientseitig]

Überwachen Sie das Ereignis [bestätigen](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event), um die Bestätigung zu verarbeiten. Um Zahlungsinformationen zu erfassen und an Stripe zu übermitteln, verwenden Sie [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) anstelle einzelner Bestätigungsmethoden wie `stripe.confirmCardPayment`.

Anstelle einer PaymentMethod-ID verwendet `stripe.confirmPayment` die Elements-Instanz aus dem Express Checkout Element und das Client-Geheimnis aus dem erstellten `PaymentIntent`.

Beim Aufruf versucht `stripe.confirmPayment`, alle erforderlichen Aktionen durchzuführen, wie z. B. die Authentifizierung Ihrer Kundinnen/Kunden durch Anzeigen eines 3DS-Dialogfelds oder die Weiterleitung an eine Bankautorisierungsseite. Nach der Bestätigung werden Nutzer/innen an die von Ihnen konfigurierte [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) weitergeleitet. Diese entspricht einer Seite auf Ihrer Website, die den Zahlungsstatus angibt.

Wenn Sie möchten, dass der Bezahlvorgang für Kartenzahlungen nur für Zahlungen umgeleitet wird, die dies erfordern, können Sie [weiterleiten](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) auf `if_required` einstellen. Dies gilt nicht für das Express Checkout Element.

Im folgenden Beispiel wird `stripe.confirmCardPayment` durch `stripe.confirmPayment` ersetzt.

#### HTML + JS

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```javascript
expressCheckoutElement.on('confirm', async (event) => {
  const {error} = await stripe.confirmPayment({
    // `Elements` instance that's used to create the Express Checkout Element.
    elements,
    // `clientSecret` from the created PaymentIntent
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
    // Uncomment below if you only want redirect for redirect-based payments.
    // redirect: 'if_required',
  });

  if (error) {
    // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
  } else {
    // Your customer will be redirected to your `return_url`.
  }
});
```

#### React

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const onConfirm = async () => {
    const {error} = await stripe.confirmPayment({
      // `Elements` instance that's used to create the Express Checkout Element.
      elements,
      // `clientSecret` from the created PaymentIntent
      clientSecret,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
      // Uncomment below if you only want redirect for redirect-based payments.
      // redirect: 'if_required',
    });

    if (error) {
      // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
    } else {
      // Your customer will be redirected to your `return_url`.
    }
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElementonConfirm={onConfirm}
      />
    </div>
  );
};
```

## Ereignisse nach der Zahlung verarbeiten [Serverseitig]

Stripe sendet ein [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded)-Ereignis, wenn die Zahlung abgeschlossen ist. Verwenden Sie [Webhook-Tool im Dashboard](https://dashboard.stripe.com/webhooks) oder folgen Sie der [Webhook-Anleitung](https://docs.stripe.com/webhooks/quickstart.md), um diese Ereignisse zu empfangen und führen Sie Aktionen aus, wie beispielsweise das Senden einer Bestellbestätigung per E-Mail, das Protokollieren des Verkaufs in der Datenbank oder das Starten eines Versand-Workflows.

Überwachen Sie diese Ereignisse, statt auf einen Callback vom Client zu warten. Auf dem Client könnten die Kund/innen das Browserfenster schließen oder die App beenden, bevor der Callback erfolgt ist. Bösartige Clients könnten dann die Antwort manipulieren. Wenn Sie Ihre Integration so einrichten, dass sie asynchrone Ereignisse überwacht, können Sie [verschiedene Arten von Zahlungsmethoden](https://stripe.com/payments/payment-methods-guide) mit einer einzelnen Integration akzeptieren.

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

| Ereignis                                                                                                                        | Beschreibung                                                                                                                                                                                                                                                                                                                                         | Aktion                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Wird gesendet, wenn Kundinnen und Kunden eine Zahlung erfolgreich abgeschlossen haben.                                                                                                                                                                                                                                                               | Senden Sie den Kund/innen eine Auftragsbestätigung und *wickeln* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) Sie die Bestellung ab.   |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Wird gesendet, wenn eine/e Kund/in eine Zahlung erfolgreich veranlasst hat, die Zahlung aber noch nicht abgeschlossen ist. Dieses Ereignis wird am häufigsten gesendet, wenn der Kunde/die Kundin eine Bankabbuchung veranlasst. In Zukunft folgt darauf entweder ein `payment_intent.succeeded`- oder ein `payment_intent.payment_failed`-Ereignis. | Senden Sie eine Bestellbestätigung an die Kund/innen, in der angegeben ist, dass die Zahlung noch aussteht. Bei digitalen Waren können Sie die Bestellung abwickeln, bevor Sie darauf warten, dass die Zahlung erfolgt. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Wird gesendet, wenn ein Kunde/eine Kundin einen Zahlungsversuch durchführt, die Zahlung jedoch fehlschlägt.                                                                                                                                                                                                                                          | Wenn eine Zahlung von `processing` zu `payment_failed` übergeht, bieten Sie der Kundin/dem Kunden einen weiteren Zahlungsversuch an.                                                                                    |