Migrer vers Payment Element avec l'API Checkout Sessions

Accédez à vos paramètres de 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 une session Checkout.

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.

Configurez le SDK pour qu’il utilise au minimum la version de l’API 2025-03-31.basil.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2025-03-31.basil;' as any,
});

Étant donné que Payment Element vous permet d’accepter plusieurs moyens de paiement, nous vous recommandons d’utiliser les moyens de paiement dynamiques, qui sont automatiquement activés si vous ne transmettez pas payment_method_types dans la session Checkout. Lorsque cette option est activée, pour déterminer la liste des moyens de paiement disponibles, Stripe prend en compte la devise, les restrictions liées aux moyens de paiement ainsi que d’autres paramètres. 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 de la localisation du client.

Mettez à jour votre appel de création de PaymentIntent pour créer une session Checkout à la place. Dans l’instance de la session Checkout, vous transmettrez :

• line_items : Représente les postes de la commande
• ui_mode: custom : Indique que vous utilisez des composants intégrés
• mode: payment : Indique que vous accepterez des paiements ponctuels pour la session Checkout
• return_url : Représente l’URL vers laquelle rediriger votre client une fois qu’il s’est authentifié ou a annulé son paiement sur l’application ou le site du moyen de paiement.

De plus, renvoyez le client_secret de la session Checkout côté client pour une utilisation ultérieure.

Chaque session de paiement génère un PaymentIntent lors de la confirmation. Si vous souhaitez conserver des paramètres supplémentaires de votre intégration actuelle lors de la création d’un PaymentIntent, reportez-vous aux options disponibles dans payment_intent_data.

intent = Stripe::PaymentIntent.create({
  amount: 1099,
  currency: 'usd',
  payment_method_types: ['card'],
})

session = Stripe::Checkout::Session.create({
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {name: 'T-shirt'},
        unit_amount: 1099,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'custom',
  return_url: '{{RETURN_URL}}',
})

{
  clientSecret: session.client_secret,
}.to_json

La migration vers des composants intégrés nécessite l’étape supplémentaire de collecte de l’adresse e-mail de votre client.

<input type="text" id="email" />
<div id="email-errors"></div>

const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}

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 = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

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

Pour confirmer la session Checkout, mettez à jour votre gestionnaire d’envoi afin qu’il utilise checkout.confirm plutôt que des méthodes de confirmation individuelles.

Lorsqu’il est appelé, le paramètre checkout.confirm tente d’effectuer toutes les actions requises, comme l’affichage d’une boîte de dialogue 3DS ou la redirection des utilisateurs vers la page d’autorisation de leur banque. Une fois la confirmation terminée, les clients 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 checkout.confirm :

// 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);

  const {error} = await checkout.confirm();

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

Une fois le paiement effectué, Stripe envoie un événement checkout.session.completed. Utilisez l’outil de webhook du Dashboard ou suivez le Quickstart 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.

Nous vous conseillons d’écouter ces événements plutôt que d’attendre un rappel de votre client. 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, et des tentatives de manipulation de la réponse par des clients malintentionnés ne sont par ailleurs pas à exclure. 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 intégration.

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

1. Accédez à votre page de paiement.
2. Renseignez les informations d’un moyen de paiement du tableau suivant. Pour les paiements par carte :
   • Saisissez une date d’expiration postérieure à la date du jour.
   • Saisissez un code CVC à 3 chiffres.
   • Saisissez un code postal de facturation.
3. Envoyez le paiement à Stripe.
4. Accédez au Dashboard et recherchez le paiement sur la page Transactions. Si votre paiement a abouti, il apparaîtra dans cette liste.
5. Cliquez sur votre paiement afin d’afficher plus d’informations (par exemple, les informations de facturation et la liste des articles achetés). Vous pouvez utiliser ces informations pour traiter la commande.

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