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 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.

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.

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.

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.

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 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:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "payment_method_types[]"=card \
  -d amount=1099 \
  -d currency=usd \
  -d customer=
{{CUSTOMER_ID}} \
  -d payment_method=
{{CARD_ID}}

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.

{
  "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,

Mit dieser Kompatibilität werden keine neuen Objekte erstellt. 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.