Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous

Migrer Klarna depuis Sources

Migrez une intégration de l'API Sources vers l'API Payment Intents.

Klarna lance un nouveau processus de paiement qui nécessite l’utilisation de l’API Payment Methods et de l’API Payment Intents. Ce guide décrit plusieurs chemins de migration recommandés pour effectuer votre migration depuis l’API Sources, dont une option à faible code utilisant Stripe Checkout.

Fonctionnalité obsolète

Nous ne prenons plus en charge l’API Sources pour Klarna, et prévoyons de la supprimer début 2024. Si vous utilisez toujours l’API Sources pour traiter les paiements Klarna, effectuez votre migration dès maintenant pour utiliser les PaymentMethods et PaymentIntents.

Le début du flux de transaction Klarna sur Payment Intents

Déclenchement du paiement Klarna sur Payment Intents

L'exécution du flux de transaction Klarna sur PaymentIntents

Finalisation du paiement Klarna sur Payment Intents

Différences notables

  • Sélection de produit Klarna : vous n’avez pas besoin de spécifier le type de produit Klarna dans votre intégration. À la place, les clients choisissent désormais un produit sur la page de redirection Klarna. Ajoutez un seul bouton Klarna sur votre page de paiement, et non pas un bouton distinct pour chaque option de paiement Klarna.
  • L’affichage intégré du SDK Klarna n’est pas pris en charge : les clients doivent désormais être redirigés vers le site Klarna à partir de votre page de paiement pour autoriser le paiement. Par conséquent, vous n’avez pas besoin de charger le SDK Klarna ni d’afficher les composants intégrés.
  • La confirmation de paiement est synchronisée sur tous les marchés : auparavant, la confirmation d’un paiement ayant abouti pouvait être asynchrone. À présent, vous pouvez détecter si le paiement a abouti immédiatement après que votre client l’a autorisé.

Mise en garde

Si vous utilisez actuellement un plugin pour votre intégration Stripe, le développeur du plugin doit effectuer la migration de son plugin pour utiliser les PaymentMethods et les PaymentIntents. Contactez-le pour savoir si vous devez apporter des modifications à vos paramètres Stripe ou à ceux du plugin.

Migrer votre tunnel de paiement

Pour migrer votre intégration Klarna pour les paiements Web, vous devez mettre à jour votre serveur et votre front-end afin d’utiliser l’API Payment Intents. Voici les trois options d’intégration classiques :

  • Rediriger les clients vers Stripe Checkout pour votre tunnel de paiement.
  • Utilisez le Payment Element de Stripe sur votre propre page de paiement.
  • Créer votre propre formulaire et utilisez le SDK Stripe JS pour effectuer le paiement.

Utilisez Stripe Checkout ou le Payment Element pour ajouter et gérer la plupart des moyens de paiement depuis le Dashboard Stripe sans toucher à votre code.

Vous trouverez ci-dessous une comparaison détaillée entre les anciennes et les nouvelles étapes d’intégration :

Ancienne intégrationStripe CheckoutPayment ElementVotre propre formulaire

Faible complexité

Complexité moyenne

Complexité élevée

Créer un objet Source sur le front-end ou sur le serveurCréer une session Checkout sur le serveurCréer un PaymentIntent sur le serveurCréer un PaymentIntent sur le serveur

Charger le widget Klarna avec le SDK Klarna pour autoriser le paiement

OU

Rediriger le client vers Klarna pour autoriser le paiement

Je n’en ai pas besoin

Transmettre la clé secrète du client au front-end et utiliser le SDK Stripe JS pour afficher un Payment Element afin de mener à bien le paiement

Transmettre la clé secrète du client au front-end, utiliser votre propre formulaire pour recueillir des informations supplémentaires auprès de votre client et utiliser le SDK Stripe JS pour le rediriger vers Klarna.

Confirmer que la source peut être débitée et débiter la sourceJe n’en ai pas besoinJe n’en ai pas besoinJe n’en ai pas besoin
Confirmer que le paiement a abouti de manière asynchrone à l’aide du webhook charge.succeededConfirmer que la session Checkout a abouti avec le webhook payment_intent.succeededConfirmer que le PaymentIntent a abouti avec le webhook payment_intent.succeededConfirmer que le PaymentIntent a abouti avec le webhook payment_intent.succeeded

Mise en garde

Un PaymentIntent est l’objet qui représente un paiement dans la nouvelle intégration. Il crée un objet Charge lorsque vous confirmez le paiement sur le front-end. Si vous avez précédemment enregistré des références au paiement dans vos bases de données, vous pouvez continuer à le faire en récupérant l’ID du PaymentIntent une fois que le client a effectué le paiement. Cependant, nous vous recommandons également d’enregistrer l’ID du PaymentIntent.

Option 1 : Utiliser une session Checkout

Stripe Checkout est une solution de paiement hébergée avec peu d’écriture code et qui accepte les paiements Klarna, ainsi que de nombreux autres moyens de paiement pris en charge par Stripe. Si vous hébergez actuellement une page de paiement sur votre site et que vous souhaitez utiliser Stripe Checkout, procédez comme suit :

  1. Assurez-vous que Klarna est activé dans votre Dashboard.
  2. Créez une session Checkout sur votre serveur. Vous pouvez définir explicitement klarna comme l’un des payment_method_types ou utiliser des moyens de paiement dynamiques.
  3. Si vous vendez des biens physiques, activez la collecte de l’adresse de livraison ou incluez l’adresse de livraison dans le hachage shipping_details.
  4. Redirigez le client vers l’URL de la session pour qu’il procède au paiement.

Option 2 : Utiliser le Payment Element

Le Payment Element Stripe est un composant d’interface utilisateur intégré unique pour votre page de paiement qui prend en charge Klarna ainsi que d’autres moyens de paiement. Il offre de nombreuses fonctionnalités de Stripe Checkout, mais s’affiche sur votre propre page de paiement. Pour utiliser le Payment Element, procédez comme suit :

  1. Assurez-vous que Klarna est activé dans votre Dashboard.
  2. Créer un PaymentIntent sur votre serveur
Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "automatic_payment_methods[enabled]"=true \
  -d amount=1099 \
  -d currency=eur

Vous pouvez explicitement activer Klarna en le définissant comme l’un des payment_method_types.

  1. Transmettez la clé secrète du client du PaymentIntent au front-end et initialisez la bibliothèque de l’interface utilisateur de Stripe Elements.
  2. Créez un Payment Element et intégrez-le à la page. Cet élément collecte automatiquement tous les champs supplémentaires nécessaires selon le moyen de paiement sélectionné par le client.
  3. Appelez confirmPayment sur le Payment Element lorsque l’utilisateur procède au paiement. Assurez-vous de transmettre une return_url.

Option 3 : Créer votre propre formulaire

Vous pouvez créer vos propres composants de formulaire et effectuer un paiement Klarna à l’aide du SDK Stripe JS. En savoir plus sur l’intégration complète. Pour intégrer cette méthode, procédez comme suit :

  1. Assurez-vous que Klarna est activé dans votre Dashboard.
  2. Créez un PaymentIntent sur votre serveur.
Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "automatic_payment_methods[enabled]"=true \
  -d amount=1099 \
  -d currency=eur

Si vous ne souhaitez pas gérer les moyens de paiement via le Dashboard, vous pouvez explicitement activer Klarna en le définissant comme l’un des payment_method_types.

  1. Utilisez un formulaire pour collecter l’adresse e-mail et le pays de facturation de votre client.
  2. Initialisez Stripe.JS sur votre page de paiement et appelez confirmKlarnaPayment avec la clé secrète du client du PaymentIntent lorsque le client est prêt à autoriser le paiement. Assurez-vous que son adresse e-mail et son pays de facturation figurent dans les champs billing_details[email] et billing_details[address][country].

Documentation sur le mappage des champs

Si vous utilisez le Payment Element ou votre propre formulaire, vous devez rediriger les champs de la source vers le PaymentIntent. Le tableau ci-dessous schématise les correspondances entre les anciens champs et les nouveaux. Si vous vendez des biens physiques, nous vous recommandons de transmettre les informations de livraison. Tous les autres champs sont facultatifs, et Klarna recueille les informations supplémentaires nécessaires sur sa page.

Ancien champ SourceNouveau champ du PaymentIntentNote
Champs obligatoires
typepayment_method_types[]Il s’agit d’un tableau de PaymentIntents. Définissez klarna comme l’un des éléments du tableau si vous répertoriez les moyens de paiement manuellement.
amountamount
currencycurrency
owner[email]payment_method_data[billing_details][email]Non requis lorsque vous utilisez le Payment Element. Cette information est collectée automatiquement.
owner[address][country]payment_method_data[billing_details][address][country]Non requis lorsque vous utilisez le Payment Element. Cette information est collectée automatiquement.
Champs recommandés si vous vendez des biens physiques
klarna[shipping_first_name]shipping[name]Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces.
klarna[shipping_last_name]shipping[name]Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces.
order[shipping][address]shipping[address]Veuillez consulter la documentation de l’API pour connaître les composants.
order[shipping][carrier]shipping[carrier]
order[shipping][tracking_number]shipping[tracking_number]
order[shipping][phone]shipping[phone]
Autres champs facultatifs
klarna[purchase_country]payment_method_data[billing_details][address][country]
klarna[first_name]payment_method_data[billing_details][name]Facultatif. Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces.
klarna[last_name]payment_method_data[billing_details][name]Facultatif. Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces.
N’est plus requis
klarna[product]Non applicable pour l’API Payment Intents. Les clients choisissent le produit Klarna lorsqu’ils autorisent le paiement sur le site de Klarna.
klarna[shipping_delay]Non applicable. Si vous prévoyez un retard de livraison, utilisez l’autorisation et la capture distinctes pour capturer le paiement uniquement après l’expédition du produit.
source_orders[items]N’est plus requis.

Mise en garde

Si vous utilisez actuellement le paramètre klarna[attachment] ou le paramètre order[items] dans l’objet Source, nous vous contacterons pour vous fournir des informations sur ces paramètres.

Après l’achat

Les modifications suivantes sont requises pour tous les points d’intégration survenant suite à la finalisation d’un paiement.

Vérification de l’état du paiement

Auparavant, votre intégration aurait dû vérifier à la fois l’état des objets Source et Charge après chaque appel à l’API. Ce n’est plus nécessaire désormais ; il suffit de vérifier l’état du PaymentIntent ou de la session Checkout après confirmation sur le front-end.

payment_intent.statusSignificationNote
succeededLe paiement a abouti.
requires_payment_methodLe paiement a échoué.
requires_actionLe client n’a pas mené à bien l’autorisation de paiement sur le site de Klarna.Si le client ne finalise pas le paiement dans les 48 heures, le PaymentIntent passe à requires_payment_method et vous pouvez retenter la confirmation.

Confirmez toujours l’état du PaymentIntent en le récupérant ou en écoutant les webhooks sur votre serveur. Ne comptez pas uniquement sur le retour de l’utilisateur à la return_url fournie lorsque vous confirmez le PaymentIntent. Pour en savoir plus, cliquez ici.

Remboursements

Vous pouvez continuer à appeler l’API Refunds avec l’objet Charge créé par le PaymentIntent. L’ID du paiement est accessible dans le paramètre latest_charge. Vous pouvez également fournir l’ID du PaymentIntent à l’API Refunds à la place de l’objet Charge.

Gestion des erreurs

Auparavant, vous deviez gérer les erreurs sur les Sources qui étaient créées. Avec l’API Payment Intents, vous n’avez pas besoin de vérifier les erreurs sur les objets Source, mais sur le PaymentIntent au moment de sa création et après que le client a autorisé le paiement. La plupart des erreurs sur le PaymentIntent concernent le champ type renvoyé dans une requête non valide.

Ancien code d’erreur lors de la création de la sourceNouveau type d’erreur lors de la création ou de la confirmation du PaymentIntentNote
payment_method_not_availableinvalid_request_error
processing_errorinvalid_request_error
missing_sku_item_quantityNon applicable. Vous n’avez pas besoin de fournir les articles vendus lors de la création du PaymentIntent.
country_currency_mismatchinvalid_request_error
country_not_supportedinvalid_request_error
invalid_currencyinvalid_request_error
invalid_emailinvalid_request_error
invalid_phoneNon applicable. Ce champ n’est pas obligatoire et est collecté par Klarna sur leur page.
invalid_addressNon applicable. Ce champ n’est pas obligatoire et est collecté par Klarna sur leur page.

Webhooks

Si vous écoutiez précédemment des événements sources, vous devrez peut-être mettre à jour votre intégration pour écouter de nouveaux types d’événements. Vous trouverez ci-dessous une liste des nouveaux types d’événements à écouter.

Ancien webhookNouveau webhook dans CheckoutNouveau webhook sur Payment IntentsNote
source.chargeableSans objetSans objet
source.failedSans objetSans objet
source.canceledSans objetSans objet
charge.succeededcheckout.session.completedpayment_intent.succeededLe webhook charge.succeeded est également envoyé, vous n’avez donc pas besoin de mettre à jour votre intégration pour écouter le nouveau webhook.
charge.failedNon applicable : le client peut retenter le paiement au cours de la même session Checkout jusqu’à son expiration, auquel cas vous recevrez un événement checkout.session.expired.payment_intent.payment_failedLe webhook charge.failed est également envoyé, vous n’avez donc pas besoin de mettre à jour votre intégration pour écouter le nouveau webhook.
charge.dispute.createdcharge.dispute.createdcharge.dispute.created
Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service d'assistance.
Rejoignez notre programme d'accès anticipé.
Consultez notre journal des modifications des produits.
Des questions ? Contactez l'équipe commerciale.
Propulsé par Markdoc