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 SetupIntent.

Par défaut, Stripe active les cartes bancaires et les autres moyens de paiement courants qui peuvent vous permettre d’atteindre davantage de clients. Nous vous recommandons toutefois d’activer d’autres moyens de paiement pertinents pour votre entreprise et vos clients. Consultez la page Prise en charge des moyens de paiement pour en savoir plus sur la prise en charge des produits et des moyens de paiement, et notre page des tarifs pour prendre connaissance des frais que nous appliquons.

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

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

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
  mode: 'setup',
  currency: 'usd',
};
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.confirmSetup.

Le Payment Element vous permettant d’accepter plusieurs moyens de paiement, nous vous recommandons d’utiliser le paramètre automatic_payment_methods. Si vous choisissez de l’activer, Stripe prendra en compte la devise, les restrictions relatives aux moyens de paiement et d’autres paramètres pour déterminer la liste des moyens de paiement disponibles pour vos clients. Nous donnons la priorité aux moyens de paiement qui augmentent le taux de conversion et qui sont les plus adaptés à la devise et au lieu de résidence du client.

Ajoutez l’attribut automatic_payment_methods au endpoint sur votre serveur qui crée le SetupIntent.

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 SetupIntent.

curl https://api.stripe.com/v1/setup_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-08-27.basil" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "automatic_payment_methods[enabled]"=true

Au lieu d’utiliser des méthodes de confirmation individuelles comme stripe.confirmCardSetup ou stripe.confirmP24Setup, utilisez stripe.confirmSetup pour recueillir les informations de paiement et les soumettre à Stripe.

Pour confirmer le SetupIntent, 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 SetupIntent vers le gestionnaire d’envoi. De cette façon, vous ne créez le SetupIntent que lorsque l’utilisateur est prêt à soumettre ses informations de paiement.
• Transmettez l’instance elements que vous avez utilisée pour créer le Payment Element et le clientSecret du SetupIntent en tant que paramètres à stripe.confirmSetup.

Lorsqu’il est appelé, le paramètre stripe.confirmSetup 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 SetupIntent.

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

Les exemples de code suivants remplacent stripe.confirmCardSetup par stripe.confirmSetup :

// Create the SetupIntent 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.confirmCardSetup(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 SetupIntent 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.confirmSetup({
    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);
  }
};

Utilisez les informations de paiement et la page de redirection test pour vérifier votre intégration. Cliquez sur les onglets ci-après pour obtenir des informations sur chacun des moyens de paiement.

Tester le traitement d’un PaymentMethod enregistré de type prélèvement automatique SEPA

La confirmation du SetupIntent à l’aide d’iDEAL, de Bancontact ou de Sofort génère un PaymentMethod de type prélèvement automatique SEPA. Le prélèvement automatique SEPA est un moyen de paiement à notification différée qui passe à l’état intermédiaire processing avant de basculer quelques jours plus tard à l’état succeeded ou requires_payment_method.