Klarna von Sources migrieren

Migrieren Sie eine Integration von der Sources API auf die Payment Intents API.

Klarna führt einen neuen Checkout-Prozess ein, der die Payment Methods API und die Payment Intents API erfordert. In diesem Leitfaden werden mehrere empfohlene Pfade für die Migration von der Verwendung der Sources API beschrieben, einschließlich einer Low-Code-Option, die Stripe Checkout verwendet.

Funktion ist veraltet

Wir haben die Unterstützung für die Sources API für Klarna eingestellt und planen, sie Anfang 2024 vollständig abzuschaffen. Wenn Sie die Sources API immer noch zum Abwickeln von Klarna-Zahlungen verwenden, steigen Sie jetzt auf PaymentMethods und PaymentIntents um.

Der Start des Klarna-Transaktionsvorgangs für PaymentIntents

Klarna-Zahlung für PaymentIntents initiieren

Der Abschluss des Klarna-Transaktionsvorgangs für PaymentIntents

Klarna-Zahlung für PaymentIntents abschließen

Nennenswerte Unterschiede

** Klarna-Produktauswahl**: Sie müssen den Klarna-Produkttyp in Ihrer Integration nicht angeben. Stattdessen wählen Kundinnen und Kunden ein Produkt jetzt auf der Klarna-Weiterleitungsseite aus. Fügen Sie auf Ihrer Bezahlvorgangsseite keine eigene Schaltfläche für jede unterstützte Klarna-Zahlungsoption ein. Fügen Sie nur eine einzige Klarna-Schaltfläche ein.
Inline-Anzeige im Klarna SDK wird nicht unterstützt: Kundinnen und Kunden müssen jetzt von Ihrer Zahlungsseite auf die Klarna-Website weitergeleitet werden, um die Zahlung zu autorisieren. Daher müssen Sie das Klarna SDK nicht laden und keine Inline-Komponenten rendern.
Die Zahlungsbestätigung erfolgt in allen Märkten synchron: Zuvor erfolgte die Bestätigung einer erfolgreichen Zahlung in einigen Fällen asynchron. Jetzt können Sie sofort nach der Autorisierung durch den Kunden/die Kundin feststellen, ob die Zahlung erfolgreich war.

Vorsicht

Wenn Sie derzeit ein Plugin für Ihre Stripe Integration verwenden, müssen die Plugin-Entwickler/innen ihr Plugin auf die Nutzung von PaymentMethods und PaymentIntents umstellen. Wenden Sie sich an sie, um zu erfahren, ob Sie Änderungen an Ihren Stripe- oder Plugin-Einstellungen vornehmen müssen.

Ihren Zahlungsablauf umstellen

Um Ihre Klarna-Integration für Webzahlungen zu migrieren, müssen Sie Ihren Server und Ihr Frontend aktualisieren, damit die PaymentIntents API verwendet wird. Es gibt drei typische Optionen für die Integration:

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.

Verwenden Sie Stripe Checkout oder das Payment Element, um die meisten Zahlungsmethoden über das Stripe-Dashboard hinzuzufügen und zu verwalten, ohne Codeänderungen vorzunehmen.

Nachfolgend finden Sie einen allgemeinen Vergleich der alten Integrationsschritte mit den neuen Integrationen:

Alte Integration	Stripe Checkout	Payment Element	Eigenes Formular
	Geringe Komplexität	Mittlere Komplexität	Hohe Komplexität
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
Laden Sie das Klarna-Widget mit dem Klarna SDK, um die Zahlung zu autorisieren ODER Zur Autorisierung der Zahlung an Klarna weiterleiten	Nicht erforderlich	Übergeben Sie das Client-Geheimnis an das Frontend und verwenden Sie das Stripe JS SDK, um ein Payment Element zu rendern, um die Zahlung abzuschließen.	Übergeben Sie das Client-Geheimnis an das Frontend. Verwenden Sie Ihr eigenes Formular, um zusätzliche Details von Ihren Kundinnen und Kunden zu erfassen, und verwenden Sie das Stripe JS SDK für die Weiterleitung an Klarna
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 ist das Objekt, das eine Zahlung in der neuen Integration darstellt und eine Abbuchung erstellt, wenn Sie die Zahlung im Frontend bestätigen. Wenn Sie zuvor in Ihren Datenbanken 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.

Option 1: Eine Checkout Sitzung verwenden

Stripe Checkout ist eine gehostete Low-Code-Zahlungslösung, die Klarna-Zahlungen sowie eine Vielzahl anderer von Stripe unterstützter Zahlungsmethoden akzeptieren kann. Wenn Sie derzeit eine Zahlungsseite auf Ihrer Website gehostet haben und stattdessen Stripe Checkout verwenden möchten, gehen Sie wie folgt vor:

Stellen Sie sicher, dass Klarna in Ihrem Dashboard aktiviert ist.
Erstellen Sie eine Checkout-Sitzung auf Ihrem Server. Sie können entweder explizit klarna als einen der payment_method_types festlegen oder dynamische Zahlungsmethoden verwenden.
Wenn Sie physische Waren verkaufen, aktivieren Sie die Erfassung der Versandadresse oder fügen Sie die Versandadresse im Hash shipping_details hinzu.
An die Sitzungs-URL weiterleiten, wenn die Kundin/der Kunde bereit ist zu bezahlen

Option 2: Payment Element verwenden

Stripe Payment Element ist eine einzelne eingebettete Nutzeroberflächen-Komponente für Ihre Zahlungsseite, die neben Klarna auch andere Zahlungsmethoden unterstützt. Es bietet viele der Funktionen von Stripe Checkout, wird jedoch auf Ihrer eigenen Zahlungsseite angezeigt. Gehen Sie wie folgt vor, um das Payment Element zu verwenden:

Stellen Sie sicher, dass Klarna in Ihrem Dashboard aktiviert ist.
PaymentIntent auf Ihrem Server erstellen

Sie können Klarna explizit aktivieren, indem Sie Klarna als einen der payment_method_types festlegen.

Übergeben Sie das Client-Geheimnis des PaymentIntent an das Frontend und initialisieren Sie die Nutzeroberfläche von Stripe Elements.
Erstellen Sie ein Payment Element und betten Sie es in die Seite ein. Dieses Element erfasst automatisch alle zusätzlichen Felder, die für die von den Kundinnen und Kunden ausgewählte Zahlungsmethode benötigt werden.
Rufen Sie confirmPayment für das Payment Element auf, wenn der/die Nutzer/in die Zahlung übermittelt. Übergeben Sie unbedingt eine return_url.

Option 3: Ihr eigenes Formular erstellen

Sie können Ihre eigenen Formularkomponenten erstellen und eine Klarna-Zahlung mit dem Stripe JS SDK abschließen. Erfahren Sie mehr über die vollständige Integration. Um diese Methode zu integrieren, gehen Sie wie folgt vor:

Stellen Sie sicher, dass Klarna in Ihrem Dashboard aktiviert ist.
Erstellen Sie einen PaymentIntent auf Ihrem Server.

Wenn Sie Zahlungsmethoden nicht über das Dashboard verwalten möchten, können Sie Klarna explizit aktivieren, indem Sie es als einen der payment_method_types festlegen.

Verwenden Sie ein Formular, um die E-Mail-Adresse und das Abrechnungsland Ihrer Kundinnen und Kunden zu erfassen.
Initialisieren Sie Stripe.JS auf Ihrer Zahlungsseite und rufen Sie confirmKlarnaPayment mit dem Client-Geheimnis des PaymentIntent auf, wenn der Kunde/die Kundin bereit ist, die Zahlung zu autorisieren. Stellen Sie sicher, dass die E-Mail-Adresse und das Land der Abrechnung in den Feldern billing_details[email] und billing_details[address][country] angegeben sind.

Referenz für die Feldzuordnung

Wenn Sie das Payment Element oder Ihr eigenes Formular verwenden, müssen Sie die Felder zuvor auf der Quelle dem PaymentIntent erneut zuordnen. Die folgende Tabelle zeigt eine Zuordnung der alten Felder zu den neuen Feldern. Wenn Sie physische Waren verkaufen, empfehlen wir Ihnen, Versanddetails zu übergeben. Alle anderen Felder sind optional, und Klarna erfasst die notwendigen zusätzlichen Informationen auf ihrer Seite.

Altes Quellfeld	Neues PaymentIntent-Feld	Notiz
Erforderliche Felder
`type`	`payment_method_types[]`	Dies ist ein Array für PaymentIntents. Legen Sie `klarna` als eines der Elemente des Arrays fest, wenn Sie Zahlungsmethoden manuell aufführen.
`amount`	`amount`
`currency`	`currency`
`owner[email]`	`payment_method_data[billing_details][email]`	Bei Verwendung des Payment Element nicht erforderlich. Es wird automatisch erfasst.
`owner[address][country]`	`payment_method_data[billing_details][address][country]`	Bei Verwendung des Payment Element nicht erforderlich. Es wird automatisch erfasst.
Empfohlen, wenn Sie physische Waren verkaufen
`klarna[shipping_first_name]`	`shipping[name]`	Geben Sie sowohl den Vor- als auch den Nachnamen als einzelne durch Leerzeichen getrennte Zeichenfolge an.
`klarna[shipping_last_name]`	`shipping[name]`	Geben Sie sowohl den Vor- als auch den Nachnamen als einzelne durch Leerzeichen getrennte Zeichenfolge an.
`order[shipping][address]`	`shipping[address]`	Komponenten finden Sie in der API-Dokumentation.
`order[shipping][carrier]`	`shipping[carrier]`
`order[shipping][tracking_number]`	`shipping[tracking_number]`
`order[shipping][phone]`	`shipping[phone]`
Weitere optionale Felder
`klarna[purchase_country]`	`payment_method_data[billing_details][address][country]`
`klarna[first_name]`	`payment_method_data[billing_details][name]`	Optional. Geben Sie sowohl den Vor- als auch den Nachnamen als einzelne durch Leerzeichen getrennte Zeichenfolge an.
`klarna[last_name]`	`payment_method_data[billing_details][name]`	Optional. Geben Sie sowohl den Vor- als auch den Nachnamen als einzelne durch Leerzeichen getrennte Zeichenfolge an.
Nicht mehr erforderlich
`klarna[product]`		Gilt nicht für PaymentIntents. Kundinnen und Kunden wählen das Klarna-Produkt, wenn sie die Zahlung auf der Klarna-Website autorisieren.
`klarna[shipping_delay]`		Nicht zutreffend. Wenn Sie eine Versandverzögerung erwarten, verwenden Sie die separate Authentifizierung und Erfassung, damit die Zahlung erst nach Versand des Produkts erfasst wird.
`source_orders[items]`		Nicht mehr erforderlich.

Vorsicht

Wenn Sie derzeit den Parameter klarna[attachment] oder den Parameter order[items] für die Quelle verwenden, teilen wir Ihnen Einzelheiten zu diesen Parametern mit.

Nach dem Kauf

Die folgenden Änderungen sind für alle Integrationspunkte erforderlich, die Sie nach Abschluss einer Zahlung haben.

Zahlungsstatus prü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	Notiz
`succeeded`	Die Zahlung war erfolgreich.
`requires_payment_method`	Die Zahlung ist fehlgeschlagen.
`requires_action`	Der Kunde/die Kundin hat die Autorisierung der Zahlung auf der Website von Klarna nicht abgeschlossen.	Wenn der Kunde/die Kundin 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 der/die Nutzer/in zu der return_url zurückkehrt, die angegeben wird, wenn Sie den PaymentIntent bestätigen. Mehr dazu erfahren Sie hier.

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.

Fehlerbehandlung

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

Alter Fehlercode beim Erstellen der Quelle	Neuer Fehlertyp beim Erstellen oder Bestätigen des PaymentIntent	Notiz
`payment_method_not_available`	`invalid_request_error`
`processing_error`	`invalid_request_error`
`missing_sku_item_quantity`		Nicht zutreffend. Beim Erstellen des PaymentIntent müssen Sie die verkauften Artikel nicht angeben.
`country_currency_mismatch`	`invalid_request_error`
`country_not_supported`	`invalid_request_error`
`invalid_currency`	`invalid_request_error`
`invalid_email`	`invalid_request_error`
`invalid_phone`		Nicht zutreffend. Dieses Feld ist nicht erforderlich und wird von Klarna auf der entsprechenden Seite erfasst.
`invalid_address`		Nicht zutreffend. Dieses Feld ist nicht erforderlich und wird von Klarna auf der entsprechenden Seite erfasst.

Webhooks

Wenn Sie zuvor Source-Ereignisse überwacht haben, müssen Sie möglicherweise Ihre Integration aktualisieren, um neue Ereignistypen zu überwachen. Nachfolgend finden Sie eine Übersicht über die neuen Ereignistypen, die Sie überwachen müssen.

Alter Webhook	Neuer Webhook in Checkout	Neuer Webhook für PaymentIntents	Notiz
`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`