Migration vers l'API Payment Intents

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

Nous développons une intégration de Payment Element qui gère les abonnements, les taxes, les remises, les frais d’expédition et la conversion de 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 tunnel 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 clients.
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 clients

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 11-02-2019, 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’un de nos SDK, vous devez passer à la dernière version de la bibliothèque pour pouvoir utiliser l’API Payment Intents.

Migrer vos tunnels 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 tokenisées 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 bancaires sur les objets Customer

Une intégration d’API Payment Intents qui collecte les informations de carte bancaire dans le tunnel 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. Définissez setup_future_usage sur off_session si vous comptez principalement facturer les utilisateurs lorsqu’ils sont déconnectés de votre application ou sur on_session si vous prévoyez de les facturer dans l’application. Si vous prévoyez de les facturer en session et hors session, utilisez off_session. Si vous indiquez le paramètre setup_future_usage avec un ID client, vous enregistrerez le PaymentMethod correspondant pour ce client une fois que le PaymentIntent aura été confirmé et que toutes les actions requises du client auront été effectuées. Ensuite, mettez le PaymentIntent à disposition 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
:

Tester 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 de test dans un environnement de test 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 via 3D Secure 2, mais ne l’exige pas. Les paiements utilisant cette carte ne nécessitent pas une authentification supplémentaire dans un environnement de test, sauf si vos règles Radar de l’environnement de test) 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, Tax, les remises, les frais de livraison ou la conversion de devises ?

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

Migrer vos tunnels 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 bancaires 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

Tester l’intégration

Voir aussi