Passer aux API Payment Intents et Payment Methods

Découvrez comment passer des API Sources et Tokens à l'API Payment Methods.

L’API Payment Methods doit désormais être privilégiée aux API Tokens et Sources pour permettre aux intégrations de collecter et de stocker des informations de paiement. Elle interagit avec l’API Payment Intents afin de créer des paiements pour une vaste palette de moyens de paiement.

Nous prévoyons de désactiver la prise en charge de l’API Sources pour les moyens de paiement locaux. Si vous gérez actuellement des moyens de paiement locaux à l’aide de l’API Sources, vous devez les migrer vers l’API Payment Methods. Nous vous enverrons de plus amples informations par e-mail concernant la fin de la prise en charge des API Sources et Tokens.

Si nous ne prévoyons pas de mettre fin à la prise en charge des moyens de paiement par carte, nous vous recommandons tout de même de passer aux API Payment Methods et Payment Intents. Pour en savoir plus sur la migration des méthodes de paiement par carte, consultez la page Migration vers l’API Payment Intents.

Migrer les moyens de paiement locaux de l’API Sources vers l’API Payment Intents

Pour migrer votre intégration pour les moyens de paiement locaux, mettez à 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.

Si vous utilisez Stripe Checkout ou le Payment Element, vous pouvez ajouter et gérer la plupart des moyens de paiement depuis le Dashboard Stripe sans toucher à votre code.

Pour obtenir des informations spécifiques sur l’intégration d’un moyen de paiement local à l’aide de l’API Payment Methods, consultez les instructions relatives à ce moyen de paiement dans la documentation sur les moyens de paiement. Le tableau suivant fournit une comparaison des différents types de paiement.

Intégration ancienne	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
Autorisez un paiement en chargeant un widget ou en redirigeant vers un tiers	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 les informations auprès de votre client et effectuer le paiement en fonction du moyen de paiement
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.succeeded`	Confirmer que la session Checkout a abouti avec le webhook `payment_intent.succeeded`	Confirmer que le PaymentIntent a abouti avec le webhook `payment_intent.succeeded`	Confirmer que le PaymentIntent a abouti avec le webhook `payment_intent.succeeded`

Mise en garde

Un objet PaymentIntent 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, 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.

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.status	Signification	Instructions spéciales
`succeeded`	Le paiement a abouti.	Non applicable
`requires_payment_method`	Le paiement a échoué.	Non applicable
`requires_action`	Le client n’a pas mené à bien l’autorisation de paiement.	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.

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. Avec les PaymentIntents, au lieu de vérifier les erreurs sur un objet Source, vous vérifiez les erreurs au niveau du PaymentIntent quand il est créé et après que le client a autorisé le paiement. La plupart des erreurs sur un PaymentIntent sont de type invalid_request_error. Elles sont renvoyées dans une requête non valide.

Lorsque vous migrez votre intégration, gardez à l’esprit que les codes d’erreur liés au PaymentIntent peuvent différer des codes d’erreur correspondants pour les sources.

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. Le tableau suivant contient quelques exemples.

Ancien webhook	Nouveau webhook sur Checkout	Nouveau webhook sur Payment Intents	Instructions spéciales
`source.chargeable`	Non applicable	Non applicable
`source.failed`	Non applicable	Non applicable
`source.canceled`	Non applicable	Non applicable
`charge.succeeded`	`checkout.session.completed`	`payment_intent.succeeded`	Le webhook `charge.succeeded` est également envoyé, vous n’avez donc pas besoin de mettre à jour votre intégration pour écouter le nouveau webhook.
`charge.failed`	Non applicable : le client peut retenter le paiement au cours de la même session Checkout jusqu’à son expiration, auquel cas vous recevez un événement `checkout.session.expired`.	`payment_intent.payment_failed`	Le 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.created`	`charge.dispute.created`	`charge.dispute.created`

Migration vers l’API Payment Methods

La principale différence entre les API Payment Methods et Sources réside dans le fait que l’API Sources décrit l’état de la transaction par l’intermédiaire de la propriété status. Par conséquent, chaque objet Source doit basculer sur un état acceptant les paiements pour pouvoir être utilisé lors d’un paiement. A contrario, un objet PaymentMethod n’a pas d’état et repose sur l’objet PaymentIntent pour représenter l’état du paiement.

Remarque

Le tableau suivant ne constitue pas une liste exhaustive des moyens de paiement. Si vous intégrez d’autres moyens de paiement à l’aide de l’API Sources, migrez-les également vers l’API Payment Methods.

Flux	Intégration de Payment Method avec l’API Payment Intents	API Tokens ou Sources avec API Charges
Cartes bancaires	Paiements par carte	Pris en charge avec Tokens ; non recommandé avec Sources
Prélèvement automatique ACH	Prélèvements automatiques de comptes bancaires aux États-Unis	Pris en charge avec Tokens ; non pris en charge avec Sources
Virement ACH	Virements bancaires en USD	Obsolète
Alipay	Paiements Alipay	Obsolète
Bancontact	Paiements Bancontact	Obsolète
EPS	Paiements EPS	Obsolète
giropay	Paiements giropay	Obsolète
iDEAL	Paiements iDEAL	Obsolète
Klarna	Paiements Klarna	Obsolète
Multibanco	Paiements Multibanco	Bêta obsolète
Przelewy24	Paiements Przelewy24	Obsolète
Virement SEPA	Virements bancaires en EUR	Obsolète
Prélèvement SEPA	Prélèvements automatiques de l’espace unique de paiements en euros (SEPA)	Obsolète
Sofort	Paiements Sofort	Obsolète
WeChat Pay	Paiements WeChat Pay	Obsolète

Après avoir choisi l’API à intégrer, utilisez le guide des moyens de paiement pour déterminer les types de moyens de paiement à prendre en charge.

Ce guide présente des descriptions détaillées de chaque moyen de paiement et décrit les différences dans les flux client, ainsi que les régions géographiques dans lesquelles ils sont le plus pertinents. Vous pouvez activer tous les moyens de paiement figurant dans le Dashboard. De manière générale, cette activation est instantanée et ne nécessite pas de contrats supplémentaires.

Compatibilité avec les anciens moyens de paiement réutilisables

Si vous avez précédemment traité l’un des moyens de paiement réutilisables suivants à l’aide de Sources, les sources existantes enregistrées ne sont pas migrées automatiquement :

Alipay
Prélèvement automatique Bacs
Prélèvement SEPA

pour conserver les moyens de paiement enregistrés de vos clients existants, vous devez convertir ces sources en moyens de paiement à l’aide d’un outil de migration de données dans le Dashboard Stripe. Pour connaître la procédure à suivre, consultez la page de support.

Compatibilité avec les anciens objets Card

Si vous avez déjà collecté des informations de paiement auprès de clients avec Stripe à l’aide de cartes ou de l’API Sources, vous pouvez commencer à utiliser l’API Payment Methods immédiatement et sans migrer ces informations de paiement.

Les instruments de paiement compatibles enregistrés dans un objet Customer peuvent être utilisés dans toute API acceptant un objet PaymentMethod. Par exemple, vous pouvez utiliser une carte bancaire enregistrée comme objet PaymentMethod lors de la création d’un PaymentIntent :

N’oubliez pas de fournir l’ID de l’objet Customer dans lequel votre instrument de paiement compatible est enregistré lorsque vous associez l’objet à un PaymentIntent.

Vous pouvez récupérer l’ensemble des moyens de paiement enregistrés compatibles par le biais de l’API Payment Methods.

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

Ce mécanisme de compatibilité n’entraîne la création d’aucun nouvel objet : l’API Payment Methods propose une vue différente du même objet sous-jacent. Par exemple, les mises à jour apportées à un instrument de paiement compatible par le biais de l’API Payment Methods sont visibles via l’API Sources et inversement.