# Statusaktualisierung für Zahlungen Überwachen und verifizieren Sie den Zahlungsstatus, um auf erfolgreiche und fehlgeschlagene Zahlungen reagieren zu können. Aktualisierung von *PaymentIntents* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) als Antwort auf Aktionen des Kunden/der Kundin oder der Zahlungsmethode. Ihre Integration kann den PaymentIntent untersuchen, um den Status des Zahlungsvorgangs zu ermitteln, damit Sie Maßnahmen für Ihr Unternehmen ergreifen oder auf Status, die weitere Intervention erfordern, reagieren können. Sie können das Stripe-Dashboard auch verwenden, um Ihr Konto so zu konfigurieren, dass es Sie per E-Mail über den Zahlungsstatus informiert, z. B. bei erfolgreichen Zahlungen. Ändern Sie Ihre [E-Mail-Benachrichtigungen](https://docs.stripe.com/get-started/account/teams.md#email-notifications) in Ihren [Nutzereinstellungen](https://dashboard.stripe.com/settings/user). ## Zahlungs- und PaymentIntent-Status Die Seite [Payments](https://dashboard.stripe.com/payments) im Dashboard zeigt für jede Zahlung einen Zahlungsstatus an. Diesen können Sie zum Filtern der Liste nutzen. Der Status fasst die Zahlung zusammen, enthält aber keine zusätzlichen Details aus dem PaymentIntent-[Status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status). Der `Status` eines PaymentIntent entspricht dem Status einer Zahlung und gibt an, ob eine weitere Verarbeitung oder kundenseitige Maßnahmen erforderlich sind. So kann die Abwicklung einer Zahlung mit PaymentIntent eine Zahlungsmethode, eine Bestätigung oder eine andere Maßnahme erfordern. Im Dashboard werden diese Status als **Unvollständig** angezeigt. Für weitere Informationen, warum eine Zahlung den Status „unvollständig“ hat, klicken Sie auf die Zahlung und nutzen Sie den [Workbench Inspector](https://docs.stripe.com/workbench/overview.md#inspector), um die Details des PaymentIntent in JSON anzuzeigen. Suchen Sie nach `Status`, um den genauen Wert zu sehen. In der folgenden Tabelle wird jeder PaymentIntent-`Status` dem Zahlungsstatus im Dashboard zugeordnet. Grenzfälle, wie abgelaufene Versuche und bestimmte Ablehnungscodes, können diese Zuordnung beeinflussen. Verwenden Sie die API oder den Workbench Inspector, um den maßgeblichen Status zu erhalten. | PaymentIntent-`Status` | Zahlungsstatus | Beschreibung | | ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requires_payment_method` | **Unvollständig** | Wird typischerweise angezeigt, wenn [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) nicht verfügbar ist oder der Intent nicht über den Einzug hinaus fortgeschritten ist. Je nach Zahlungsmethode, Betrag und Fehler kann der Zahlungsstatus auch **Teilweise bezahlt**, **Wartet auf Finanzierung** oder **Fehlgeschlagen** lauten. | | `requires_confirmation` | **Unvollständig** | Wird angezeigt, nachdem ein Kunde/eine Kundin Zahlungsinformationen angegeben hat und zur Bestätigung bereit ist. Die meisten Integrationen überspringen diesen Zustand, da sie Informationen zur Zahlungsmethode erst nach Bestätigung der Zahlung übermitteln. | | `requires_action` | **Unvollständig** | Wird angezeigt, wenn die Zahlung zusätzliche Maßnahmen erfordert, wie z. B. die Authentifizierung mit [3D Secure](https://docs.stripe.com/payments/3d-secure.md). Der Zahlungsstatus im Dashboard kann unter bestimmten Authentifizierungs- oder Fehlerbedingungen auch **Teilweise bezahlt**, **Wartet auf Finanzierung** oder **Fehlgeschlagen** lauten. | | `processing` | **Ausstehend** | Wird angezeigt, wenn die erforderlichen Maßnahmen abgeschlossen sind und bei der Zahlung eine *asynchrone Zahlungsmethode* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) verwendet wird, wie z. B. eine Banklastschrift. Bei diesen Zahlungsmethoden kann die Abwicklung mehrere Tage dauern. | | `requires_capture` | **Nicht erfasst** oder **Anteilige Erfassung** | Wird angezeigt, wenn Ihr Zahlungsablauf eine [separate Erfassung](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md) verwendet. Wenn ein Betrag für den Intent eingeht, lautet der Status **Anteilige Erfassung**. Wenn kein Betrag eingeht, lautet der Status **Nicht erfasst**. | | `succeeded` | **Erfolgreich** | Ein PaymentIntent mit dem Status `succeeded` bedeutet, dass der entsprechende Zahlungsablauf abgeschlossen ist. Das Geld befindet sich auf Ihrem Konto und Sie können die Bestellung ausführen. Wenn der Zahlungsversuch fehlschlägt (zum Beispiel aufgrund einer Ablehnung), kehrt der Status des PaymentIntent zu `requires_payment_method` zurück, sodass die Zahlung erneut versucht werden kann. Spätere Rückerstattungen, Zahlungsanfechtungen und Ergebnisse werden in der Buchung ausgewiesen. Dadurch kann sich die Anzeige im Dashboard ändern, auch wenn der PaymentIntent bei `succeeded` bleibt. | | `canceled` | **Storniert** | Wird angezeigt, wenn die Zahlung storniert wurde. Wenn der Intent im Zuge einer fehlgeschlagenen Rechnungsstellung storniert wurde und die letzte Abbuchung fehlgeschlagen ist, kann der Status auch **Fehlgeschlagen** lauten. | ## Nächste Aktion ausführen Für manche Zahlungsmethoden sind zusätzliche Schritte erforderlich, wie z. B. eine Authentifizierung, um den Zahlungsvorgang abzuschließen. Stripe.js verarbeitet diese automatisch bei der Bestätigung des PaymentIntent. Wenn Sie über eine erweiterte Integration verfügen, können Sie diese aber auch manuell verarbeiten. Die Eigenschaft [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) des PaymentIntent gibt den nächsten Schritt an, den Ihre Integration verarbeiten muss, um die Zahlung abzuschließen. Welche nächsten Aktionen infrage kommen, hängt von der Zahlungsmethode ab. Eine vollständige Liste finden Sie in der [API-Dokumentation](https://docs.stripe.com/api.md#payment_intent_object-next_action-type). Erfahren Sie, wie Sie [die erforderlichen nächsten Aktionen einer Zahlungsmethode handhaben](https://docs.stripe.com/payments/payment-methods/overview.md). ## PaymentIntent-Status auf dem Client prüfen Beim Abschließen einer Zahlung auf dem Client über die Funktion [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) können Sie den zurückgegebenen PaymentIntent prüfen, um seinen aktuellen Status zu ermitteln: ```javascript (async () => { const {paymentIntent, error} = await stripe.confirmPayment({ elements, confirmParams: { return_url: 'https://example.com/order/complete', }, redirect: 'if_required', }); if (error) { // Handle error here } else if (paymentIntent && paymentIntent.status === 'succeeded') { // Handle successful payment here } })(); ``` Nachfolgend finden Sie die möglichen Ergebnisse beim Verwenden der Funktion `confirmPayment`: | **Ereignis** | **Was ist passiert** | **Erwartete Integration** | | -------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Wird mit einer PaymentIntent beigelegt | Der Kunde/die Kundin hat die Zahlung auf Ihrer Zahlungsseite abgeschlossen | Den Kunden/die Kundin über erfolgreiche Zahlung informieren | | Wird mit einem Fehler beigelegt | Die Zahlung des Kunden/der Kundin auf Ihrer Zahlungsseite ist fehlgeschlagen | Eine Fehlermeldung anzeigen und Ihren Kunden/Ihre Kundin zu einem erneuten Zahlungsversuch auffordern | Das von `confirmPayment` zurückgegebene Promise wird erfüllt, wenn der Zahlungsvorgang entweder abgeschlossen oder mit einem Fehler fehlgeschlagen ist. Wenn er erfolgreich abgeschlossen wurde und einen PaymentIntent zurückgibt, wird der Status immer als `succeeded` angezeigt (oder als `requires_capture` bei [späterer Erfassung](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). Wenn die Zahlung einen zusätzlichen Schritt wie beispielsweise Authentifizierung erfordert, wird das Promise erst erfüllt, wenn dieser Schritt abgeschlossen ist oder ein Timeout auftritt. ## Überprüfen Sie den Status des PaymentIntent auf dem Client ohne die Verwendung von confirmPayment Um den Status eines PaymentIntent ohne Verwendung der Funktion `confirmPayment` zu prüfen, rufen Sie ihn unabhängig davon mit der Funktion [retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) ab und übergeben Sie das *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)). ```javascript (async () => { const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret); if (paymentIntent && paymentIntent.status === 'succeeded') { // Handle successful payment here } else { // Handle unsuccessful, processing, or canceled payments and API errors here } })(); ``` Nachfolgend finden Sie einige [mögliche Status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) des PaymentIntent nach einer Bestätigung. | **Was ist passiert** | **Erwarteter PaymentIntent-Status** | | ---------------------------------------------------------------------------- | ----------------------------------- | | Der Kunde/die Kundin hat die Zahlung auf Ihrer Zahlungsseite abgeschlossen | `succeeded` | | Der Kunde/die Kundin hat die Zahlung nicht abgeschlossen | `requires_action` | | Die Zahlung des Kunden/der Kundin auf Ihrer Zahlungsseite ist fehlgeschlagen | `requires_payment_method` | [Erfahren Sie mehr über die PaymentIntent-Status](https://docs.stripe.com/payments/paymentintents/lifecycle.md). ## Überwachen Sie eine PaymentIntent mit Webhooks Stripe kann *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests)-Ereignisse an Ihren Server senden, um Sie zu benachrichtigen, wenn sich der Status einer PaymentIntent ändert. Dies ist hilfreich, um beispielsweise zu ermitteln, wann Sie die Waren und Dienstleistungen abwickeln müssen. Versuchen Sie nicht, die *Ausführung* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) auf der Client-Seite zu verarbeiten, da Kunden/Kundinnen die Seite nach Abschluss der Zahlung, jedoch vor Beginn des Abwicklungsprozesses verlassen können. Verwenden Sie stattdessen Webhooks, um das Ereignis `payment_intent.succeeded` zu überwachen und dessen Abschluss asynchron zu verarbeiten, statt zu versuchen, die Abwicklung auf der Client-Seite zu veranlassen. > Technisch ist es möglich, Abfragen statt Webhooks zu verwenden, um die von asynchronen Abläufen ausgelösten Änderungen zu überwachen. Dazu müssen Sie einen PaymentIntent wiederholt abrufen, um seinen Status zu prüfen. Dies ist jedoch wesentlich weniger verlässlich und kann zu Problemen in Bezug auf Ratenbegrenzungen führen. Stripe setzt [Ratenbegrenzungen](https://docs.stripe.com/testing.md#rate-limits) für API-Anfragen um, verwenden Sie Abfragen daher mit Bedacht. Um ein Webhook-Ereignis zu verarbeiten, erstellen Sie eine Route auf Ihrem Server und konfigurieren Sie einen entsprechenden Webhook-Endpoint [im Dashboard](https://dashboard.stripe.com/account/webhooks). Stripe sendet das `payment_intent.succeeded`-Ereignis, wenn die Zahlung erfolgt ist und das `payment_intent.payment_failed`-Ereignis, wenn die Zahlung fehlschlägt. Die Webhook-Nutzlast enthält das PaymentIntent-Objekt. Das folgende Beispiel erklärt den Umgang mit beiden Ereignissen: #### Ruby ```ruby require 'sinatra' require 'stripe' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature status 400 return end case event['type'] when 'payment_intent.succeeded' intent = event['data']['object'] puts "Succeeded:", intent['id'] # Fulfill the customer's purchase when 'payment_intent.payment_failed' intent = event['data']['object'] error_message = intent['last_payment_error'] && intent['last_payment_error']['message'] puts "Failed:", intent['id'], error_message # Notify the customer that payment failed end status 200 end ``` Wenn eine Zahlung fehlgeschlagen ist, finden Sie weitere Details, indem Sie die Eigenschaft `last_payment_error` des PaymentIntent untersuchen. Sie können den Kunden/die Kundin benachrichtigen, dass seine/ihre Zahlung nicht erfolgt ist und ihn/sie auffordern, es mit einer anderen Zahlungsmethode erneut zu versuchen. Verwenden Sie denselben PaymentIntent, um den Kauf des Kunden/der Kundin nachzuverfolgen. ### Bestimmte Webhook-Ereignisse verarbeiten Die folgende Liste beschreibt, wie Sie Webhook-Ereignisse verarbeiten: | Ereignis | Beschreibung | Nächste Schritte | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `processing` | Die Zahlung der Kundin oder des Kunden wurde erfolgreich an Stripe übermittelt. Dies gilt nur für Zahlungsmethoden mit [verzögerten Benachrichtigungen](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Warten Sie, bis die initiierte Zahlung erfolgt oder fehlschlägt. | | `succeeded` | Die Kundenzahlung war erfolgreich. | Führen Sie die Bestellung der gekauften Waren oder Dienstleistungen aus. | | `amount_capturable_updated` | Die Zahlung des Kunden oder der Kundin ist autorisiert und kann erfasst werden. | Erfassen Sie die Gelder, die für die Zahlung verfügbar sind. | | `payment_failed` | Die Zahlung des Kunden oder der Kundin wurde vom Kartennetzwerk abgelehnt oder ist aus einem anderen Grund verfallen. | Kontaktieren Sie Ihren Kunden oder Ihre Kundin per E-Mail oder Push-Benachrichtigung und fordern Sie ihn/sie auf, eine andere Zahlungsmethode anzugeben. | Verwenden Sie die [Stripe-CLI](https://docs.stripe.com/stripe-cli.md), um Webhooks lokal zu testen. Nach der Installation können Sie Ereignisse an Ihren Server weiterleiten: ```bash stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) ``` Erfahren Sie mehr über die [Einrichtung von Webhooks](https://docs.stripe.com/webhooks.md). ## Zahlungen auf einer PaymentIntent identifizieren Wenn Sie versuchen, eine Kundenzahlung einzuziehen, erstellt der PaymentIntent eine [Abbuchung](https://docs.stripe.com/api/charges.md). Zeigen Sie die [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)-Eigenschaft des PaymentIntent an, um die ID der aktuellen Zahlung prüfen zu können: #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') intent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}') latest_charge = intent.latest_charge ``` Um alle Abbuchungen im Zusammenhang mit einem PaymentIntent anzuzeigen, einschließlich aller fehlgeschlagener Abbuchungen, [listen Sie alle Abbuchungen](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) auf und geben Sie den `payment_intent​`-Parameter an. ```curl curl -G https://api.stripe.com/v1/charges \ -u "<>:" \ -d "payment_intent={{PAYMENTINTENT_ID}}" ```