Die Payment Intents API

Verwenden Sie die Payment Intents API, um eine Integration zu erstellen, die komplexe Zahlungsabläufe mit einem Status verarbeiten kann, der sich innerhalb des Lebenszyklus des PaymentIntent ändert. Sie verfolgt Zahlungen von der Erstellung bis zum Bezahlvorgang und löst bei Bedarf zusätzliche Authentifizierungsschritte aus.

Die Payment Intents API bietet u. a. folgende Vorteile:

• Automatische Verarbeitung von Authentifizierungen
• Keine doppelten Zahlungen
• Keine Probleme mit Idempotenz-Schlüsseln
• Unterstützung der starken Kundenauthentifizierung (SCA) und anderer Vorschriftsänderungen

Eine komplette API-Lösung

Verwenden Sie die Payment Intents API zusammen mit der Setup Intents API und der Payment Methods API. Diese APIs helfen Ihnen beim Umgang mit dynamischen Zahlungen (beispielsweise bei einer zusätzlichen Authentifizierung mit 3D Secure) und bereiten Sie auch auf die Expansion in andere Länder vor, wobei Sie die Möglichkeit zur Unterstützung neuer Vorschriften und regionaler Zahlungsmethoden erhalten.

Das Entwickeln einer Integration mit der Payment Intents API erfordert zwei Aktionen, nämlich das Erstellen und Bestätigen 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. Darin wird beschrieben, wie Sie einen PaymentIntent auf dem Server erstellen und sein Client-Geheimnis an den Client übergeben, statt das gesamte PaymentIntent-Objekt zu übergeben.

Wenn Sie den PaymentIntent erstellen, können Sie Optionen wie Betrag und Währung angeben:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd

Best Practices

• Wir empfehlen, einen PaymentIntent zu erstellen, sobald Sie den Betrag kennen (z. B. wenn die Kundin/der Kunde den Zahlungsvorgang beginnt). So können Sie Ihren Kauftrichter nachverfolgen. Wenn sich der Betrag ändert, können Sie den Betrag des PaymentIntent aktualisieren. Wenn Ihre Kundin/Ihr Kunde den Bezahlvorgang beispielsweise verlässt und einen neuen Artikel zum Warenkorb hinzufügt, müssen Sie den Betrag eventuell entsprechend anpassen, wenn der Zahlungsvorgang erneut gestartet wird.

• 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 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 dabei hilft, fehlgeschlagene Zahlungsversuche für einen bestimmten Warenkorb oder eine bestimmte Sitzung nachzuverfolgen.

• Denken Sie daran, einen Idempotenzschlüssel 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, 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 oder stripe.handleCardAction, um die Zahlung abzuschließen.

Client-Geheimnis abrufen

Im PaymentIntent ist ein Client-Geheimnis enthalten, das auf dem Client verwendet wird, um Zahlungen sicher abzuschließen. Es gibt verschiedene Verfahren zum Übergeben des Client-Geheimnisses an den Client.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Nach der Zahlung

Nachdem der Client die Zahlung bestätigt hat, wird empfohlen, dass Ihr Server Webhooks überwacht, um zu erkennen, wann die Zahlung erfolgreich abgeschlossen wird oder fehlschlägt.

Einem PaymentIntent können mehr als ein Charge-Objekt zugeordnet sein, wenn mehrere Zahlungsversuche (z. B. Wiederholungsversuche) vorliegen. Für jede Zahlung können Sie das Ergebnis und die Details der verwendeten Zahlungsmethode prüfen.

Zahlungsmethoden für zukünftige Zahlungen optimieren

Der Parameter 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). Überlegen Sie, wie Sie diese Zahlungsmethode in Zukunft verwenden möchten, um zu festzulegen, welcher Wert verwendet werden soll.

Sie können weiterhin Off-Session-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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

Dynamische Zahlungsbeschreibung in der Abrechnung

Die Zahlungsbeschreibung in der Abrechnung wird standardmäßig in der Abrechnung Ihrer Kundinnen und Kunden angezeigt, wenn Sie ihre Karte belasten. Um eine andere Zahlungsbeschreibung auf Pro-Zahlungs-Basis anzugeben, fügen Sie den Parameter statement_descriptor ein.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

Zahlungsbeschreibungen in der Abrechnung 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 angehängt. Ein * und ein Leerzeichen werden ebenfalls hinzugefügt, um die Standard-Zahlungsbeschreibung vom dynamischen Teil zu trennen. Diese 2 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. 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 nutzen, sollten Sie in Erwägung ziehen, alle zusätzlichen Kunden- und Bestellinformationen als Metadaten zu übergeben. Dann können Sie Radar-Regeln mit Metadatenattributen 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 https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735