Auf die Payment Intents API und die Payment Methods API umstellen

Erfahren Sie, wie Sie von der Sources API und der Tokens API zur Payment Methods API wechseln.

Die Payment Methods API ersetzt die vorhandenen Token- und Sources APIs als empfohlene Option zum Erfassen und Speichern von Zahlungsinformationen für Integrationen. Sie arbeitet mit der Payment Intents API zusammen, um Zahlungen für eine Vielzahl von Zahlungsmethoden zu erstellen.

Wir planen, die Sources API für lokale Zahlungsmethoden zu deaktivieren. Wenn Sie derzeit lokale Zahlungsmethoden mit der Sources API verarbeiten, müssen Sie diese zur Payment Methods API migrieren. Weite Informationen zur eingestellten Unterstützung der Sources API und der Tokens API senden wir Ihnen per E-Mail.

Obwohl wir nicht vorhaben, die Unterstützung für Kartenzahlungsmethoden zu deaktivieren, empfehlen wir Ihnen dennoch, diese auf die Payment Methods API und die Payment Intents API umzustellen. Weitere Informationen zur Umstellung von Kartenzahlungsmethoden finden Sie unter Auf die Payment Intents API umstellen.

Lokale Zahlungsmethoden von der Sources API zur Payment Intents API migrieren

Um Ihre Integration für lokale Zahlungsmethoden umzustellen, aktualisieren Sie Ihren Server und Ihr Frontend auf die Verwendung der PaymentIntents API. Es gibt drei typische Integrationsmöglichkeiten:

Führen Sie für Ihren Zahlungsablauf eine Weiterleitung zu Stripe Checkout durch.
Verwenden Sie das Payment Element von Stripe auf Ihrer eigenen Zahlungsseite.
Erstellen Sie Ihr eigenes Formular und verwenden Sie das Stripe JS SDK, um die Zahlung abzuschließen.

Wenn Sie Stripe Checkout oder das Payment Element verwenden, können Sie die meisten Zahlungsmethoden über das Stripe-Dashboard hinzufügen und verwalten, ohne Codeänderungen vornehmen zu müssen.

Weitere Informationen zur Integration einer lokalen Zahlungsmethode mithilfe der Payment Methods API finden Sie in den Anweisungen für diese Zahlungsmethode in der Dokumentation zu den Zahlungsmethoden. Die folgende Tabelle bietet einen allgemeinen Vergleich der verschiedenen Zahlungsarten.

Alte Integration	Stripe Checkout	Payment Element	Eigenes Formular
	Geringer Integrationsaufwand	Mittlerer Integrationsaufwand	Hoher Integrationsaufwand
Eine Quelle im Frontend oder auf dem Server erstellen	Eine Checkout-Sitzung auf dem Server erstellen	PaymentIntent auf dem Server erstellen	PaymentIntent auf dem Server erstellen
Zahlung autorisieren, indem ein Widget geladen oder an einen Drittanbieter weitergeleitet wird	Nicht erforderlich	Übergeben Sie das Client-Geheimnis an das Frontend und verwenden Sie das Stripe JS SDK, um ein Payment Element zu rendern und die Zahlung abzuschließen.	Übergeben Sie das Client-Geheimnis an das Frontend, verwenden Sie Ihr eigenes Formular, um Details von Ihren Kundinnen und Kunden zu erfassen, und schließen Sie die Zahlung gemäß der Zahlungsmethode ab
Bestätigen, dass die Quelle abrechenbar ist, und belasten der Quelle	Nicht erforderlich	Nicht erforderlich	Nicht erforderlich
Mit dem Webhook `charge.succeeded` bestätigen, dass die Zahlung asynchron erfolgreich durchgeführt wurde	Mit dem Webhook `payment_intent.succeeded` bestätigen, dass die Checkout-Sitzung erfolgreich durchgeführt wurde	Mit dem Webhook `payment_intent.succeeded`bestätigen, dass der PaymentIntent erfolgreich war	Mit dem Webhook `payment_intent.succeeded`bestätigen, dass der PaymentIntent erfolgreich war

Vorsicht

Ein PaymentIntent-Objekt stellt eine Zahlung in der neuen Integration dar und erstellt eine Abbuchung, wenn Sie die Zahlung im Frontend bestätigen. Wenn Sie zuvor Verweise auf die Abbuchung gespeichert haben, können Sie dies weiterhin tun, indem Sie die Abbuchungs-ID aus dem PaymentIntent abrufen, nachdem die Kundin/der Kunde die Zahlung abgeschlossen hat. Wir empfehlen jedoch auch, die PaymentIntent-ID zu speichern.

Zahlungsstatus überprüfen

Zuvor sollte Ihre Integration nach jedem API-Aufruf sowohl den Status der Quelle als auch den Status der Abbuchung überprüft haben. Sie müssen nicht mehr zwei Status überprüfen – Sie müssen nur den Status des PaymentIntent oder der Checkout-Sitzung überprüfen, nachdem Sie diesen im Frontend bestätigt haben.

payment_intent.status	Bedeutung	Besondere Hinweise
`succeeded`	Die Zahlung war erfolgreich.	Nicht zutreffend
`requires_payment_method`	Die Zahlung ist fehlgeschlagen.	Nicht zutreffend
`requires_action`	Die Kundin/der Kunde hat die Autorisierung der Zahlung nicht abgeschlossen.	Wenn die Kundin/der Kunde die Zahlung nicht innerhalb von 48 Stunden abschließt, wechselt der PaymentIntent zu `requires_payment_method`, und Sie können erneut versuchen, die Bestätigung einzuholen.

Bestätigen Sie den Status des PaymentIntent, indem Sie ihn von Ihrem Server abrufen oder die Webhooks auf Ihrem Server überwachen. Verlassen Sie sich nicht nur darauf, dass die Nutzerin/der Nutzer zu der return_url zurückkehrt, die angegeben wird, wenn Sie den PaymentIntent bestätigen.

Rückerstattungen

Sie können weiterhin die Refunds API mit einer vom PaymentIntent erstellten Abbuchung aufrufen. Die ID der Abbuchung erhalten Sie über den Parameter latest_charge.

Alternativ können Sie der Refunds API auch die PaymentIntent-ID anstelle der Abbuchung übermitteln.

Fehlerbehebung

Bisher mussten Fehler bei den Quellen behoben werden. Mit PaymentIntents müssen Sie eine Quelle nicht auf Fehler überprüfen. Stattdessen müssen Sie auf Fehler im PaymentIntent achten, wenn dieser erstellt wird und nachdem die Kundin/der Kunde die Zahlung autorisiert hat. Die meisten Fehler im PaymentIntent treten beim Typ invalid_request_error auf, der in einer ungültigen Anfrage zurückgegeben wurde.

Beachten Sie bei der Migration Ihrer Integration, dass die Fehlercodes des PaymentIntent von den entsprechenden Fehlercodes der Quellen abweichen können.

Webhooks

Wenn Sie zuvor Source-Ereignisse überwacht haben, müssen Sie möglicherweise Ihre Integration aktualisieren, um neue Ereignistypen zu überwachen. In der nachfolgenden Tabelle zeigen wir Ihnen einige Beispiele.

Alter Webhook	Neuer Webhook in Checkout	Neuer Webhook in PaymentIntents	Besondere Hinweise
`source.chargeable`	Nicht zutreffend	Nicht zutreffend
`source.failed`	Nicht zutreffend	Nicht zutreffend
`source.canceled`	Nicht zutreffend	Nicht zutreffend
`charge.succeeded`	`checkout.session.completed`	`payment_intent.succeeded`	Der Webhook `charge.succeeded` wird ebenfalls übermittelt, sodass Sie Ihre Integration nicht aktualisieren müssen, um den neuen Webhook zu überwachen.
`charge.failed`	Nicht zutreffend - Der Kunde/die Kundin kann die Zahlung für dieselbe Checkout-Sitzung bis zum Ablauf wiederholen. Anschließend erhalten Sie das Ereignis `checkout.session.expired`.	`payment_intent.payment_failed`	Der Webhook `charge.failed` wird ebenfalls übermittelt, sodass Sie Ihre Integration nicht aktualisieren müssen, um den neuen Webhook zu überwachen.
`charge.dispute.created`	`charge.dispute.created`	`charge.dispute.created`

Umstellung auf die Payment Methods API

Der Hauptunterschied zwischen der Payment Methods API und der Sources API besteht darin, dass Sources den Transaktionsstatus über die Eigenschaft Status beschreibt. Das bedeutet, dass jedes Source-Objekt in einen abrechenbaren Status übergehen muss, bevor Sie es für eine Zahlung verwenden können. Im Gegensatz dazu befindet sich eine PaymentMethod in gar keinem Status und ist auf das PaymentIntent-Objekt angewiesen, um den Zahlungsstatus darzustellen.

Notiz

Die folgende Tabelle umfasst nicht alle Zahlungsmethoden. Wenn Sie andere Zahlungsmethoden mit der Sources API integrieren, müssen Sie für diese ebenfalls eine Migration mit der Payment Methods API vornehmen.

Zahlungsabläufe	Zahlungsmethode mit Payment Intents API integrieren	Token oder Sources mit der Charges API
Karten	Kartenzahlungen	Unterstützt für Token; Nicht empfohlen für Sources
ACH-Lastschriftverfahren	US-Bankkonto-Lastschriften	Unterstützt für Token Nicht unterstützt für Sources
ACH-Überweisung	USD-Banküberweisungen	Veraltet
Alipay	Alipay-Zahlungen	Veraltet
Bancontact	Bancontact-Zahlungen	Veraltet
EPS	EPS-Zahlungen	Veraltet
giropay	Giropay-Zahlungen	Veraltet
iDEAL	iDEAL-Zahlungen	Veraltet
Klarna	Klarna-Zahlungen	Veraltet
Multibanco	Multibanco-Zahlungen	Veraltete Beta
Przelewy24	Przelewy24 payments	Veraltet
SEPA-Überweisung	EUR-Banküberweisungen	Veraltet
SEPA-Lastschrift	Single Euro Payments Area-Lastschriften	Veraltet
Sofort	Sofort-Zahlungen	Veraltet
WeChat Pay	Zahlungen per WeChat Pay	Veraltet

Nachdem Sie ausgewählt haben, mit welcher API die Integration stattfinden soll, nutzen Sie den Leitfaden zu Zahlungsmethoden. Dieser hilft Ihnen dabei, die Zahlungsmethoden zu ermitteln, die Sie unterstützen sollten.

Dieser Leitfaden enthält detaillierte Beschreibungen der einzelnen Zahlungsmethoden und beschreibt die Unterschiede in den kundenorientierten Abläufen sowie die geografischen Regionen, in denen sie am relevantesten sind. Sie können jede im Dashboard verfügbare Zahlungsmethode aktivieren. Die Aktivierung erfolgt in der Regel sofort und erfordert keine zusätzlichen Vereinbarungen.

Kompatibilität mit älteren wiederverwendbaren Zahlungsmethoden

Wenn Sie zuvor eine der folgenden wiederverwendbaren Zahlungsmethoden mit Sources verarbeitet haben, werden die vorhandenen gespeicherten Quellen nicht automatisch migriert.

Alipay
BACS-Lastschriftverfahren
SEPA-Lastschrift

Um die gespeicherten Zahlungsmethoden Ihrer bestehenden Kundinnen und Kunden zu erhalten, müssen Sie diese Quellen mithilfe eines Datenmigrationstools im Stripe-Dashboard in Zahlungsmethoden umwandeln. Anweisungen zur Umwandlung finden Sie auf der Support-Seite.

Kompatibilität mit älteren Card-Objekten

Wenn Sie zuvor Kartenzahlungsdetails von Kundinnen und Kunden mit Karten oder Sources erfasst haben, können Sie sofort mit der Nutzung der Payment Methods API starten, ohne Zahlungsinformationen übertragen zu müssen.

Kompatible Zahlungsmethoden, die für einen Kunden/eine Kundin gespeichert wurden, können in jeder API verwendet werden, die ein PaymentMethod-Objekt akzeptiert. So können Sie zum Beispiel beim Erstellen eines PaymentIntent eine gespeicherte Karte als PaymentMethod verwenden:

Denken Sie daran, die Kunden-ID anzugeben, unter der Ihre kompatible Zahlungsmethode gespeichert ist, wenn Sie das Objekt an einen PaymentIntent anhängen.

Sie können alle gespeicherten kompatiblen Zahlungsmethoden über die Payment Methods API abrufen.

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

Bei dieser Kompatibilität werden keine neuen Objekte erstellt. Die Payment Methods API bietet eine andere Ansicht desselben zugrunde liegenden Objekts. Aktualisierungen einer kompatiblen Zahlungsmethode über die Payment Methods API sind beispielsweise über die Sources API sichtbar und umgekehrt.