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](https://b.stripecdn.com/docs-statics-srv/assets/klarna_on_pi_image_1.506e683101b89d2a5c34b5d5d7bde362.png)
Déclenchement du paiement Klarna sur Payment Intents
![L'exécution du flux de transaction Klarna sur PaymentIntents](https://b.stripecdn.com/docs-statics-srv/assets/klarna_on_pi_image_2.8ab6e30014bbbf5e9afd33268bddea0b.png)
Finalisation du paiement Klarna sur Payment Intents
Différences notables![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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égration | Stripe Checkout | Payment Element | Votre propre formulaire |
---|---|---|---|
Faible complexité | Complexité moyenne | Complexité élevée | |
Créer un objet Source sur le front-end ou sur le serveur | Créer une session Checkout sur le serveur | Créer un PaymentIntent sur le serveur | Cré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 source | Je n’en ai pas besoin | Je n’en ai pas besoin | Je n’en ai pas besoin |
Confirmer que le paiement a abouti de manière asynchrone à l’aide du webhook charge. | Confirmer que la session Checkout a abouti avec le webhook payment_ | Confirmer que le PaymentIntent a abouti avec le webhook payment_ | Confirmer que le PaymentIntent a abouti avec le webhook payment_ |
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 :
- Assurez-vous que Klarna est activé dans votre Dashboard.
- Créez une session Checkout sur votre serveur. Vous pouvez définir explicitement
klarna
comme l’un despayment_
ou utiliser des moyens de paiement dynamiques.method_ types - 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 - Redirigez le client vers l’URL de la session pour qu’il procède au paiement.
Option 2 : Utiliser le Payment Element![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 :
- Assurez-vous que Klarna est activé dans votre Dashboard.
- Créer un PaymentIntent sur votre serveur
Vous pouvez explicitement activer Klarna en le définissant comme l’un des payment_method_types.
- Transmettez la clé secrète du client du PaymentIntent au front-end et initialisez la bibliothèque de l’interface utilisateur de Stripe Elements.
- 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.
- 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 :
- Assurez-vous que Klarna est activé dans votre Dashboard.
- Créez un PaymentIntent sur votre serveur.
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.
- Utilisez un formulaire pour collecter l’adresse e-mail et le pays de facturation de votre client.
- 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 champsbilling_
etdetails[email] billing_
.details[address][country]
Documentation sur le mappage des champs![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 Source | Nouveau champ du PaymentIntent | Note |
---|---|---|
Champs obligatoires | ||
type | payment_ | 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. |
amount | amount | |
currency | currency | |
owner[email] | payment_ | Non requis lorsque vous utilisez le Payment Element. Cette information est collectée automatiquement. |
owner[address][country] | payment_ | 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_ | 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_ | 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_ | shipping[tracking_ | |
order[shipping][phone] | shipping[phone] | |
Autres champs facultatifs | ||
klarna[purchase_ | payment_ | |
klarna[first_ | payment_ | Facultatif. Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces. |
klarna[last_ | payment_ | Facultatif. Indiquer le prénom et le nom en une seule chaîne de caractères séparée par des espaces. |
klarna[locale] | payment_ | Ce champ doit être au format « en-US » avec le code du pays en majuscules. Il doit être cohérent par rapport au pays renseigné dans les informations de facturation (par exemple, fr-FR n’est pas une combinaison valide aux États-Unis). Vous trouverez la liste des régions prises en charge par pays dans notre documentation. |
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_ | 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_ | 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.status | Signification | Note |
---|---|---|
succeeded | Le paiement a abouti. | |
requires_ | Le paiement a échoué. | |
requires_ | Le 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_
fournie lorsque vous confirmez le PaymentIntent. Pour en savoir plus, cliquez ici.
Remboursements![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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_
. Vous pouvez également fournir l’ID du PaymentIntent à l’API Refunds à la place de l’objet Charge.
Gestion des erreurs![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 source | Nouveau type d’erreur lors de la création ou de la confirmation du PaymentIntent | Note |
---|---|---|
payment_ | invalid_ | |
processing_ | invalid_ | |
missing_ | Non applicable. Vous n’avez pas besoin de fournir les articles vendus lors de la création du PaymentIntent. | |
country_ | invalid_ | |
country_ | invalid_ | |
invalid_ | invalid_ | |
invalid_ | invalid_ | |
invalid_ | Non applicable. Ce champ n’est pas obligatoire et est collecté par Klarna sur leur page. | |
invalid_ | Non applicable. Ce champ n’est pas obligatoire et est collecté par Klarna sur leur page. |
Webhooks![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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 webhook | Nouveau webhook dans Checkout | Nouveau webhook sur Payment Intents | Note |
---|---|---|---|
source. | Sans objet | Sans objet | |
source. | Sans objet | Sans objet | |
source. | Sans objet | Sans objet | |
charge. | checkout. | payment_ | Le webhook charge. est également envoyé, vous n’avez donc pas besoin de mettre à jour votre intégration pour écouter le nouveau webhook. |
charge. | Non 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. . | payment_ | Le webhook charge. est également envoyé, vous n’avez donc pas besoin de mettre à jour votre intégration pour écouter le nouveau webhook. |
charge. | charge. | charge. |