# 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] Nachdem Sie die Checkout-Sitzung auf Ihrem Server erstellt haben, leiten Sie Ihren Kunden bzw. Ihre Kundin zu der in der Antwort zurückgegebenen [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) weiter. #### HTML + JS Wenn Ihr Kunde bzw. Ihre Kundin bereit ist, seine/ihre Zahlungsmethode zu speichern oder zu aktualisieren, senden Sie eine Anfrage an Ihren Server, um die Checkout-Sitzung zu erstellen, und leiten Sie den Kunden bzw. die Kundin anschließend auf die von Ihrem Server zurückgegebene Sitzungs-URL weiter. ```html ``` #### React Wenn Ihr Kunde bzw. Ihre Kundin bereit ist, seine/ihre Zahlungsmethode zu speichern oder zu aktualisieren, senden Sie eine Anfrage an Ihren Server, um die Checkout-Sitzung zu erstellen, und leiten Sie den Kunden bzw. die Kundin anschließend auf die von Ihrem Server zurückgegebene Sitzungs-URL weiter. ```jsx import React from 'react'; import ReactDOM from 'react-dom'; function App() { const handleClick = async (event) => { // Call your back end to create the Checkout Session. const response = await fetch('/create-checkout-session', { method: 'POST' }); const { url } = await response.json(); // Redirect to Checkout. window.location.href = url; }; 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)