# Migrer vers l'Express Checkout Element

Migrer votre intégration existante avec le Payment Request Button Element vers l'Express Checkout Element.

Le [Payment Request Button Element](https://docs.stripe.com/stripe-js/elements/payment-request-button.md) permet d’accepter les paiements par carte bancaire via [Apple Pay](https://docs.stripe.com/apple-pay.md), [Google Pay](https://docs.stripe.com/google-pay.md) ou [Link](https://docs.stripe.com/payments/link.md). En migrant vers le [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md), vous pouvez accepter des paiements par carte bancaire ou via [wallet](https://docs.stripe.com/payments/wallets.md) à l’aide d’un ou plusieurs boutons, notamment [PayPal](https://docs.stripe.com/payments/paypal.md).

| Si votre intégration existante utilise                                                                                                                                        | Procédez comme suit                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| l’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) pour créer et suivre les paiements ou enregistrer les informations de carte bancaire lors du paiement | Suivez les étapes de ce guide pour utiliser le composant Express Checkout Element.                                          |
| API [Charges](https://docs.stripe.com/api/charges.md) avec tokens                                                                                                             | Migrez vers l’[API Payment Intents](https://docs.stripe.com/payments/payment-intents/migration.md#web) avant de poursuivre. |

## Activer des moyens de paiement

Activez les moyens de paiement que vous souhaitez prendre en charge dans vos [paramètres des moyens de paiement](https://dashboard.stripe.com/settings/payment_methods). Vous devez activer au moins un moyen de paiement.

Par défaut, Stripe active les cartes bancaires et autres moyens de paiement courants. Vous pouvez activer d’autres moyens de paiement pertinents pour votre entreprise et vos clients. Consultez la page [Prise en charge des moyens de paiement](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) pour en savoir plus sur la prise en charge des produits et des moyens de paiement, et notre [page tarifaire](https://stripe.com/pricing/local-payment-methods) pour prendre connaissance des frais que nous appliquons.

## Mettre à jour l'instance d'Elements [Côté client]

Ensuite, mettez à jour votre code côté client pour transmettre le mode (paiement), le montant et la devise. Ces valeurs déterminent les moyens de paiement à présenter à vos clients.

Par exemple, si vous transmettez la devise `eur` dans le `PaymentIntent` et que vous avez activé OXXO dans le Dashboard, votre client ne verra pas OXXO, car OXXO ne prend pas en charge les paiements libellés en `eur`.

Pour déterminer la liste des moyens de paiement pris en charge, 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.

#### HTML + JS

### Before

```javascript
const stripe =
    Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const elements = stripe.elements();
```

### After

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};
const elements = stripe.elements(options);
```

#### React

### Before

```jsx
 const stripePromise =
     loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

 function App() {
  return (
    <Elements stripe={stripePromise}>
      <CheckoutForm />
    </Elements>
  );
};
```

### After

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## Optional: Enregistrer les coordonnées bancaires lors du paiement

Si votre intégration existante enregistre les informations de carte bancaire lors du paiement, utilisez l’option `setup_future_usage` à la création de l’instance Elements, au lieu de les transmettre à l’étape de confirmation du paiement avec `stripe.confirmCardPayment`.

Certains moyens de paiement ne peuvent être enregistrés lors du paiement. Vous pouvez toujours activer ces [moyens de paiement](https://docs.stripe.com/payments/payment-methods/integration-options.md) pour d’autres cas d’usage, mais les clients ne les verront pas lorsqu’ils configureront des paiements ultérieurs.

#### HTML + JS

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};
const elements = stripe.elements(options);
```

#### React

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## Mettre à jour l'appel de création de votre PaymentIntent [Côté serveur]

Le `PaymentIntent` inclut les moyens de paiement présentés aux clients lors du paiement. Vous pouvez gérer les moyens de paiement depuis le [Dashboard](https://dashboard.stripe.com/settings/payment_methods). 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.

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-03-25.dahlia" \
  -d "amount"=1099 \
  -d "currency"="usd" \-d "automatic_payment_methods[enabled]"=true \
```

Si votre intégration existante prend en charge plusieurs moyens de paiement ou si vous souhaitez accepter d’autres moyens de paiement que la carte bancaire, vous pouvez [activer d’autres moyens de paiement](https://dashboard.stripe.com/settings/payment_methods) dans le Dashboard.

## Ajouter l'Express Checkout Element [Côté client]

Si vous utilisez [React Stripe.js](https://github.com/stripe/react-stripe-js), installez la version la plus récente pour utiliser l’Express Checkout Element.

Remplacez le Payment Request Button Element par l’Express Checkout Element. Les exemples ci-dessous montrent comment remplacer `PaymentRequestButtonElement` par `ExpressCheckoutElement`.

Vous n’avez plus besoin de créer d’objet `paymentRequest`. Transmettez plutôt les options lors de la création du `ExpressCheckoutElement`.

#### HTML + JS

### Before

```html
<div id="payment-request-button">
</div>
```

### After

```html
<div id="express-checkout-element">
  <!-- Mount the Express Checkout Element here -->
</div>
```

### Before

```javascript
const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1099,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});
const paymentRequestButton = elements.create('paymentRequestButton', {
  paymentRequest: paymentRequest,
});
paymentRequestButton.mount("#payment-request-button");
paymentRequest.canMakePayment().then(function(result) {
  if (result) {
    paymentRequestButton.mount('#payment-request-button');
  } else {
    document.getElementById('payment-request-button').style.display = 'none';
  }
});
```

### After

```javascript
const expressCheckoutElement = elements.create("expressCheckout", {
  emailRequired: true
});
expressCheckoutElement.mount("#express-checkout-element");
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const [paymentRequest, setPaymentRequest] = useState(null);

  useEffect(() => {
    if (stripe) {
      const pr = stripe.paymentRequest({
        country: 'US',
        currency: 'usd',
        total: {
          label: 'Demo total',
          amount: 1099,
        },
        requestPayerName: true,
        requestPayerEmail: true,
      });

      pr.canMakePayment().then(result => {
        if (result) {
          setPaymentRequest(pr);
        }
      });
    }
  }, [stripe]);

  return (
    paymentRequest && <PaymentRequestButtonElement options={{paymentRequest}} />
  );
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    emailRequired: true
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElement
        options={options}
        onConfirm={onConfirm}
      />
    </div>
  );
};
```

## Optional: Demander un token de marchand Apple&nbsp;Pay (MPAN)

L’Express Checkout Element prend en charge les tokens de marchand Apple&nbsp;Pay, que nous vous conseillons de privilégier aux tokens d’appareils pour activer les transactions initiées par le marchand (MIT), telles que les paiements récurrents, les paiements différés et les rechargements automatiques. Les tokens de marchand (MPAN) établissent une connexion entre votre entreprise et le moyen de paiement Apple&nbsp;Wallet de votre client. Ils fonctionnent donc sur plusieurs appareils et permettent de conserver les informations de paiement sur un nouvel appareil, même lorsque celles-ci sont supprimées d’un appareil perdu ou volé. Pour obtenir des informations sur l’intégration, consultez la page sur les [tokens de marchand Apple&nbsp;Pay](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=ece).

## Optional: Écouter l'événement ready

Une fois ajouté, le composant Express Checkout Element n’affichera aucun bouton pendant une brève période. Vous pouvez animer l’Element lorsque des boutons apparaissent. Pour cela, écoutez l’[événement ready](https://docs.stripe.com/js/element/events/on_ready) et examinez la valeur de `availablePaymentMethods` pour déterminer quels boutons apparaissent dans l’Express Checkout Element, le cas échéant.

#### HTML + JS

```javascript
// 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';
  }
});
```

#### React

```jsx
import React, {useState} from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';
import {onConfirm} from './confirmHandler';

const CheckoutPage = () => {
  // Optional: If you're doing custom animations, hide the Element
  const [visibility, setVisibility] = useState('hidden');
const onReady = ({availablePaymentMethods}) => {
    if (!availablePaymentMethods) {
      // No buttons will show
    } else {
      // Optional: Animate in the Element
      setVisibility('initial');
    }
  };

  return (
    <div id="checkout-page">
      <div id="express-checkout-element" style={{visibility}}>
        <ExpressCheckoutElement
          onConfirm={onConfirm}onReady={onReady}
        />
      </div>
    </div>
  );
};
```

## Optional: Styliser l'Express Checkout Element

Vous pouvez [styliser](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme) chaque bouton de moyen de paiement (par exemple, [Google Pay](https://developers.google.com/pay/api/web/guides/resources/customize) ou [Apple Pay](https://developer.apple.com/design/human-interface-guidelines/technologies/apple-pay/buttons-and-marks/)) pour afficher différents thèmes et types de moyens de paiement.

Vous pouvez également utiliser la variable `borderRadius` dans l’API [Appearance](https://docs.stripe.com/elements/appearance-api.md?platform=web#commonly-used-variables).

#### HTML + JS

### Before

```javascript
elements.create('paymentRequestButton', {
  paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'book',
      theme: 'dark',
      height: '55px',
    },
  },
});
```

### After

```javascript
const appearance = {
  variables: {
    // This controls the border-radius of the rendered Express Checkout Element.
    borderRadius: '4px',
  }
};
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  appearance,
};
// Pass the appearance object to the Elements instance.
const elements = stripe.elements(options);
elements.create('expressCheckout', {
  layout: 'auto',
  buttonType: {
    googlePay: 'book',
    applePay: 'book',
    paypal: 'buynow',
  },
  buttonTheme: {
    applePay: 'black'
  },
  buttonHeight: 55
});
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const options = {
    paymentRequest,
    style: {
      paymentRequestButton: {
        type: 'book',
        theme: 'dark',
        height: '55px',
      },
    }
  };

  return <PaymentRequestButtonElement options={options} />;
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    layout: 'auto',
    buttonType: {
      googlePay: 'book',
      applePay: 'book',
      paypal: 'buynow',
    },
    buttonTheme: {
      applePay: 'black'
    },
    buttonHeight: 55
  }

  return (
    <ExpressCheckoutElementoptions={options}
      onConfirm={onConfirm}
    />
  );
};
```

## Mettre à jour la méthode de confirmation du paiement [Côté client]

Écoutez l’événement [confirm](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) pour gérer la confirmation. Pour collecter les informations de paiement et les envoyer à Stripe, utilisez [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) au lieu des méthodes de confirmation individuelles comme `stripe.confirmCardPayment`.

Plutôt que d’utiliser un ID de PaymentMethod, `stripe.confirmPayment` utilise l’instance Elements de l’Express Checkout Element et la clé secrète du client du `PaymentIntent` créé.

Lorsqu’il est appelé, le paramètre `stripe.confirmPayment` tente d’effectuer toutes les actions requises, comme authentifier vos clients en affichant une boîte de dialogue 3DS ou en les redirigeant vers une page d’autorisation bancaire. Une fois la confirmation effectuée, les utilisateurs sont redirigés vers la [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) que vous avez configurée, c’est-à-dire une page de votre site Web indiquant l’état du paiement.

Si vous souhaitez que le tunnel de paiement par carte bancaire redirige vos clients uniquement pour les moyens de paiement qui l’exigent, vous pouvez définir la [redirection](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) sur `if_required`. Cela ne s’applique pas à l’Express Checkout Element.

L’exemple ci-dessous remplace `stripe.confirmCardPayment` par `stripe.confirmPayment`.

#### HTML + JS

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```javascript
expressCheckoutElement.on('confirm', async (event) => {
  const {error} = await stripe.confirmPayment({
    // `Elements` instance that's used to create the Express Checkout Element.
    elements,
    // `clientSecret` from the created PaymentIntent
    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) {
    // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
  } else {
    // Your customer will be redirected to your `return_url`.
  }
});
```

#### React

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const onConfirm = async () => {
    const {error} = await stripe.confirmPayment({
      // `Elements` instance that's used to create the Express Checkout Element.
      elements,
      // `clientSecret` from the created PaymentIntent
      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) {
      // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
    } else {
      // Your customer will be redirected to your `return_url`.
    }
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElementonConfirm={onConfirm}
      />
    </div>
  );
};
```

## Gérer les événements post-paiement [Côté serveur]

Stripe envoie un événement [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) à l’issue du paiement. Utilisez l’[outil de webhook du Dashboard](https://dashboard.stripe.com/webhooks) ou suivez le [guide consacré aux webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://stripe.com/payments/payment-methods-guide) 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&nbsp;:

| Événement                                                                                                                       | Description                                                                                                                                                                                                                                                                         | Action                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Envoyé lorsqu’un client effectue un paiement avec succès.                                                                                                                                                                                                                           | Envoyez au client une confirmation de commande et *traitez* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) sa commande.           |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Envoyé lorsqu’un client initie un paiement, mais qu’il ne l’a pas encore finalisé. Dans la plupart des cas, cet événement est envoyé lorsque le client initie un prélèvement bancaire. Il est suivi par un événement `payment_intent.succeeded` ou `payment_intent.payment_failed`. | Envoyez au client une confirmation de commande qui indique que son paiement est en attente. Pour des marchandises dématérialisées, vous pourrez traiter la commande sans attendre que le paiement soit effectué. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Envoyé lorsqu’un client effectue une tentative de paiement qui se solde par un échec.                                                                                                                                                                                               | Si un paiement passe de l’état `processing` à `payment_failed`, proposez au client de retenter le paiement.                                                                                                      |