Accepter un paiement avec Express Checkout Element

Utilisez une seule intégration pour accepter les paiements par le biais de boutons de paiement en un clic.

Le composant Express Checkout Element est une intégration permettant d’accepter des paiements par le biais de boutons de moyens de paiement en un clic. Les moyens de paiement pris en charge sont les suivants : Link, Apple Pay, Google Pay, PayPal, Klarna, et Amazon Pay.

Les clients voient différents boutons de paiement en fonction de leur appareil et de leur navigateur. Les appareils compatibles prennent automatiquement en charge Google Pay et Link. Vous devez effectuer des étapes supplémentaires pour prendre en charge Apple Pay et PayPal.

Essayer la démonstration

Basculez les options préconfigurées dans la démo pour modifier la couleur d’arrière-plan, la mise en page, la taille et la collecte des adresses de livraison. La démo affiche Google Pay et Apple Pay uniquement sur les plateformes où ils sont disponibles. Les boutons de moyens de paiement ne s’affichent que dans les pays où ils sont pris en charge.

Si vous ne voyez pas la démo, essayez de visualiser cette page dans un navigateur pris en charge.

Option	Description
Pays du marchand	Définissez cette option avec la clé publiable que vous utilisez pour initialiser Stripe.js. Pour modifier le pays, vous devez démonter l’Express Checkout Element, mettre à jour la clé publiable, puis remonter l’Express Checkout Element.
Couleur d’arrière-plan	Définissez les couleurs à l’aide de l’API Elements Appearance. Les thèmes des boutons sont hérités de l’API Appearance, mais vous pouvez aussi les définir directement lors de la création de l’Element.
Taille ordinateur de bureau et mobile	Utilisez la liste déroulante pour définir la largeur maximale en pixels de l’élément parent sur lequel l’Express Checkout Element est monté. Vous pouvez la définir sur 750 px (ordinateur de bureau) ou 320 px (mobile).
Max. de colonnes et max. de lignes	Définissez ces valeurs à l’aide du paramètre layout lorsque vous créez le composant Express Checkout Element.
Menu de débordement	Définissez cette option à l’aide du paramètre layout lorsque vous créez l’Express Checkout Element.
Collecter une adresse de livraison	Pour collecter les informations de livraison, vous devez transmettre les options lors de la création de l’Express Checkout Element. En savoir plus sur la collecte des informations des clients et l’affichage des postes de facture.

Nous vous recommandons de collecter les informations de paiement avant de créer un Intent lorsque vous utilisez le composant Express Checkout Element. Si vous avez déjà effectué une intégration avec le composant Payment Element, vous devrez peut-être mettre à jour votre intégration.

Avant de commencer

Ajoutez un moyen de paiement à votre navigateur. Par exemple, vous pouvez ajouter une carte à votre compte Google Pay ou à Cartes pour Safari.
Fournir votre application via HTTPS. Cette exigence s’applique à la fois en développement et en production. Vous pouvez également utiliser un service comme ngrok.
Enregistrez votre domaine en modes environnement de test et production.

Configurer Stripe
Côté serveur

Tout d’abord, créez un compte Stripe ou connectez-vous.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

Activer des moyens de paiement

Par défaut, Stripe utilise vos paramètres des moyens de paiement pour déterminer quels moyens de paiement sont activés dans le composant Express Checkout Element.

Pour modifier manuellement les moyens de paiement activés, dressez la liste de ceux que vous souhaitez activer à l’aide de l’attribut payment_method_types.

Si vous collectez des paiements avant de créer un intent, répertoriez les moyens de paiement dans l’attribut paymentMethodTypes de vos options Elements provider.
Si vous créez un intent avant d’afficher des composants Elements, répertoriez les moyens de paiement dans l’attribut payment_method_types de votre intent.

Moyens de paiement pris en charge

Apple Pay et Google Pay sont automatiquement activés lorsque vous utilisez le type de moyen de paiement card. Lors de l’utilisation de Link, vous devez également transmettre le type de moyen de paiement card.

Nom du moyen de paiement	Paramètres de l’API Payment Method
Apple Pay	`card`
Google Pay	`card`
Lien	`link, card`
PayPal	`paypal`
Amazon Pay	`amazon_pay`
Klarna	`klarna`

Configurer Stripe Elements
Côté client

L’Express Checkout Element est automatiquement disponible en tant que fonctionnalité de Stripe.js. Incluez le script Stripe.js en l’ajoutant entre les balises head de votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans un lot, ni en héberger de copie.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Créez une instance de Stripe avec le code JavaScript suivant sur votre page de paiement :

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Créez ensuite une instance d’Elements avec un mode (paiement, configuration ou abonnement), un montant et une devise. Ces valeurs déterminent les moyens de paiement qui seront présentés à votre client. Reportez-vous à l’étape suivante pour découvrir davantage d’options d’Elements.

checkout.js
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  // Customizable by using the Appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form.
const elements = stripe.elements(options);

FacultatifOptions d'éléments supplémentaires
Côté client

L’objet Elements accepte des options supplémentaires qui ont une incidence sur l’encaissement des paiements. En fonction des options proposées, l’Express Checkout Element affiche les moyens de paiement disponibles parmi ceux que vous avez activés. En savoir plus sur la prise en charge des moyens de paiement.

Propriété	Type	Description	Obligatoire
`mode`	`payment` `setup` `subscription`	Indique si l’Express Checkout Element est utilisé avec un PaymentIntent, un SetupIntent ou un abonnement.	Oui
`currency`	`string`	La devise du montant à facturer au client.	Oui
`amount`	`number`	Le montant à débiter au client, indiqué dans les interfaces utilisateur Apple Pay, Google Pay ou BNPL.	Pour les modes `payment` et `subscription`
`setupFutureUsage`	`off_session` `on_session`	Indique que vous avez l’intention d’effectuer des paiements ultérieurs avec les informations de paiement collectées par l’Express Checkout Element. Non pris en charge pour Klarna utilisant l’Express Checkout Element.	Non
`captureMethod`	`automatic` `automatic_async` `manual`	Détermine à quel moment capturer les fonds sur le compte du client.	Non
`onBehalfOf`	`string`	Connect uniquement. L’ID de compte Stripe qui correspond à l’entreprise de référence. Consultez les cas d’usage pour déterminer si cette option est pertinente pour votre intégration.	Non
`paymentMethodTypes`	`string[]`	Liste des types de moyens de paiement à afficher. Vous pouvez omettre cet attribut pour gérer vos moyens de paiement dans le Dashboard Stripe.	Non
`paymentMethodConfiguration`	`string`	La configuration des moyens de paiement à utiliser lors de la gestion de vos moyens de paiement dans le Dashboard Stripe. Si aucune configuration n’est spécifiée, votre configuration par défaut sera utilisée.	Non
`paymentMethodCreation`	`manual`	Autorise la création d’objets PaymentMethod à partir de l’instance Elements à l’aide de stripe.createPaymentMethod.	Non
`paymentMethodOptions`	`{us_bank_account: {verification_method: string}}`	Options de vérification pour le moyen de paiement `us_bank_account`. Accepte les mêmes méthodes de vérification que les Payment Intents.	Non
`paymentMethodOptions`	`{card: {installments: {enabled: boolean}}}`	Permet d’activer manuellement l’interface utilisateur de sélection du calendrier de versements échelonnés par carte, le cas échéant, lorsque vous ne gérez pas vos moyens de paiement dans le Dashboard Stripe. Vous devez définir `mode='payment'` et spécifier explicitement des `paymentMethodTypes`. Dans le cas contraire, une erreur est générée. Non compatible avec `paymentMethodCreation='manual'`.	Non

Créer et intégrer l'Express Checkout Element
Côté client

L’Express Checkout Element contient une balise iframe qui envoie les informations de paiement à Stripe de manière sécurisée via une connexion HTTPS. Pour que votre intégration fonctionne, l’adresse de la page de paiement doit également commencer par https:// et non http://.

L’Express Checkout Element doit avoir un emplacement dédié dans votre page de paiement. Créez un nœud DOM (conteneur) vide avec un ID unique dans votre formulaire de paiement.

checkout.html
<div id="express-checkout-element">
  <!-- Express Checkout Element will be inserted here -->
</div>
<div id="error-message">
  <!-- Display an error message to your customers here -->
</div>

Une fois le formulaire chargé, créez une instance de l’Express Checkout Element et intégrez-la au nœud DOM du conteneur :

checkout.js
// Create and mount the Express Checkout Element
const expressCheckoutElement = elements.create('expressCheckout');
expressCheckoutElement.mount('#express-checkout-element');

Collecter les informations des clients et afficher des postes de facture
Côté client

Transmettez les options lors de la création de l’Express Checkout Element.

Collecter les informations du payeur

Définissez emailRequired: true pour collecter les e-mails, et phoneNumberRequired: true pour collecter les numéros de téléphone.

La valeur billingAddressRequired par défaut dépend de votre intégration :

Si vous transmettez allowedShippingCountries, phoneNumberRequired, shippingAddressRequired, emailRequired, applePay, lineItems, or business lors de la création du composant Element Express, la valeur billingAddressRequired est définie sur false par défaut.
Sinon, la valeur billingAddressRequired est définie sur true par défaut.

checkout.js
elements.create('expressCheckout', {
  emailRequired: true,
  phoneNumberRequired: true
});

Informations client PayPal

PayPal ne fournit généralement pas l’adresse de facturation du client (sauf le pays) ni son numéro de téléphone. Si ces informations ne sont pas fournies, l’événement de confirmation présente des chaînes vides pour ces propriétés. Si vous avez besoin de l’adresse de facturation ou du numéro de téléphone du client, le composant Express Checkout Element n’affiche pas le bouton PayPal, sauf si cette information est disponible.

Collecter les informations de livraison

Définissez shippingAddressRequired: true et transmettez un tableau de shippingRates.

checkout.js
elements.create('expressCheckout', {
  shippingAddressRequired: true,
  allowedShippingCountries: ['US'],
  shippingRates: [
    {
      id: 'free-shipping',
      displayName: 'Free shipping',
      amount: 0,
      deliveryEstimate: {
        maximum: {unit: 'day', value: 7},
        minimum: {unit: 'day', value: 5}
      }
    },
  ]
});

Écoutez l’événement shippingaddresschange pour détecter lorsqu’un client sélectionne une adresse de livraison. Vous devez appeler resolve ou reject si vous choisissez de gérer cet événement.

Remarque

Pour préserver la confidentialité, les navigateurs peuvent anonymiser l’adresse de livraison en supprimant les informations sensibles qui ne sont pas nécessaires pour calculer les frais d’expédition. Selon le pays, certains champs peuvent être manquants ou partiellement expurgés. Par exemple, l’adresse de livraison aux États-Unis ne peut contenir qu’une ville, un État et un code postal. L’adresse de livraison complète apparaît dans l’objet événement de confirmation une fois l’achat confirmé dans l’interface de paiement du navigateur.

checkout.js
expressCheckoutElement.on('shippingaddresschange', async (event) => {
  const response = await fetch('/calculate-shipping', {
    data: JSON.stringify({
      shippingAddress: event.address
    })
  });
  const result = await response.json();
  event.resolve({
    lineItems: result.updatedLineItems,
  });
});

Écoutez l’événement shippingratechange pour détecter lorsqu’un client sélectionne un tarif de livraison. Vous devez appeler resolve ou reject si vous choisissez de gérer cet événement.

checkout.js
expressCheckoutElement.on('shippingratechange', async (event) => {
  const response = await fetch('/calculate-and-update-amount', {
    data: JSON.stringify({
      shippingRate: event.shippingRate
    })
  });
  const result = await response.json();
  elements.update({amount: result.amount})
  event.resolve({
    lineItems: result.updatedLineItems,
  });
});

Écoutez l’événement cancel pour détecter si un client quitte l’interface de paiement. Réinitialisez le montant au montant initial.

checkout.js
expressCheckoutElement.on('cancel', () => {
  elements.update({amount: 1099})
});

Afficher les postes de facture

Transmettez un tableau de lineItems :

checkout.js
elements.create('expressCheckout', {
  lineItems: [
    {
      name: 'Sample item',
      amount: 1000
    },
    {
      name: 'Tax',
      amount: 100
    },
    {
      name: 'Shipping cost',
      amount: 1000
    }
  ]
});

Configurer l'interface Apple Pay

Découvrez comment configurer l’interface Apple Pay.

Transactions initiées par le marchand (MIT)

Vous pouvez configurer les paiements récurrents, les paiements différés ou les paiements par rechargement automatique lorsqu’un utilisateur effectue un paiement avec Apple Pay en demandant le type de token de marchand concerné dans l’événement click d’Express Checkout Element. Nous vous recommandons d’implémenter les tokens de marchand Apple Pay pour vous aligner sur les dernières directives d’Apple Pay et pour pérenniser votre intégration.

FacultatifÉcouter l'événement ready
Côté client

Une fois ajouté, le composant Express Checkout Element n’affichera pas les boutons pendant une brève période. Pour animer l’Element lorsque les boutons apparaissent, écoutez l’événement ready. Examinez la valeur availablePaymentMethods pour déterminer quels boutons s’affichent dans l’Express Checkout Element, le cas échéant.

checkout.js
// Optional: If you're doing custom animations, hide the Element
const expressCheckoutDiv = document.getElementById('express-checkout-element');
expressCheckoutDiv.style.visibility = 'hidden';

expressCheckoutElement.on('ready', ({availablePaymentMethods}) => {
  if (!availablePaymentMethods) {
    // No buttons will show
  } else {
    // Optional: Animate in the Element
    expressCheckoutDiv.style.visibility = 'initial';
  }
});

FacultatifContrôle de l'affichage des boutons de paiement
Côté client

Vous pouvez gérer les moyens de paiement qui apparaissent dans le composant Express Checkout Element de plusieurs manières :

Dans les paramètres des moyens de paiement du Dashboard Stripe.
En utilisant la propriété paymentMethods pour désactiver les boutons de paiement. L’utilisation de cette propriété vous permet de mieux contrôler ce que voient vos clients.

Le composant Express Checkout Element affiche Apple Pay ou Google Pay lorsque le client se trouve sur une plateforme prise en charge et qu’il dispose d’une carte active. Si vous souhaitez toujours afficher Apple Pay et Google Pay même lorsque le client n’a pas de carte active, vous pouvez également configurer cette fonction avec paymentMethods.

FacultatifStyliser le bouton
Côté client

Vous pouvez styliser chaque bouton de moyen de paiement différemment. Pour des exemples de thèmes et de types de boutons, consultez les ressources de Google et d’Apple. Vous pouvez également utiliser la variable borderRadius dans l’API Appearance :

checkout.js
const appearance = {
  variables: {
    // This controls the border-radius of the rendered Express Checkout Element
    borderRadius: '4px',
  }
};

// Pass the appearance object to the Elements instance
const elements = stripe.elements({clientSecret, appearance});

elements.create('expressCheckout', {
  // Specify a type per payment method
  // Defaults to 'buy' for Google, 'plain' for Apple, and 'paypal' for PayPal
  buttonType: {
    googlePay: 'checkout',
    applePay: 'check-out',
    paypal: 'buynow',
  },
  // Specify a theme per payment method
  // Default theme is based on appearance API settings
  buttonTheme: {
    applePay: 'white-outline'
  },
  // Height in pixels. Defaults to 44. The width is always '100%'.
  buttonHeight: 55
});

FacultatifCréer un ConfirmationToken
Côté client

Lorsque le client autorise un paiement, vous pouvez créer un ConfirmationToken à envoyer à votre serveur afin de lancer un processus de validation supplémentaire ou de logique métier avant confirmation. Vous devez immédiatement utiliser le ConfirmationToken créé pour confirmer un PaymentIntent ou un SetupIntent.

checkout-confirmation.js
const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
}

expressCheckoutElement.on('confirm', async (event) => {
  ...

  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create a ConfirmationToken using the details collected by the Express Checkout Element
  const {error, confirmationToken} = await stripe.createConfirmationToken({
    elements,
    params: {
      payment_method_data: {
        billing_details: {
          name: 'Jenny Rosen',
        }
      },
      return_url: 'https://example.com/order/123/complete'
    }
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
    return;
  }

  // Send the ConfirmationToken ID to your server for additional logic and attach the ConfirmationToken
  const res = await fetch('/create-intent', {
    method: 'POST',
    body: confirmationToken.id
  });
  const {client_secret: clientSecret} = await res.json();

  // Confirm the PaymentIntent
  const {error: confirmError} = await stripe.confirmPayment({
    clientSecret,
    confirmParams: {
      confirmation_token: confirmationToken.id
    },
  });

  if (confirmError) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(confirmError);
  } else {
    // The payment UI automatically closes with a success animation.
    // Your customer is redirected to your `return_url`.
  }
});

Créer un PaymentIntent
Côté serveur

Pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent, qui suit les tentatives de débit et les changements d’état du paiement tout au long du processus.

Créez un PaymentIntent sur votre serveur avec un montant et une devise. Ces informations doivent correspondre à celles définies sur l’instance stripe.elements à l’étape 3. Décidez toujours du montant à débiter côté serveur, un environnement sécurisé, plutôt que côté client. Cela empêchera les clients malintentionnés de fixer leurs propres tarifs.

Le PaymentIntent renvoyé inclut une clé secrète à utiliser côté client pour mener à bien le processus de paiement en toute sécurité, plutôt que de transmettre l’objet PaymentIntent dans son intégralité. Vous pouvez utiliser différentes approches pour transmettre cette clé secrète côté client.

Envoyer le paiement à Stripe
Côté client

Utilisez stripe.confirmPayment pour finaliser le paiement à l’aide des informations de l’Express Checkout Element.

Remarque

Pour Amazon Pay, Klarna et PayPal, le montant que vous confirmez dans le PaymentIntent doit correspondre au montant que l’acheteur a préautorisé. Si les montants ne correspondent pas, le paiement est refusé.

Fournissez une return_url à cette fonction pour indiquer où Stripe doit rediriger l’utilisateur une fois le paiement effectué. Votre utilisateur peut être redirigé vers un site intermédiaire avant d’être redirigé vers la return_url. Payments redirige immédiatement l’utilisateur vers la return_url lorsqu’un paiement aboutit.

Si vous ne souhaitez pas effectuer de redirection une fois le paiement effectué, vous pouvez définir la redirection sur if_required. De cette manière, seuls les clients qui choisissent un moyen de paiement avec redirection seront redirigés.

checkout.js
const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
}

expressCheckoutElement.on('confirm', async (event) => {
  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',
  });
  const {client_secret: clientSecret} = await res.json();

  const {error} = await stripe.confirmPayment({
    // `elements` instance used to create the Express Checkout Element
    elements,
    // `clientSecret` from the created PaymentIntent
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
  } else {
    // The payment UI automatically closes with a success animation.
    // Your customer is redirected to your `return_url`.
  }
});

Tester l'intégration

Avant de passer en mode production, testez l’intégration de chaque moyen de paiement. Pour déterminer la compatibilité d’un moyen de paiement avec un navigateur, consultez les navigateurs pris en charge. Si vous utilisez Express Checkout Element dans un iframe, l’attribut allow de cet iframe doit être défini sur payment *.

Mise en garde

Ne stockez pas de données utilisateur réelles dans des comptes Link du bac à sable. Traitez-les comme des données publiques, car ces comptes de test sont associés à votre clé publiable.

À l’heure actuelle, Link fonctionne uniquement pour les cartes de crédit, les cartes de débit et les achats admissibles effectués via un compte bancaire américain. Link nécessite un enregistrement de domaine.

Vous pouvez créer des comptes dans un environnement de test pour Link à l’aide d’une adresse e-mail valide. Le tableau suivant répertorie les codes à usage unique acceptés par Stripe pour l’authentification des comptes en mode test :

Valeur	Résultat
Tout autre ensemble de 6 chiffres non listé ci-dessous	Opération réussie
000001	Erreur, code non valide
000002	Erreur, code expiré
000003	Erreur, nombre maximal de tentatives dépassé

FacultatifUtilisez l'Express Checkout Element avec Stripe Connect

Les plateformes Connect qui créent des paiements directs ou ajoutent le token à un objet Customer sur le compte connecté doivent effectuer des actions supplémentaires.

Sur votre front-end, avant de créer le composant ExpressCheckoutElement, définissez l’option stripeAccount sur l’instance Stripe :

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  apiVersion: "2025-11-17.clover",
  stripeAccount: '{{CONNECTED_ACCOUNT_ID}}'
,
});

Enregistrez tous les domaines sur lesquels vous prévoyez d’afficher le composant Express Checkout Element.

Divulguer Stripe à vos clients

Stripe recueille des informations sur les interactions des clients avec Elements afin de vous fournir des services, de prévenir la fraude et d’améliorer ses services. Cela inclut l’utilisation de cookies et d’adresses IP pour identifier les Elements qu’un client a vus au cours d’une même session Checkout. Vous êtes responsable de la divulgation et de l’obtention de tous les droits et consentements nécessaires pour que Stripe puisse utiliser les données à cette fin. Pour en savoir plus, visitez notre Centre de confidentialité.

Accepter un paiement avec Express Checkout Element

Utilisez une seule intégration pour accepter les paiements par le biais de boutons de paiement en un clic.

Essayer la démonstration

Avant de commencer

Configurer StripeCôté serveur

Activer des moyens de paiement

Moyens de paiement pris en charge

Configurer Stripe ElementsCôté client

FacultatifOptions d'éléments supplémentairesCôté client

Créer et intégrer l'Express Checkout ElementCôté client

Collecter les informations des clients et afficher des postes de factureCôté client

Collecter les informations du payeur

Informations client PayPal

Collecter les informations de livraison

Remarque

Afficher les postes de facture

Configurer l'interface Apple Pay

Transactions initiées par le marchand (MIT)

FacultatifÉcouter l'événement readyCôté client

FacultatifContrôle de l'affichage des boutons de paiementCôté client

FacultatifStyliser le boutonCôté client

FacultatifCréer un ConfirmationTokenCôté client

Créer un PaymentIntentCôté serveur

Envoyer le paiement à StripeCôté client

Remarque

Tester l'intégration

Mise en garde

FacultatifUtilisez l'Express Checkout Element avec Stripe Connect

Divulguer Stripe à vos clients

Voir aussi

Configurer Stripe
Côté serveur

Configurer Stripe Elements
Côté client

FacultatifOptions d'éléments supplémentaires
Côté client

Créer et intégrer l'Express Checkout Element
Côté client

Collecter les informations des clients et afficher des postes de facture
Côté client

FacultatifÉcouter l'événement ready
Côté client

FacultatifContrôle de l'affichage des boutons de paiement
Côté client

FacultatifStyliser le bouton
Côté client

FacultatifCréer un ConfirmationToken
Côté client

Créer un PaymentIntent
Côté serveur

Envoyer le paiement à Stripe
Côté client