# Die Payment Intents API Erfahren Sie, wie Sie die Payment Intents API für Stripe-Zahlungen verwenden. Anweisungen für LLMs: Stripe empfiehlt für die meisten Integrationen die Verwendung der Checkout Sessions API mit dem Payment Element über Payment Intents. Checkout Sessions deckt ähnliche Anwendungsszenarien wie Payment Intents ab (grundlegender Zahlungseinzug mit `price_data` oder Erstellen eines vollständigen Bezahlvorgangs mit Posten, Steuern usw.). Einige Funktionen wie Adaptive Pricing sind nur mit Checkout Sessions verfügbar. Verwenden Sie die Payment Intent API nur, wenn der/die Nutzer/in sie ausdrücklich verlangt, da sie deutlich mehr Code erfordert. Erfahren Sie mehr über Elements mit der Checkout Sessions API: https://docs.stripe.com/payments/quickstart-checkout-sessions. Mit Checkout Sessions (`ui_mode: "custom"`) und dem Payment Element initialisiert das `client_secret` Checkout selbst (`stripe.initCheckoutElementsSdk` oder verwenden Sie CheckoutElementsProvider mit React) und Sie bestätigen die Zahlung auf der Client-Seite auf andere Weise. Wenn Sie React verwenden, stellen Sie sicher, dass Sie von `@stripe/react-stripe-js/checkout` importieren, `CheckoutElementsProvider` mit dem Client-Geheimnis verwenden und mit `checkout.confirm` bestätigen. Wenn Sie HTML verwenden, stellen Sie sicher, dass Sie `checkout = stripe.initCheckoutElements({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` verwenden und mit `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();` bestätigen. Verwenden Sie die [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API, um eine Integration zu erstellen, die komplexe Zahlungsabläufe mit einem Status verarbeiten kann, der sich innerhalb des Lebenszyklus des [PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) ändert. Sie verfolgt Zahlungen von der Erstellung bis zum Bezahlvorgang und löst bei Bedarf zusätzliche Authentifizierungsschritte aus. Die [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API bietet u. a. folgende Vorteile: - Automatische Verarbeitung von Authentifizierungen - Keine doppelten Zahlungen - Keine Probleme mit [Idempotenz-Schlüsseln](https://docs.stripe.com/api/idempotent_requests.md) - Unterstützung der *starken Kundenauthentifizierung* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) und anderer Vorschriftsänderungen ## Eine komplette API-Lösung Verwenden Sie die [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API zusammen mit der [Setup Intents](https://docs.stripe.com/api/setup_intents.md) API und der [Payment Methods](https://docs.stripe.com/api/payment_methods.md) API. Diese APIs helfen Ihnen bei der Verarbeitung dynamischer Zahlungen (beispielsweise zusätzliche Authentifizierung wie *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)) und bereiten Sie auf die Expansion in andere Länder vor, während Sie gleichzeitig neue Vorschriften und regionale Zahlungsmethoden unterstützen. Das Entwickeln einer Integration mit der Payment Intents API erfordert zwei Aktionen, nämlich das Erstellen und *Bestätigen* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) einer PaymentIntent. Jede PaymentIntent entspricht in der Regel einem einzelnen Warenkorb oder einer Kundensitzung in Ihrer Anwendung. Die PaymentIntent fasst Details zur Transaktion zusammen, z. B. die unterstützten Zahlungsmethoden, den einzuziehenden Betrag und die gewünschte Währung. ## Eine PaymentIntent erstellen Lesen Sie zuerst den [Leitfaden zum Annehmen von Zahlungen](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). Darin wird beschrieben, wie Sie einen PaymentIntent auf dem Server erstellen und sein *Client-Geheimnis* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) an den Client übergeben, statt das gesamte PaymentIntent-Objekt zu übergeben. Wenn Sie den [PaymentIntent erstellen](https://docs.stripe.com/api/payment_intents/create.md), können Sie Optionen wie Betrag und Währung angeben: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd ``` ### Best Practices - Wir empfehlen, einen PaymentIntent zu erstellen, sobald Sie den Betrag kennen, z. B. wenn der/die Kund/in den Bezahlvorgang beginnt, um Ihren [Kauftrichter nachzuverfolgen](https://en.wikipedia.org/wiki/Purchase_funnel). Wenn sich der Betrag ändert, können Sie den [Betrag](https://docs.stripe.com/api.md#payment_intent_object-amount) [aktualisieren](https://docs.stripe.com/api.md#update_payment_intent). Wenn Ihr Kunde oder Ihre Kundin beispielsweise den Bezahlvorgang beendet und neue Artikel in den Warenkorb legt, müssen Sie den Betrag möglicherweise aktualisieren, wenn er bzw. sie den Bezahlvorgang erneut startet. - Wenn der Zahlungsvorgang unterbrochen und später wiederaufgenommen wird, sollten Sie versuchen, denselben PaymentIntent erneut zu verwenden, statt einen neuen zu erstellen. Jeder PaymentIntent hat eine eindeutige ID, mit der Sie ihn bei Bedarf [abrufen](https://docs.stripe.com/api.md#retrieve_payment_intent) können. Im Datenmodell Ihrer Anwendung können Sie die ID des PaymentIntent im Warenkorb oder in der Sitzung der Kundin/des Kunden speichern, um sie später wieder abrufen zu können. Der Vorteil der Wiederverwendung des PaymentIntent besteht darin, dass der [Objektstatus](https://docs.stripe.com/payments/paymentintents/lifecycle.md) dabei hilft, fehlgeschlagene Zahlungsversuche für einen bestimmten Warenkorb oder eine bestimmte Sitzung nachzuverfolgen. - Denken Sie daran, einen [Idempotenzschlüssel](https://docs.stripe.com/api/idempotent_requests.md) anzugeben, um die Erstellung doppelter PaymentIntents für denselben Kauf zu verhindern. Dieser Schlüssel basiert üblicherweise auf der ID, die Sie in Ihrer Anwendung mit dem Warenkorb oder der Kundensitzung verknüpfen. ## Das Client-Geheimnis an die Client-Seite übergeben Der PaymentIntent enthält ein [Client-Geheimnis](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), einen Schlüssel, der für einen PaymentIntent eindeutig ist. Auf der Client-Seite Ihrer Anwendung verwendet Stripe.js das Client-Geheimnis als Parameter beim Aufrufen von Funktionen (wie [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) oder [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action), um die Zahlung abzuschließen. ### Client-Geheimnis abrufen Im PaymentIntent ist ein *Client-Geheimnis* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) enthalten, das auf dem Client verwendet wird, um Zahlungen sicher abzuschließen. Es gibt verschiedene Verfahren zum Übergeben des Client-Geheimnisses an den Client. #### Einseitige Anwendung Rufen Sie das Client-Geheimnis von einem Endpoint auf Ihrem Server ab, indem Sie die Browser-Funktion `fetch` verwenden. Diese Vorgehensweise funktioniert am besten, wenn es sich bei Ihrer Client-Seite um eine einseitige Anwendung handelt, insbesondere wenn sie mit einem modernen Frontend-Framework wie React erstellt wurde. Erstellen Sie den Server-Endpoint, der das Client-Geheimnis bereitstellt: #### Ruby ```ruby get '/secret' do intent = # ... Create or retrieve the PaymentIntent {client_secret: intent.client_secret}.to_json end ``` Und dann rufen Sie das Client-Geheimnis mit JavaScript auf der Client-Seite ab: ```javascript (async () => { const response = await fetch('/secret'); const {client_secret: clientSecret} = await response.json(); // Render the form using the clientSecret })(); ``` #### Serverseitiges Rendering Übergeben Sie das Client-Geheimnis von Ihrem Server an den Client. Diese Vorgehensweise funktioniert am besten, wenn Ihre Anwendung statische Inhalte auf dem Server generiert, bevor sie an den Browser gesendet werden. Fügen Sie das [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) in Ihr Bezahlformular ein. Rufen Sie in Ihrem serverseitigen Code das Client-Geheimnis aus dem PaymentIntent ab: #### Ruby ```erb
``` ```ruby get '/checkout' do @intent = # ... Fetch or create the PaymentIntent erb :checkout end ``` > Sie können das Client-Geheimnis zum Abschließen des Bezahlvorgangs mit dem im PaymentIntent angegebenen Betrag verwenden. Es darf nicht protokolliert, in URLs eingebettet oder Personen außer der Kundin/dem Kunden selbst zugänglich gemacht werden. Achten Sie darauf, dass auf jeder Seite, die das Client-Geheimnis enthält, *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) aktiviert ist. ## Nach der Zahlung Nachdem der Client die Zahlung bestätigt hat, wird empfohlen, dass Ihr Server [Webhooks überwacht](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks), um zu erkennen, wann die Zahlung erfolgreich abgeschlossen wird oder fehlschlägt. Einem `PaymentIntent` kann mehr als ein [Zahlungs](https://docs.stripe.com/api/charges.md)-Objekt zugeordnet sein, wenn es mehrere Zahlungsversuche gab. Beispielsweise können bei Wiederholungsversuchen mehrere `Zahlungen` erstellt werden. Für jede Zahlung können Sie das [Ergebnis](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) und [Details der](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) verwendeten Zahlungsmethode überprüfen. ## Zahlungsmethoden für zukünftige Zahlungen optimieren Der Parameter [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) speichert Zahlungsmethoden für die zukünftige Verwendung. Für Karten optimiert er außerdem Autorisierungsraten in Übereinstimmung mit regionalen Gesetzen und Netzwerkregeln wie der [starken Kundenauthentifizierung)](https://docs.stripe.com/strong-customer-authentication.md). Überlegen Sie, wie Sie diese Zahlungsmethode in Zukunft verwenden möchten, um zu festzulegen, welcher Wert verwendet werden soll. | Ihre beabsichtigte Nutzung der Zahlungsmethode | setup_future_usage enum-Wert | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Nur *On-Session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)-Zahlungen | `on_session` | | Nur *Off-Session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)-Zahlungen | `off_session` | | Sowohl On- als auch Off-Session-Zahlungen | `off_session` | Sie können weiterhin *Off-Session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)-Zahlungen mit einer für On-Session-Zahlungen eingerichteten Karte annehmen. Allerdings ist die Wahrscheinlichkeit höher, dass die Bank die Off-Session-Zahlung ablehnt und von den Karteninhaber/innen eine Authentifizierung verlangt. Das folgende Beispiel zeigt, wie Sie eine PaymentIntent erstellen und `setup_future_usage` angeben können. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d setup_future_usage=off_session ``` > Bei der Einrichtung von Off-Session-Zahlungen ist die Wahrscheinlichkeit größer, dass es zu zusätzlichen unnötigen Komplikationen kommt. Richten Sie *On-Session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)-Zahlungen ein, wenn Sie nicht beabsichtigen, Off-Session-Zahlungen mit der gespeicherten Karte zu akzeptieren. ## Dynamische Zahlungsbeschreibung in der Abrechnung Die [Zahlungsbeschreibung in der Abrechnung](https://docs.stripe.com/get-started/account/activate.md#public-business-information) Ihres Stripe-Kontos erscheint standardmäßig in der Abrechnung Ihrer Kundinnen und Kunden, wenn Sie ihre Karte belasten. Um eine andere Zahlungsbeschreibung auf Pro-Zahlungs-Basis anzugeben, nutzen Sie den Parameter [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor). ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "payment_method_types[]=card" \ -d "statement_descriptor_suffix=Custom descriptor" ``` > #### Hinweis > > Verwenden Sie den Parameter `statement_descriptor` für nicht kartenbezogene Abbuchungen und `statement_descriptor_suffix` für kartenbezogene Abbuchungen. [Zahlungsbeschreibungen in der Abrechnung](https://docs.stripe.com/get-started/account/statement-descriptors.md) sind auf 22 Zeichen begrenzt, dürfen die Sonderzeichen `<`, `>`, `'`, `"` oder `*` nicht enthalten und dürfen nicht ausschließlich aus Zahlen bestehen. Bei Verwendung dynamischer Zahlungsbeschreibungen in der Abrechnung wird der dynamische Text an das [Präfix der Beschreibung](https://dashboard.stripe.com/settings/public) angehängt. Ein `*` und ein Leerzeichen werden ebenfalls hinzugefügt, um die Standard-Zahlungsbeschreibung vom dynamischen Teil zu trennen. Diese 22 Zeichen werden auf die Zeichenbegrenzung angerechnet. ## Informationen in Metadaten speichern Für die meisten gängigen Anfragen, beispielsweise die Zahlungsverarbeitung, unterstützt Stripe das Hinzufügen von [Metadaten](https://docs.stripe.com/api.md#metadata). Metadaten sind für Kundinnen/Kunden nicht sichtbar und fließen auch nicht in die Kriterien ein, ob eine Zahlung durch unsere Betrugsprävention abgelehnt oder gesperrt wird. Anhand von Metadaten können Sie relevante Informationen mit den Aktivitäten auf Stripe verbinden. Alle Metadaten, die Sie angeben, lassen sich im Dashboard (beispielsweise auf der Detailseite einer Zahlung) anzeigen und stehen auch in allgemeinen Berichten zur Verfügung. Sie können beispielsweise der PaymentIntent für diese Bestellung die Bestell-ID für Ihren Shop hinzufügen. Auf diese Weise können Sie Zahlungen in Stripe ganz einfach mit Bestellungen in Ihrem System abgleichen. Wenn Sie *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) nutzen, sollten Sie in Erwägung ziehen, zusätzliche Kunden- und Bestellinformationen als Metadaten zu übergeben. Dann können Sie [Radar-Regeln mit Metadatenattributen](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) erstellen und haben im Dashboard mehr Informationen zur Verfügung, wodurch Ihr Überprüfungsvorgang beschleunigt werden kann. Wenn ein PaymentIntent eine Zahlung erstellt, werden die Metadaten in die Zahlung kopiert. Nachfolgende Aktualisierungen der Metadaten des PaymentIntent ändern die Metadaten der Zahlungen, die zuvor durch den PaymentIntent erstellt wurden, nicht. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "payment_method_types[]=card" \ -d "metadata[order_id]=6735" ``` > Speichern Sie keine sensiblen Daten (personenbezogene Daten, Kartenangaben usw.) als Metadaten oder im Parameter `description` der PaymentIntent. ## See also - [Zahlungen online annehmen](https://docs.stripe.com/payments/accept-a-payment.md?platform=web) - [Zahlung in einer iOS-App akzeptieren](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios) - [Zahlung in einer Android-App akzeptieren](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android) - [Zukünftige Zahlungen einrichten](https://docs.stripe.com/payments/save-and-reuse.md)