# Integration mit einem eingebetteten Formular erstellen

Die folgende Anleitung beschreibt, wie Sie das eingebettete Formular mit *Checkout-Sitzungen* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription) verwenden.

## Stripe einrichten [Serverseitig]

[Erstellen Sie zunächst ein Stripe-Konto](https://dashboard.stripe.com/register) oder [melden Sie sich an](https://dashboard.stripe.com/login).

Coding Agents sollten die Stripe-CLI installieren (`npm i -g @stripe/cli`) und den Befehl `stripe sandbox create --help` ausführen, um eine anonyme Stripe-Sandbox mit funktionierenden API-Schlüsseln einzurichten. Eine Kontoregistrierung ist nicht erforderlich.

Verwenden Sie unsere offiziellen Bibliotheken, um von Ihrer Anwendung aus auf die Stripe API zuzugreifen:

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

## Zahlungsmethoden aktivieren

Standardmäßig verwendet Stripe Ihre [Einstellungen für Zahlungsmethoden](https://dashboard.stripe.com/settings/payment_methods), um zu bestimmen, welche Zahlungsmethoden das eingebettete Formular anzeigt. Sie können auch spezifische Zahlungsmethoden für Ihre Checkout-Sitzung über das Attribut [payment_method_types](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_types) konfigurieren.

## Checkout-Sitzung erstellen [Serverseitig]

Erstellen Sie eine Checkout-Sitzung auf Ihrem Server, um den Zahlungsablauf zu steuern. Die Checkout-Sitzung definiert Ihre Posten, Versandoptionen und andere Einstellungen für die Zahlung.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=form \
  -d return_url={{RETURN_URL}}
```

Setzen Sie `ui_mode` auf `Form`, um das eingebettete Formular zu integrieren. Das zurückgegebene `CheckoutSession`-Objekt enthält ein Client-Geheimnis, das der Client verwendet, um die Checkout-Oberfläche sicher anzuzeigen.

Sie können auch die folgenden Optionen in der [CheckoutSession](https://docs.stripe.com/api/checkout/sessions/create.md) konfigurieren:

- [automatic_tax](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_tax): Automatische Steuerberechnung ermöglichen
- [billing_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection): Rechnungsadressen erfassen
- [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email): E-Mail-Adresse des Kunden/Kundin vorab ausfüllen
- [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer): Kundendaten aus einem bestehenden `Customer`-Objekt vorab ausfüllen
- [name_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-name_collection): Erfassen Sie für Ihre Kundin oder Ihren Kunden den Unternehmensnamen, den persönlichen Namen oder beides
- [shipping_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection): Versandadressen erfassen
- [shipping_options](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options): Versandtarifoptionen angeben
- [submit_type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type): Geben Sie die Art der durchgeführten Transaktion an
- [phone_number_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-phone_number_collection): Erfassen Sie die Telefonnummer Ihrer Kundin/Ihres Kunden
- [tax_id_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-tax_id_collection): Steuer-IDs einziehen

> #### Nicht unterstützte CheckoutSession-Parameter
> 
> Das eingebettete Formular unterstützt `allow_promotion_codes` oder `consent_collection` nicht.

## Stripe Elements einrichten [Clientseitig]

#### React

Das eingebettete Formular ist als Funktion von Stripe.js verfügbar. Installieren Sie [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) und den [Stripe.js-Loader](https://www.npmjs.com/package/@stripe/stripe-js) aus der öffentlichen npm-Registry.

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

Erstellen Sie `clientSecret` als `Promise<string> | string`, das den von Ihrem Server zurückgegebenen geheimen Client-Schlüssel enthält. Umschließen Sie Ihre Anwendung mit der [CheckoutFormProvider](https://docs.stripe.com/js/react_stripe_js/checkout_form/checkout_form_provider)-Komponente und übergeben Sie dabei das `clientSecret` und die `Stripe`-Instanz.

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe(
  '<<YOUR_PUBLISHABLE_KEY>>',
  {betas: ['custom_checkout_payment_form_1']}
);

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutFormProvider>
  );
};

export default App;
```

#### HTML + JS

Das eingebettete Formular ist automatisch als Funktion von Stripe.js verfügbar. Fügen Sie das Stripe.js-Skript in Ihre Zahlungsseite ein, indem Sie es am Anfang Ihrer HTML-Datei hinzufügen. Laden Sie Stripe.js immer direkt von js.stripe.com, um PCI-konform zu bleiben. Fügen Sie das Script nicht in ein Paket ein und hosten Sie keine eigene Kopie davon.

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

Erstellen Sie auf Ihrer Bezahlseite eine Instanz von Stripe:

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>', {
  betas: ['custom_checkout_payment_form_1']
});
```

Rufen Sie das Client-Geheimnis von Ihrem Server ab und initialisieren Sie das SDK für das Checkout-Formular:

```javascript
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.client_secret);
```

SDK-Instanz für das Checkout-Formular erstellen:

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret
});
```

## Erstellen und einbinden [Clientseitig]

Das eingebettete Formular enthält einen iframe, der die Zahlungsinformationen über eine HTTPS-Verbindung sicher an Stripe überträgt.

#### React

Die `CheckoutForm`-Komponente wird bereits im vorherigen Schritt in `CheckoutFormProvider` gerendert. Für React ist keine zusätzliche Einbindung erforderlich.

#### HTML + JS

Das eingebettete Formular benötigt einen festgelegten Platz auf Ihrer Zahlungsseite. Erstellen Sie einen leeren DOM-Knoten (Container) mit einer eindeutigen ID in Ihrem Zahlungsformular.

```html
<div id="checkout-form">
  <!-- embedded form will be inserted here -->
</div>
```

Wenn die Checkout-Formular-SDK-Instanz bereit ist, erstellen Sie das eingebettete Formular und hängen Sie es an den Container-DOM-Knoten an:

```javascript
const form = checkout.createForm();
form.mount('#checkout-form');
```

Sie können das [Layout](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-layout) festlegen, um das eingebettete Formular als einstufiges oder mehrstufiges eingebettetes Formular zu rendern.

## Kunden-E-Mail-Adresse vorab ausfüllen

Sie können die E-Mail-Adresse des Kunden/der Kundin mit einer von zwei Methoden vorab ausfüllen, je nachdem, ob es möglich sein soll, die E-Mail-Adresse zu ändern.

### E-Mail-Adresse in der Checkout-Sitzung festlegen (nicht bearbeitbar)

Übergeben Sie [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email), wenn Sie die Checkout-Sitzung auf Ihrem Server erstellen. Die E-Mail-Adresse wird im eingebetteten Formular angezeigt, aber die Kundin/der Kunde kann sie nicht ändern. Sie können auch eine [Kunden](https://docs.stripe.com/api/customers.md)-ID an das [Kundenfeld](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) übergeben, um die beim Kunden/bei der Kundin gespeicherte E-Mail-Adresse vorauszufüllen.

### Standard-E-Mail-Adresse auf dem Client festlegen (bearbeitbar)

Übergeben Sie bei der Initialisierung des SDK den Parameter `defaultValues.email`, um ein bearbeitbares E-Mail-Feld vorab auszufüllen. Der Kunde kann diesen Wert im eingebetteten Formular ändern.

#### React

```jsx
<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret,
    defaultValues: {
      email: 'customer@example.com',
    },
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret,
  defaultValues: {
    email: 'customer@example.com',
  },
});
```

## Zahlung abschließen [Clientseitig]

Die Checkout Session, die Sie auf dem Server erstellt haben, legt automatisch die Posten, den Gesamtbetrag und die verfügbaren Zahlungsmethoden fest. Das eingebettete Formular verwendet diese Informationen, um die entsprechende Benutzeroberfläche anzuzeigen.

#### React

### Zahlungsbestätigung verarbeiten

Verarbeiten Sie das Bestätigungsereignis, wenn Ihre Kundinnen und Kunden die Zahlung abschließen:

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm, useCheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe(
  '<<YOUR_PUBLISHABLE_KEY>>',
  {betas: ['custom_checkout_payment_form_1']}
);

const CheckoutPage = () => {
  const checkoutState = useCheckoutForm();

  if (checkoutState.type === 'error') {
    return <div>Error: {checkoutState.error.message}</div>;
  }

  const onConfirm = (event) => {
    if (checkoutState.type === 'success') {
       checkoutState.checkout.confirm({formConfirmEvent: event});
    }
  };

  return <CheckoutForm onConfirm={onConfirm} />;
};

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutPage />
    </CheckoutFormProvider>
  );
};

export default App;
```

### Umgang mit Fehlern

Das eingebettete Formular zeigt den Kundinnen und Kunden während der Client-Bestätigung automatisch lokalisierte Fehlermeldungen an. Wenn ein Problem die Fortsetzung der Bestätigungsmethode verhindert, kann die Bestätigungsmethode eine Ausnahme auslösen. Erfassen Sie diese Ausnahmen und behandeln Sie sie entsprechend.

```jsx
const onConfirm = async (event) => {
  if (checkoutState.type === 'success') {
    try {
      await checkoutState.checkout.confirm({formConfirmEvent: event});
    } catch (error) {
      console.error('Payment confirmation error:', error);
    }
  }
};
```

#### HTML + JS

### Zahlungsbestätigung verarbeiten

Überwachen Sie das Bestätigungsereignis, wenn Ihre Kundinnen und Kunden die Zahlung abschließen:

```javascript
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  form.on('confirm', (event) => {
    loadActionsResult.actions.confirm({formConfirmEvent: event});
  });
}
```

Das eingebettete Formular zeigt den Kundinnen und Kunden während der Client-Bestätigung automatisch lokalisierte Fehlermeldungen an. Sollte ein unmittelbares Problem die Fortsetzung der Bestätigungsmethode verhindern, kann die Bestätigungsmethode eine Ausnahme auslösen. Erfassen Sie diese Ausnahmen und behandeln Sie sie entsprechend.

```javascript
form.on('confirm', async (event) => {
  try {
    await checkout.confirm({formConfirmEvent: event});
  } catch (error) {
    console.error('Payment confirmation error:', error);
  }
});
```

> #### Weiterleitungsverhalten anpassen
> 
> By default, after a successful payment, the embedded form redirects your customer to the `return_url` that you specify when you create the Checkout Session. To prevent redirects for payment methods that don’t require a redirect, such as cards, set [redirect](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) to `'if_required'` when calling [confirm](https://docs.stripe.com/js/custom_checkout/confirm). To learn more, see [Customize redirect behavior](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=checkout-form).

## Ereignisse nach der Zahlung verarbeiten [Serverseitig]

Die Checkout-Sitzung definiert Ihre Posten, Versandoptionen und weitere Einstellungen für die Zahlung. Nachdem eine Kundin oder ein Kunde die Zahlung auf dem Client bestätigt hat, verarbeiten Sie das Ergebnis auf Ihrem Server, anstatt sich auf den clientseitigen Status zu verlassen.

- **Webhooks** (Empfohlen): Achten Sie auf das Ereignis [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed), das Stripe sendet, sobald die Zahlung erfolgreich abgeschlossen wurde. Dieser Ansatz stellt sicher, dass Sie benachrichtigt werden, selbst wenn der Kunde oder die Kundin seinen bzw. ihren Browser vor der Weiterleitung schließt.
- **Rückkehrseite**: [Rufen Sie die Checkout-Sitzung](https://docs.stripe.com/api/checkout/sessions/retrieve.md) anhand ihrer ID ab, um den Zahlungsstatus zu überprüfen, und zeigen Sie Ihrem Kunden oder Ihrer Kundin das entsprechende Ergebnis auf der Seite an, die Sie als `return_url` festgelegt haben.

Erfahren Sie, wie Sie [Bestellungen nach Zahlungseingang ausführen](https://docs.stripe.com/checkout/fulfillment.md?payment-ui=checkout-form).

## Integration testen

Bevor Sie live gehen, [testen](https://docs.stripe.com/testing.md) Sie jede Zahlungsmethodenintegration. Klicken Sie auf **Bezahlen**, um die Zahlung abzuschließen. Sie werden dann zur angegebenen Rückgabeseite weitergeleitet.

Wenn die Rückgabeseite angezeigt wird und die Zahlung in der Liste der erfolgreichen Zahlungen im Dashboard erscheint, funktioniert Ihre Integration.

#### Karten

Verwenden Sie die [Testkartennummern](https://docs.stripe.com/testing.md#cards) von Stripe, um Kartenzahlungen zu testen. Zum Beispiel:

| Scenario                            | Card Number      |
| ----------------------------------- | ---------------- |
| Payment succeeds                    | 4242424242424242 |
| Payment requires 3DS authentication | 4000002500003155 |
| Payment is declined                 | 4000000000009995 |

#### Schaltflächen für die Zahlung mit einem Klick

Befolgen Sie diese Schritte, um die Ein-Klick-Zahlungsschaltflächen zu testen:

1. Ihrem Browser eine Zahlungsmethode hinzufügen. Beispiel: Sie können Ihrem Google Pay-Konto bzw. Ihrer Wallet für Safari eine Karte hinzufügen.
2. Stellen Sie Ihre Anwendung über HTTPS bereit. Dies ist sowohl in der Entwicklung als auch in der Produktion erforderlich. Sie können einen Dienst wie [ngrok](https://ngrok.com/) verwenden.
3. [Registrieren Sie Ihre Domain](https://dashboard.stripe.com/settings/payment_method_domains) sowohl in einer *Sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) als auch im Live-Modus.
4. Befolgen Sie bitte die Anweisungen im [Testleitfaden für das Express-Checkout-Element](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=embedded-components#test-integration).

## Passen Sie das Layout und das Erscheinungsbild an

Sie können das eingebettete Formular anpassen, indem Sie dessen Optionen festlegen oder die Appearance API verwenden.

### Optionen für eingebettete Formulare

Sie können das allgemeine Layout des eingebetteten Formulars konfigurieren und das Erscheinungsbild der Schaltflächen für jede Express-Zahlungsmethode mithilfe von Optionen anpassen.

#### React

```jsx
const checkoutFormOptions = {
  layout: 'expanded',

  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
};

<CheckoutForm
  options={checkoutFormOptions}
  onConfirm={onConfirm}
/>
```

#### HTML + JS

```javascript
const form = checkout.createForm({
  layout: 'expanded',

  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
});

form.mount('#checkout-form');
```

Das eingebettete Formular unterstützt die folgenden Optionen:

|  |
|  |
| `layout`                         | Layout für das eingebettete Formular. Zu den Optionen gehören `erweitert` und `kompakt`. Wenn Sie dies nicht definieren, rendert Stripe das Layout, das am ehesten die beste Konversionsrate erzielt.                                                              |
| `expressCheckout.buttonTheme`    | Legen Sie ein Design für die Ein-Klick-Zahlungsschaltfläche fest. Siehe [buttonTheme](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-buttonTheme).                                                     |
| `expressCheckout.paymentMethods` | Geben Sie an, welche Schaltflächen für Zahlungen mit einem Klick angezeigt werden. Siehe [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-paymentMethods).                              |
| `Kontakte`                       | Ein Array von Objekten, die gespeicherte Adressen repräsentieren, von denen jedes die Eigenschaften `name`, `address`, und `phone` enthält. Siehe [Kontakte](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-contacts). |

### Appearance API

Sie können die [Appearance API](https://docs.stripe.com/elements/appearance-api.md) verwenden, um den Stil des eingebetteten Formulars zu steuern, indem Sie ein Design anwenden oder bestimmte Details aktualisieren. Das eingebettete Formular unterstützt jedoch die Option `Regeln` nicht.

Wähle Sie zum Beispiel das „flache“ Design und überschreiben Sie die Standardtextfarbe.

#### React

```jsx
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret, // In einer funktionierenden Integration übergibt Ihr Backend diesen Hash mit Details wie dem Zahlungsbetrag. Weitere Informationen finden Sie im vollständigen Beispiel.
    appearance
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

const checkout = stripe.initCheckoutFormSdk({
  clientSecret, // In einer funktionierenden Integration übergibt Ihr Backend diesen Hash mit Details wie dem Zahlungsbetrag. Weitere Informationen finden Sie im vollständigen Beispiel.
  appearance
});
```

## Stripe Ihren Kundinnen/Kunden anzeigen

Stripe erfasst Informationen über Kundeninteraktionen mit Elements , um Ihnen Dienste bereitzustellen, Betrug vorzubeugen und seine Dienste zu verbessern. Dies umfasst auch die Verwendung von Cookies und IP-Adressen, um zu ermitteln, welche Elements ein/e Kund/in während einer einzelnen Checkout-Sitzung gesehen hat. Sie sind dafür verantwortlich, alle Rechte und Zustimmungen offenzulegen und einzuholen, die Stripe benötigen, um Ihre Daten auf diese Weise zu nutzen. Weitere Informationen finden Sie in unserem [Datenschutzcenter](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe).

## See also

- [Zahlungsmethode einer Kundin/eines Kunden speichern, wenn sie/er diese für eine Zahlung verwendet](https://docs.stripe.com/payments/save-during-payment.md?payment-ui=embedded-components)