Migration vers l'API Payment Intents

Vous souhaitez utiliser Stripe Billing, Stripe Tax, les remises, la livraison ou la conversion de devises?

Nous développons une intégration pour le composant Payment Element qui gère les abonnements, les taxes, les réductions, les frais de livraison et la conversion des devises. Pour en savoir plus, lisez le guide Créer une page de paiement.

Découvrez comment migrer l’intégration existante de vos cartes et de l’API Charges.

La migration de votre flux de paiement peut être rébarbative. Pour cette raison, il est préférable de mettre à jour l’API Payment Intents et de l’utiliser avec l’API Charges. Ainsi, vous pouvez fractionner les étapes de migration comme suit :

Mettez à jour votre version de l’API et votre bibliothèque client.
S’il y a lieu, migrez le code qui lit les propriétés de Charge de façon à ce que vous obteniez une lecture cohérente entre les paiements créés par l’API Charges et ceux créés par l’API Payment Intents. Ainsi, vous obtenez une intégration en lecture qui fonctionne avec vos nouvelles et vos anciennes intégrations.
Pour utiliser l’API Payment Intents, effectuez la migration de l’intégration de votre API Charges existante sur le Web, iOS ou Android.
Migrez votre intégration qui enregistre les cartes bancaires sur les objets Customer.
Effectuez des tests avec nos cartes de test pour vérifier que votre intégration mise à niveau gère correctement l’authentification.

Mettre à jour la version de votre API et votre bibliothèque client

Bien que l’API Payment Intents fonctionne avec toutes les versions d’API, nous vous recommandons de la mettre à niveau vers la version la plus récente de l’API. Si vous décidez d’utiliser une version d’API antérieure au 2019-02-11, notez les deux modifications suivantes dans l’exemple de code :

requires_source a été renommé requires_payment_method
requires_source_action a été renommé requires_action

De plus, si vous utilisez l’une de nos trousses SDK, vous devez mettre à niveau la bibliothèque vers sa dernière version pour pouvoir utiliser l’API Payment Intents.

Migrer vos flux de paiements ponctuels

L’élaboration d’une intégration avec Stripe.js et Elements comprend les étapes suivantes :

Enregistrer votre intention d’encaisser le paiement côté serveur
Collecter les informations de paiement côté client
Lancer la création du paiement
Traiter la commande du client côté serveur

Étape 1 : Enregistrer votre intention d’encaisser le paiement côté serveur

Créez un PaymentIntent sur votre serveur et mettez-le à disposition côté client.

Avant

Après

Impossible avant

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1099 \
  -d "currency"="usd"

Étape 2 : Collecter les informations de paiement côté client

Utilisez la fonction confirmCardPayment, qui collecte les informations de paiement et les envoie directement à Stripe.

Avant

Après

stripe.createToken(
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  INTENT_SECRET_FROM_STEP_1,
  {
    payment_method: {card: cardElement}
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Étape 3 : Lancer la création du paiement

Dans votre intégration existante, la dernière étape consiste à utiliser les informations de paiement transformées en jeton pour créer un paiement sur votre serveur. Cela n’est plus nécessaire puisque la fonction confirmCardPayment appelée à l’étape précédente lance la création du paiement.

Avant

Après

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Effectué à l’étape précédente

Étape 4 : Traiter la commande du client

Avec la confirmation automatique, le paiement est créé de façon asynchrone en fonction des actions du client côté client. Vous devez donc surveiller les webhooks pour savoir si le paiement a abouti. Pour effectuer les étapes comme le traitement de la commande après que le paiement d’un client a réussi, implémentez la prise en charge des webhooks et surveillez l’événement payment_intent.succeeded.

Avant

Après

Si le paiement réussit, traitez la commande.

Abonnez-vous au webhook payment_intent.succeeded et traitez la commande dans le gestionnaire de webhooks.

Maintenant que vous avez terminé la migration, utilisez les cartes de test de la section suivante pour vérifier que votre intégration mise à niveau prend en charge l’authentification 3D Secure.

Migrez votre intégration qui enregistre les cartes sur les objets Customer

Une intégration d’API Payment Intents qui collecte les informations de carte dans le flux de paiement comprend les étapes suivantes :

Enregistrer votre intention d’encaisser le paiement côté serveur
Collecter les informations de paiement côté client
Lancer la création du paiement
Traiter la commande du client côté serveur

Étape 1 : Enregistrer votre intention d’encaisser le paiement côté serveur

Créez un PaymentIntent sur votre serveur. Configurez cette option setup_future_usage à off_session si vous prévoyez de débiter les utilisateurs lorsqu’ils sont déconnectés de votre application ou à on_session si vous prévoyez de les débiter lorsqu’ils sont connectés à votre application. Si vous prévoyez d’utiliser la carte pour les paiements effectués pendant la session et hors session, utilisez off_session. Si vous indiquez le paramètre setup_future_usage avec l’ID d’un client, vous enregistrerez alors le PaymentMethod correspondant pour ce client après que le PaymentIntent a été confirmé et que le client a effectué toutes les actions requises. Ensuite, rendez le PaymentIntent accessible côté client.

Avant

Après

Impossible avant

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "setup_future_usage"="off_session" \
  -d "amount"=1099 \
  -d "currency"="usd"

Étape 2 : Collecter les informations de paiement côté client

Utilisez la fonction confirmCardPayment, qui collecte les informations de paiement et les envoie directement à Stripe.

Avant

Après

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  '{{INTENT_SECRET_FROM_STEP_1}}',
  {
    payment_method: {card: cardElement},
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Enfin, associez le moyen de paiement (paymentIntent.payment_method) au client.

Avant

Après

Command Line
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/sources \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "source"="{{TOKEN_OR_SOURCE}}"

Command Line
curl https://api.stripe.com/v1/payment_method/{{PAYMENT_METHOD_ID}}/attach \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer"="{{CUSTOMER_ID}}"

Étape 3 : Lancer la création du paiement

Avant

Après

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Effectué à l’étape précédente

Étape 4 : Traiter la commande du client

Avant

Après

Si le paiement réussit, traitez la commande.

Abonnez-vous au webhook payment_intent.succeeded et traitez la commande dans le gestionnaire de webhooks.

Maintenant que vous avez terminé la migration, utilisez les cartes de test de la section suivante pour vérifier que votre intégration mise à niveau prend en charge l’authentification 3D Secure.

Accéder aux moyens de paiement enregistrés

Pour afficher les Cards, Sources et PaymentMethods précédemment enregistrés par le client, ne lisez pas la propriété sources de l’objet Customer, mais affichez plutôt la liste des moyens de paiement. En effet, les nouveaux PaymentMethods ajoutés par le client ne seront pas dupliqués dans la propriété sources de l’objet Customer.

Avant

Après

Command Line

customer.sources

Command Line
curl https://api.stripe.com/v1/payment_methods?customer={{CUSTOMER_ID}}&type=card \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Testez l’intégration

Il est important de tester l’ensemble de votre intégration pour vérifier qu’elle prend correctement en charge les cartes qui nécessitent une authentification supplémentaire et celles qui n’en nécessitent pas. Validez la bonne gestion de ces deux cas de figure par votre intégration en utilisant ces numéros de carte dans un bac à sable avec n’importe quelle date d’expiration future et n’importe quel code CVC à trois chiffres.

Numéro	Authentification	Description
	Requis lors de la configuration ou de la première transaction	Cette carte de test exige une authentification pour les paiements ponctuels. Toutefois, si vous configurez cette carte avec l’API Setup Intents et utilisez la carte enregistrée pour des paiements ultérieurs, aucune autre authentification n’est nécessaire.
	Obligatoire	Cette carte de test exige une authentification pour toutes les transactions.
	Obligatoire	Cette carte de test exige l’authentification, mais les paiements seront refusés avec un code d’échec `insufficient_funds` après une authentification réussie.
	Pris en charge	Cette carte de test prend en charge l’authentification par 3D Secure 2, mais ne l’exige pas. Les paiements effectués à l’aide de cette carte ne nécessitent pas d’authentification supplémentaire dans un bac à sable, sauf si vos règles Radar du bac à sable exigent l’authentification.

Utilisez ces cartes dans votre application ou la démonstration de paiement pour voir les différences de comportement.

Migration vers l'API Payment Intents

Vous souhaitez utiliser Stripe Billing, Stripe Tax, les remises, la livraison ou la conversion de devises?

Mettre à jour la version de votre API et votre bibliothèque client

Migrer vos flux de paiements ponctuels

Étape 1 : Enregistrer votre intention d’encaisser le paiement côté serveur

Étape 2 : Collecter les informations de paiement côté client

Étape 3 : Lancer la création du paiement

Étape 4 : Traiter la commande du client

Migrez votre intégration qui enregistre les cartes sur les objets Customer

Étape 1 : Enregistrer votre intention d’encaisser le paiement côté serveur

Étape 2 : Collecter les informations de paiement côté client

Étape 3 : Lancer la création du paiement

Étape 4 : Traiter la commande du client

Accéder aux moyens de paiement enregistrés

Testez l’intégration

Voir aussi