# Zahlungsangaben aktualisieren Erfahren Sie, wie die für zukünftige Rechnungen verwendete Zahlungsmethode aktualisiert werden kann. Führen Sie die folgenden Schritte aus, um eine Checkout-Seite zu erstellen, die die Zahlungsdetails Ihrer Kund/innen erfasst und eine Zahlungsmethode zurückgibt. Verwenden Sie dann die REST-APIs von Stripe, um die für zukünftige *Rechnungen* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) verwendete Zahlungsmethode zu aktualisieren. > In diesem Leitfaden wird Checkout verwendet, um die Zahlungsmethoden für Abonnements zu aktualisieren. Sie können stattdessen das [Billing-Kundenportal](https://docs.stripe.com/customer-management.md) implementieren, um Ihren Kundinnen/Kunden ein von Stripe gehostetes Dashboard zur Verfügung zu stellen, um ihre Abonnements und Rechnungsdetails zu verwalten. ## Stripe einrichten [Serverseitig] Zunächst benötigen Sie ein Stripe-Konto. [Registrieren Sie sich jetzt](https://dashboard.stripe.com/register). Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API über Ihre Anwendung: #### 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' ``` ## Checkout-Sitzung erstellen [Serverseitig] Um eine Sitzung im Einrichtungsmodus zu erstellen, verwenden Sie beim Erstellen der Sitzung den Parameter `mode` mit dem Wert `setup`. Eine vollständige Liste der Parameter, die Sie für die Erstellung einer Sitzung verwenden können, finden Sie in der [Dokumentation zur Checkout Session API](https://docs.stripe.com/api/checkout/sessions/create.md). Hängen Sie die Vorlagenvariable `{CHECKOUT_SESSION_ID}` an die `success_url` an, um Zugriff auf die Sitzungs-ID zu erhalten, sobald Ihre Kundin/Ihr Kunde eine Checkout-Sitzung erfolgreich abgeschlossen hat. Verwenden Sie abschließend das Wörterbuch [setup_intent_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-setup_intent_data-metadata), um die bestehende Stripe-`subscription_id` Ihrer Kundin/Ihres Kunden an die Checkout-Sitzung zu übergeben. Beachten Sie, dass es auch andere Möglichkeiten gibt, diese Daten an Ihren Server zu übergeben. Für diesen Leitfaden verwenden wir jedoch Metadaten. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="card" \ -d "mode"="setup" \ -d "customer"="cus_FOsk5sbh3ZQpAU" \ -d "setup_intent_data[metadata][subscription_id]"="sub_8epEF0PuRhmltU" \ -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` ## Zu Checkout weiterleiten [Clientseitig] Checkout basiert auf [Stripe.js](https://docs.stripe.com/payments/elements.md), der grundlegenden JavaScript-Bibliothek von Stripe für die Erstellung von Zahlungsabläufen. #### HTML + JS Fügen Sie Ihrer Website zunächst das nachfolgende Skript-Tag hinzu. Laden Sie es immer direkt von **https://js.stripe.com** herunter. Sie können das Skript nicht in ein Paket einfügen oder selbst hosten. Beispiele finden Sie unter [Stripe Samples](https://github.com/stripe-samples). ```javascript npm install @stripe/stripe-js ``` Erstellen Sie als Nächstes eine Instanz des [Stripe-Objekts](https://docs.stripe.com/js.md#stripe-function) und geben Sie dabei Ihren veröffentlichbaren [API-Schlüssel](https://docs.stripe.com/keys.md) als ersten Parameter an: ```javascript import {loadStripe} from '@stripe/stripe-js'; const stripe = await loadStripe('<>'); ``` Um Checkout auf Ihrer Website verwenden zu können, müssen Sie ein Code-Snippet mit der `id` der Sitzung aus dem [vorherigen Schritt](https://docs.stripe.com/payments/checkout/subscriptions/update-payment-details.md#create-checkout-session) hinzufügen. Wenn Ihr Kunde/Ihre Kundin bereit ist, seine/ihre Zahlungsmethode zu speichern oder zu aktualisieren, rufen Sie [redirectToCheckout](https://docs.stripe.com/js.md#stripe-redirect-to-checkout) auf und geben Sie die `id` der Sitzung als Parameter an. ```javascript const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. }); ``` #### React Installieren Sie zunächst das Stripe.js-Modul. Laden Sie Stripe.js immer direkt von **https://js.stripe.com** herunter. Sie können die Bibliothek nicht in ein Paket einfügen oder selbst hosten. ```npm npm install @stripe/stripe-js ``` ### Stripe.js zu Ihrer Seite hinzufügen Rufen Sie `loadStripe` mit Ihrem veröffentlichbaren Schlüssel auf. Es wird ein `Promise` zurückgegeben, das nach dem Laden von Stripe.js mit dem `Stripe`-Objekt aufgelöst wird. Wenn Ihr Kunde/Ihre Kundin bereit ist, seine/ihre Zahlungsmethode zu speichern, rufen Sie [redirectToCheckout](https://docs.stripe.com/js.md#stripe-redirect-to-checkout) auf und geben Sie die `id` der Sitzung als Parameter an. ```jsx import React from 'react'; import ReactDOM from 'react-dom'; import { loadStripe } from '@stripe/stripe-js'; // Make sure to call `loadStripe` outside of a component’s render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe('<>'); function App() { const handleClick = async (event) => { // Call your backend to create the Checkout session. const { sessionId } = await fetchCheckoutSession(); // When the customer clicks on the button, redirect them to Checkout. const stripe = await stripePromise; const { error } = await stripe.redirectToCheckout({ sessionId }); // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. }; return ( ); } ReactDOM.render(, document.getElementById('root')); ``` Dieser Code wird in der Regel von einem Ereignis-Handler aufgerufen, der als Reaktion auf eine Aktion Ihrer Kundin/Ihres Kunden ausgelöst wird (z. B. durch Klicken auf eine Zahlungsschaltfläche). ## Checkout-Sitzung abrufen [Serverseitig] Nachdem eine Kundin/ein Kunde die Checkout-Sitzung erfolgreich durchlaufen hat, müssen Sie das Session-Objekt abrufen. Es gibt dafür zwei Möglichkeiten: - **Asynchron**: Verarbeiten Sie `checkout.session.completed`*Webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests), die ein Session-Objekt enthalten. Hier erfahren Sie mehr über das [Einrichten von Webhooks](https://docs.stripe.com/webhooks.md) - **Synchron**: Rufen Sie die Sitzungs-ID von der `success_url`, wenn ein/e Nutzer/in auf Ihre Seite zurückgeleitet wird. Verwenden Sie die Sitzungs-ID, um das Sitzungsobjekt [abzurufen](https://docs.stripe.com/api/checkout/sessions/retrieve.md). ```curl curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \ -u "<>:" ``` Die Wahl hängt von Ihrer Toleranz gegenüber Kaufabbrüchen ab, da Kundinnen/Kunden in manchen Fällen nach erfolgreicher Zahlung nicht zur `success_url` weitergeleitet werden. Das passiert zum Beispiel, wenn sie die Registerkarte im Browser schließen, bevor die Weiterleitung erfolgt ist. Die Verarbeitung von Webhooks verhindert diese Form von Kaufabbrüchen in Ihrer Integration. Nachdem Sie das Session-Objekt abgerufen haben, erfassen Sie den Wert des Schlüssels `setup_intent`. Dabei handelt es sich um die ID des während der Checkout-Sitzung erstellten SetupIntent. Ein [SetupIntent](https://docs.stripe.com/payments/setup-intents.md) ist ein Objekt, mit dem die Bankkontoinformationen von Kundinnen und Kunden für zukünftige Zahlungen eingerichtet werden. Beispiel-Nutzlast von `checkout.session.completed`: ```json { "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0", "object": "event", "api_version": "2019-03-14", "created": 1561420781, "data": { "object": { "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k", "object": "checkout.session", "billing_address_collection": null, "client_reference_id": null, "customer": "cus_FOsk5sbh3ZQpAU", "customer_email": null, "display_items": [], "mode": "setup","setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM", "submit_type": null, "subscription": null, "success_url": "https://example.com/success" } }, "livemode": false, "pending_webhooks": 1, "request": { "id": null, "idempotency_key": null }, "type": "checkout.session.completed" } ``` Beachten Sie die `setup_intent`-ID für den nächsten Schritt. ## SetupIntent abrufen [Serverseitig] Verwenden Sie die `setup_intent`-ID, um das SetupIntent-Objekt mit dem Endpoint [/v1/setup_intents/:id](https://docs.stripe.com/api/setup_intents/retrieve.md) abzurufen. ```curl curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \ -u "<>:" ``` Beispielantwort: ```json { "id": "seti_1EzVO3HssDVaQm2PJjXHmLlM", "object": "setup_intent", "application": null, "cancellation_reason": null, "client_secret": null, "created": 1561420781,"customer": "cus_FOsk5sbh3ZQpAU", "description": null, "last_setup_error": null, "livemode": false, "metadata": {"subscription_id": "sub_8epEF0PuRhmltU" }, "next_action": null, "on_behalf_of": null,"payment_method": "pm_1F0c9v2eZvKYlo2CJDeTrB4n", "payment_method_types": [ "card" ], "status": "succeeded", "usage": "off_session" } ``` Notieren Sie sich die `customer`-ID, die `subscription_id` und die `payment_method`-ID für die nächsten Schritte. > Wenn Sie diese Informationen synchron über die Stripe-API anfordern (anstatt Webhooks zu verarbeiten), können Sie den vorherigen Schritt mit diesem Schritt kombinieren, indem Sie das SetupIntent-Objekt in der Anfrage an den Endpoint /v1/checkout/session [erweitern](https://docs.stripe.com/api/expanding_objects.md). So müssen Sie nicht zwei Netzwerkanforderungen stellen, um auf die neu erstellte PaymentMethod-ID zugreifen zu können. ## Standard-Zahlungsmethode festlegen [Serverseitig] Es gibt zwei Möglichkeiten, um sicherzustellen, dass eine Zahlungsmethode für zukünftige Rechnungen verwendet wird: - Richten Sie sie als `invoice_settings.default_payment_method` der Kundin/des Kunden ein. - Richten Sie sie als `default_payment_method` des Abonnements ein. Die Festlegung der `invoice_settings.default_payment_method` für die Kundin/den Kunden bewirkt, dass alle zukünftigen Rechnungen für diese Kundin/diesen Kunden mit der angegebenen Zahlungsmethode bezahlt werden. Die Festlegung der `default_payment_method` für das Abonnement bewirkt, dass alle zukünftigen Rechnungen für dieses Abonnement mit der angegebenen Zahlungsmethode bezahlt werden, wobei jede für die zugehörige Kundin bzw. den zugehörigen Kunden festgelegte `invoice_settings.default_payment_method` außer Kraft gesetzt wird. ### invoice_settings.default_payment_method für den Kunden/die Kundin festlegen Verwenden Sie die abgerufene Kunden-ID und die abgerufene PaymentMethod-ID und legen Sie die `invoice_settings.default_payment_method` für die Kundin/den Kunden mit dem Endpoint [/v1/customers/:id](https://docs.stripe.com/api/customers/update.md) fest. ```curl curl https://api.stripe.com/v1/customers/cus_FOsk5sbh3ZQpAU \ -u "<>:" \ -d "invoice_settings[default_payment_method]=pm_1F0c9v2eZvKYlo2CJDeTrB4n" ``` Alle zukünftigen Rechnungen für diese Kundin/diesen Kunden werden nun mit der neuen PaymentMethod abgerechnet, die mit dem Einrichtungsmodus Checkout-Sitzung erstellt wurde. ### default_payment_method für das Abonnement festlegen Verwenden Sie die abgerufene Abonnement-ID und die abgerufene PaymentMethod-ID und legen Sie die `default_payment_method` für das Abonnement mit dem Endpoint [/v1/subscriptions/:id](https://docs.stripe.com/api/subscriptions/update.md) fest. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_8epEF0PuRhmltU \ -u <>: \ -X "POST" \ -d "default_payment_method"="pm_1F0c9v2eZvKYlo2CJDeTrB4n" ``` Alle zukünftigen Rechnungen für dieses Abonnement werden nun mit der neuen PaymentMethod abgerechnet, die mit dem Einrichtungsmodus Checkout-Sitzung erstellt wurde. Dabei wird jede für die zugehörige Kundin bzw. den zugehörigen Kunden festgelegte `invoice_settings.default_payment_method` außer Kraft gesetzt. ## See also Herzlichen Glückwunsch! Sie können jetzt eine Standard-Zahlungsmethode für zukünftige Rechnungen festlegen. Beim Testen Ihrer Integration mit Ihrem Test-API-Schlüssel können Sie eine [Testkartennummer](https://docs.stripe.com/testing.md#cards) verwenden, um die ordnungsgemäße Funktion zu überprüfen. - [Testkarten](https://docs.stripe.com/testing.md#cards)