Migrer vers Payment Element avec l’API Payment Intents

Affichez vos paramètres des moyens de paiement et activez les moyens de paiement que vous souhaitez prendre en charge. Vous devez activer au moins un moyen de paiement pour créer un PaymentIntent.

By default, Stripe enables cards and other prevalent payment methods that can help you reach more customers, but we recommend turning on additional payment methods that are relevant for your business and customers. See Payment method support for product and payment method support, and our pricing page for fees.

Ensuite, mettez à jour votre code côté client pour transmettre les paramètres mode, currency et amount lorsque vous créez l’instance Elements. Pour une utilisation avec un PaymentIntent, définissez le paramètre mode sur 'payment' et les paramètres currency et amount respectivement sur la devise et le montant que vous comptez facturer à votre client.

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements();

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
  mode: 'payment',
  currency: 'usd',
  amount: 1099,
};
const elements = stripe.elements(options);

Vous pouvez désormais remplacer le composant Element Card et les composants Elements des différents moyens de paiement par le composant Element Payment. Ce dernier s’adapte automatiquement pour recueillir les valeurs des champs de saisie en fonction du moyen de paiement et du pays (par exemple, collecte de l’adresse de facturation complète pour le prélèvement SEPA). Vous n’avez donc plus besoin de gérer des champs de saisie personnalisés.

L’exemple suivant remplace CardElement par PaymentElement :

<form id="payment-form">
  <div id="card-element">
  </div>
  <div id="payment-element">
    <!-- Mount the Payment Element here -->
  </div>
  <button id="submit">Submit</button>
</form>

const cardElement = elements.create("card");
cardElement.mount("#card-element");
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

Si votre tunnel de paiement collecte déjà systématiquement des informations telles que le nom ou l’adresse e-mail du client, vous pouvez empêcher le Payment Element de collecter ces informations en transmettant l’option fields lors de la création du Payment Element. Si vous désactivez la collecte d’un certain champ, vous devez renvoyer ces mêmes données avec stripe.confirmPayment.

Le Payment Element vous permet d’accepter plusieurs moyens de paiement. Vous pouvez gérer les moyens de paiement depuis le Dashboard. Stripe gère l’affichage des moyens de paiement admissibles en fonction de facteurs tels que le montant de la transaction, la devise et le tunnel de paiement. Nous priorisons les moyens de paiement susceptibles d’accroître le taux de conversion et qui sont les plus pertinents en fonction de la devise et du pays du client.

Toutes les options d’éléments supplémentaires transmises lors de la création du groupe Elements à l’étape précédente doivent également être transmises lors de la création du PaymentIntent.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-04-30.basil" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "payment_method_types[]"=card \
  -d "automatic_payment_methods[enabled]"=true \

Au lieu d’utiliser des méthodes de confirmation individuelles comme stripe.confirmCardPayment ou stripe.confirmP24Payment, utilisez stripe.confirmPayment pour collecter les informations de paiement et les soumettre à Stripe.

Pour confirmer le PaymentIntent, apportez les modifications suivantes à votre gestionnaire d’envoi :

• Appelez await elements.submit() afin de déclencher la validation du formulaire et de collecter les données requises pour les portefeuilles électroniques.
• Facultatif : déplacez la création du PaymentIntent vers le gestionnaire d’envoi. De cette façon, vous ne créez le PaymentIntent que lorsque vous connaissez le montant final.
• Transmettez l’instance elements que vous avez utilisée pour créer le Payment Element et le clientSecret du PaymentIntent en tant que paramètres à stripe.confirmPayment.

Lorsqu’il est appelé, le paramètre stripe.confirmPayment tente d’effectuer toutes les actions requises, comme l’authentification de vos clients, en affichant une boîte de dialogue 3DS ou en les redirigeant vers la page d’autorisation de leur banque. Une fois la confirmation effectuée, les utilisateurs sont redirigés vers la return_url que vous avez configurée, qui correspond généralement à une page de votre site Web indiquant l’état du paiement.

Si vous souhaitez conserver le même tunnel de paiement pour les paiements par carte et rediriger vos clients uniquement pour les moyens de paiement qui l’exigent, vous pouvez définir la redirection sur if_required.

L’exemple de code suivant remplace stripe.confirmCardPayment par stripe.confirmPayment :

// Create the PaymentIntent and obtain clientSecret
const res = await fetch("/create-intent", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
});

const {client_secret: clientSecret} = await res.json();

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: elements.getElement(CardElement)
    }
  });

  if (error) {
    handleError(error);
  }
};

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch("/create-intent", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
  });

  const {client_secret: clientSecret} = await res.json();

  // Use the clientSecret and Elements instance to confirm the setup
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
    // Uncomment below if you only want redirect for redirect-based payments
    // redirect: "if_required",
  });

  if (error) {
    handleError(error);
  }
};

Stripe envoie un événement payment_intent.succeeded à l’issue du paiement. Utilisez l’outil de webhook du Dashboard ou suivez le guide consacré aux webhooks pour recevoir ces événements et exécuter des actions, comme envoyer une confirmation de commande par e-mail à votre client, enregistrer la vente dans une base de données ou lancer un flux de livraison.

Plutôt que d’attendre un rappel de votre client, écoutez ces événements. Côté client, il arrive en effet que l’utilisateur ferme la fenêtre de son navigateur ou quitte l’application avant l’exécution du rappel. Certains clients malintentionnés peuvent d’autre part tenter de manipuler la réponse. En configurant votre intégration de manière à ce qu’elle écoute les événements asynchrones, vous pourrez accepter plusieurs types de moyens de paiement avec une seule et même intégration.

En plus de l’événement payment_intent.succeeded, nous vous recommandons de gérer ces autres événements lorsque vous encaissez des paiements à l’aide de l’Element Payment :

Consultez la section consacrée aux tests pour obtenir des informations supplémentaires sur la manière de tester votre intégration.