# 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. Sie können Ihr eingebettetes Checkout-Formular auch über [Checkout Studio](https://docs.stripe.com/payments/checkout-studio.md) erstellen und in der Vorschau anzeigen. Dieses bietet eine zentrale Dashboard-Seite zum Konfigurieren und Überwachen Ihrer Checkout-Integrationen. ## 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 "<>:" \ -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}} \ -d integration_identifier=embedded_web_0001 ``` 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. Die Checkout Sessions API unterstützt einen optionalen Parameter `integration_identifier`, den Sie beim Erstellen einer Sitzung festlegen können. Verwenden Sie diesen, um diese Formularintegration mit einem erkennbaren Namen zu kennzeichnen und ihre Konversion unabhängig von anderen von Ihnen genutzten Checkout-Integrationen zu messen. 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 - [automatic_tax[address_collection_precision]](https://docs.stripe.com/payments/checkout/taxes.md?payment-ui=checkout-form): Steuern Sie die Erfassung der Rechnungsadresse in eingebetteten Formularen für die Steuerberechnung, wenn die automatische Steuerberechnung aktiviert ist. - [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 - [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-allow_promotion_codes): Von Kundinnen und Kunden einlösbare Aktionscodes zulassen > #### Nicht unterstützte CheckoutSession-Parameter > > Das eingebettete Formular unterstützt `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`, 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('<>'); const App = () => { const clientSecret = useMemo(() => ( fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret) ), []); return ( ); }; 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 Checkout ``` Erstellen Sie auf Ihrer Bezahlseite eine Instanz von Stripe: ```javascript const stripe = Stripe('<>'); ``` 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
``` 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 ``` #### 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('<>'); const CheckoutPage = () => { const checkoutState = useCheckoutForm(); if (checkoutState.type === 'error') { return
Error: {checkoutState.error.message}
; } const onConfirm = (event) => { if (checkoutState.type === 'success') { checkoutState.checkout.confirm({formConfirmEvent: event}); } }; return ; }; const App = () => { const clientSecret = useMemo(() => ( fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret) ), []); return ( ); }; 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 const loadActionsResult = await checkout.loadActions(); if (loadActionsResult.type === 'success') { form.on('confirm', async (event) => { try { await loadActionsResult.actions.confirm({formConfirmEvent: event}); } catch (error) { console.error('Payment confirmation error:', error); } }); } ``` > #### Weiterleitungsverhalten anpassen > > Standardmäßig leitet das eingebettete Formular Ihren Endkunden/Ihre Endkundin nach einer erfolgreichen Zahlung an die `return_url` weiter, die Sie beim Erstellen der Checkout-Sitzung angeben. Um Weiterleitungen für Zahlungsmethoden zu verhindern, die keine Weiterleitung erfordern, wie etwa Karten, setzen Sie [weiterleiten](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) beim Aufruf von [bestätigen](https://docs.stripe.com/js/custom_checkout/confirm) auf `'if_required'`. Weitere Informationen finden Sie unter [Weiterleitungsverhalten anpassen](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. Fügen Sie Ihrem Browser eine Zahlungsmethode hinzu. Sie können beispielsweise eine Karte zu Ihrem Google Pay-Konto oder zu Ihrer Apple Wallet 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. ### Layout Verwenden Sie die Option [layout](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-layout), um zu steuern, wie das eingebettete Formular die Schritte für den Bezahlvorgang darstellt. - **Erweitert**: Verwenden Sie dieses Layout für einen einstufigen Bezahlvorgang. Es ist ideal für herkömmliche Formulare für den Bezahlvorgang, die sich direkt auf der Webseite befinden. - **Kompakt** (Private preview): Verwenden Sie dieses Layout für einen mehrstufigen Bezahlvorgang. Es ist ideal für kompaktere Layouts für Nutzeroberflächen wie Modale, Pop-ups und Chat-Nutzeroberflächen. Wenn Sie `layout` undefiniert lassen, rendert Stripe das Layout, das die beste Konversion aufweist. ### Zugang zum kompakten Layout anfordern Das kompakte Layout zeigt das eingebettete Formular als mehrstufigen Bezahlvorgang an. Es ist auf Anfrage als private Vorschau verfügbar. Geben Sie unten Ihre E-Mail-Adresse ein, um Zugriff anzufordern. ```bash curl https://docs.stripe.com/preview/register \ -X POST \ -H "Content-Type: application/json" \ -H "Referer: https://docs.stripe.com/checkout/form/quickstart" \ -d '{"email": "EMAIL", "preview": "elements_betas_preview"}' ``` #### React ```jsx const checkoutFormOptions = { layout: 'expanded', }; ``` #### HTML + JS ```javascript const form = checkout.createForm({ layout: 'expanded', }); form.mount('#checkout-form'); ``` ### Optionen für eingebettete Formulare Sie können das Erscheinungsbild jedes Buttons für Express-Zahlungsmethoden konfigurieren und gespeicherte Kontakte mithilfe von Optionen übergeben. #### React ```jsx const checkoutFormOptions = { expressCheckout: { buttonTheme: { applePay: 'white-outline' }, paymentMethods: { applePay: 'always' } } }; ``` #### HTML + JS ```javascript const form = checkout.createForm({ expressCheckout: { buttonTheme: { applePay: 'white-outline' }, paymentMethods: { applePay: 'always' } } }); form.mount('#checkout-form'); ``` Das eingebettete Formular unterstützt die folgenden Optionen: | | | `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' } }; ``` #### 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-component