Transition vers l'API Payment Intents et l'API Payment Methods

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

L’API Payment Methods remplace les API Tokens et Sources existantes en tant que moyen recommandé pour les intégrations pour collecter et stocker les informations de paiement. Elle fonctionne avec l’API Payment Intents pour créer des paiements pour un large éventail de moyens de paiement.

Nous prévoyons de désactiver la prise en charge d’API Sources pour les moyens de paiement locaux. Si vous gérez actuellement des moyens de paiement locaux à l’aide d’API Sources, vous devez les migrer vers l’API Payment Methods. Nous enverrons un courriel qui comprend plus d’informations sur la fin de la prise en charge d’API Sources et l’API Tokens.

Bien que nous ne prévoyions pas de mettre fin à la prise en charge des moyens de paiement par carte, nous vous recommandons de les migrer vers les API Payment Methods et Payment Intents. Pour plus d’informations sur la migration des moyens de paiement par carte, voir Migrations vers l’API Payment Intents.

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

Pour migrer votre intégration vers des moyens de paiement locaux, mettez à jour votre serveur et votre système frontal pour utiliser l’API PaymentIntents. Il existe trois options d’intégration typiques :

Redirigez vers Stripe Checkout pour votre flux de paiement.
Utilisez le Stripe Paiement Element sur votre propre page de paiement.
Créez votre propre formulaire et utilisez la trousse SDK Stripe JS pour effectuer le paiement.

Si vous utilisez Stripe Checkout ou Payment Element, vous pouvez ajouter et gérer la plupart des moyens de paiement à partir du Dashboard Stripe sans apporter de modifications au 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 de haut niveau des différents types de paiement.

Ancienne intégration	Stripe Checkout	Payment Element	Propre formulaire
	Faible complexité	Complexité moyenne	Complexité élevée
Créez une source dans l’application frontale ou sur le serveur	Créez une session Checkout sur le serveur	Créez un PaymentIntent sur le serveur	Créez un PaymentIntent sur le serveur
Autorisez le paiement en chargeant un gadget ou en redirigeant vers un tiers	Non nécessaire	Transmettez la clé secrète du client à l’application frontale et utilisez la trousse SDK Stripe JS pour afficher un Payment Element et effectuer le paiement.	Transmettez la clé secrète du client à l’application frontale, utilisez votre propre formulaire pour collecter les informations auprès de votre client et effectuez le paiement en fonction du moyen de paiement.
Confirmez que la source est facturable et chargez la source	Non nécessaire	Non nécessaire	Non nécessaire
Confirmez que le paiement a été effectué de manière asynchrone avec le webhook `charge.succeeded`	Confirmez que la session de Checkout a été effectuée avec le webhook `payment_intent.succeeded`	Confirmez que le PaymentIntent a été effectué avec le webhook `payment_intent.succeeded`	Confirmez que le PaymentIntent a été effectué avec le webhook `payment_intent.succeeded`

Avertissement

Un objet PaymentIntent représente un paiement dans la nouvelle intégration, et il crée un paiement lorsque vous confirmez le paiement dans l’application frontale. Si vous avez déjà sauvegardé des références au paiement, vous pourrez continuer à le faire en récupérant l’ID de paiement dans le PaymentIntent une fois que le client aura effectué le paiement. Cependant, nous vous recommandons également de sauvegarder l’ID de PaymentIntent.

Vérification de l’état du paiement

Auparavant, votre intégration aurait dû vérifier l’état de la source et l’état du paiement après chaque appel à l’API. Vous n’avez plus besoin de vérifier les deux états. Il vous suffit de vérifier l’état du PaymentIntent ou de la session de Checkout après l’avoir confirmé dans l’application frontale.

payment_intent.status	Signification	Instructions spéciales
`succeeded`	Le paiement a été effectué.	Sans objet
`requires_payment_method`	Le paiement a échoué.	Sans objet
`requires_action`	Le client n’a pas terminé l’autorisation du paiement.	Si le client n’effectue pas le paiement dans les 48 heures, le PaymentIntent passe à `requires_payment_method` et vous pouvez réessayer d’effectuer la confirmation.

Confirmez toujours l’état du PaymentIntent en le récupérant sur votre serveur ou en écoutant les webhooks sur votre serveur. Ne comptez pas uniquement sur le fait que l’utilisateur retourne à l’adresse URL return_url fournie lorsque vous confirmez le PaymentIntent.

Remboursements

Vous pouvez continuer à effectuer des appels à l’API Refunds avec un paiement 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 plutôt que celui du paiement.

Gestion des erreurs

Auparavant, vous deviez gérer les erreurs dans l’API Sources. Avec PaymentIntents, plutôt que de vérifier les erreurs dans une source, vous vérifiez les erreurs dans le PaymentIntent lorsqu’il est créé et après que le client a autorisé le paiement. La plupart des erreurs dans le PaymentIntent sont de type invalid_request_error, qui sont retournées lorsqu’une demande est non valide.

Lorsque vous migrez votre intégration, il est important de noter que les codes d’erreur du PaymentIntent peuvent différer des codes d’erreur correspondants de l’API Sources.

Webhooks

Si vous avez déjà écouté des événements source, vous devrez peut-être mettre à jour votre intégration pour écouter les nouveaux types d’événements. Le tableau suivant présente quelques exemples.

Ancien webhook	Nouveau webhook dans Checkout	Nouveau webhook dans PaymentIntents	Instructions spéciales
`source.chargeable`	Sans objet	Sans objet
`source.failed`	Sans objet	Sans objet
`source.canceled`	Sans objet	Sans objet
`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`	Sans objet - Le client peut tenter à nouveau d’effectuer le paiement dans la même session Checkout jusqu’à ce qu’elle expire, 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é d’état. Par conséquent, chaque objet Source doit passer à un état facturable pour que vous puissiez l’utiliser pour un paiement. En revanche, un objet PaymentMethod n’a pas d’état et repose sur l’objet PaymentIntent pour représenter l’état du paiement.

Remarques

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

Flux	Intégrer Payment Mehotd avec l’API Payment Intents	API Tokens ou Sources avec API Charges
Cartes	Paiements par carte	Pris en charge sur Tokens; Non recommandé sur Sources
Prélèvement automatique ACH	Prélèvements automatiques de compte bancaire aux États-Unis	Pris en charge sur Tokens Non pris en charge sur Sources
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
Prélèvement SEPA	Prélèvements automatiques dans l’Espace unique de paiement en euros	Obsolète
Sofort	Paiements Sofort	Obsolète
WeChat Pay	Paiements WeChat Pay	Obsolète

Une fois que vous avez choisi l’API à 'intégrer, consultez le guide des moyens de paiement pour vous aider à déterminer les types de moyens de paiement que vous devez prendre en charge.

Ce guide décrit en détail chaque moyen de paiement et les différences dans les procédures pour le client, ainsi que les régions géographiques dans lesquelles ils sont les plus pertinents. Vous pouvez activer tous les moyens de paiement qui figurent dans le Dashboard. De manière générale, l’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 préserver les moyens de paiement de vos clients existants enregistrés, vous devez convertir ces sources en moyens de paiement à l’aide d’un outil de migration de données dans le Dashboard Stripe. Pour savoir comment les convertir, consultez la page du service d’assistance.

Compatibilité avec les anciens objets de carte

Si vous avez déjà recueilli des informations de paiement par carte 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.

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 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 tous les instruments de paiement compatibles enregistrés via 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 au moyen de l’API Sources, et inversement.