Auf die Payment Intents API und die Payment Methods API umstellen
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 werden die Unterstützung für die Sources API für lokale Zahlungsmethoden einstellen. Wenn Sie derzeit lokale Zahlungsmethoden über die Sources API abwickeln, müssen Sie diese auf die Payment Methods API umstellen. Wir werden Ihnen weitere Informationen zu diesem Thema per E-Mail mitteilen.
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.
Zuordnungsfelder
Wenn Sie das Payment Element oder Ihr eigenes Formular nutzen, müssen Sie die Quellfelder den PaymentIntent-Feldern neu zuordnen. Die spezifischen Felder hängen von der Zahlungsmethode ab.
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 | Hinweis |
---|---|---|
succeeded | Die Zahlung war erfolgreich. | |
requires_payment_method | Die Zahlung ist fehlgeschlagen. | |
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 | Hinweis |
---|---|---|---|
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 es für eine Zahlung verwendet werden kann. 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 |
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 | Geplant | Veraltete Beta |
Przelewy24 | Przelewy24 payments | Veraltet |
SEPA-Lastschrift | Single Euro Payments Area-Lastschriften | Veraltet |
Sofort | Sofort-Zahlungen | Veraltet |
WeChat Pay | Zahlungen per WeChat Pay | Veraltet |
Nachdem Sie die API ausgewählt haben, mit der die Integration stattfinden soll, hilft Ihnen unser Leitfaden für Zahlungsmethoden dabei, die richtigen Zahlungsmethoden für Ihre Kundinnen und Kunden zu finden.
Dieser Leitfaden enthält genaue Beschreibungen jeder Zahlungsmethode und erklärt die Unterschiede zwischen den kundenorientierten Zahlungsabläufen sowie die geografischen Regionen, in denen die jeweilige Zahlungsmethode am relevantesten ist. Sie können jede im Dashboard verfügbare Zahlungsmethode aktivieren. Die Aktivierung erfolgt in der Regel sofort und erfordert keine zusätzlichen Vereinbarungen oder langwierigen Prozesse.
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. 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.
- Alipay
- BACS-Lastschriftverfahren
- SEPA-Lastschrift
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 Zahlungsinstrumente, die für einen/eine Kund/in gespeichert wurden, können in jeder API verwendet werden, die ein PaymentMethod-Objekt akzeptiert. So können Sie zum Beispiel beim Speichern eines PaymentIntent eine gespeicherte Karte als PaymentMethod verwenden:
Denken Sie daran, die Kunden-ID anzugeben, unter der Ihr kompatibles Zahlungsinstrument gespeichert ist, wenn Sie das Objekt an eine PaymentIntent anhängen.
Sie können alle gespeicherten kompatiblen Zahlungsinstrumente über die Payment Methods API abrufen.
Beachten Sie, dass mit dieser Kompatibilität keine neuen Objekte erstellt werden. Die Payment Methods API bietet eine andere Ansicht desselben zugrunde liegenden Objekts. Aktualisierungen eines kompatiblen Zahlungsinstruments über die Payment Methods API sind beispielsweise über die Sources API sichtbar und umgekehrt.