Accéder directement au contenu
Créez un compte
ou
connecter-vous
Logo de la documentation Stripe
/
Demander à l'assistant IA
Créez un compte
Connectez-vous
Démarrer
Paiements
Revenus
Plateformes et places de marché
Gestion de fonds
Ressources pour les développeurs
Aperçu
Gestion des versions
Journal des modifications
Mettre à niveau votre version de l'API
Actualiser votre version du SDK
Essentials
SDK
    Présentation
    SDK côté serveur
    SDK mobiles
    SDK iOS
    SDK Android
    SDK React Native
    SDK Web
    Module ES Stripe.js
    React Stripe.js
    SDK pour Terminal
    SDK iOS
    SDK Android
    SDK React Native
    Communauté
    SDK de la communauté
    Migrations mobiles
    Migrer vers le SDK iOS 24
    Migrer vers le SDK Android 21
API
Tests
CLI Stripe
Exemples de projets
Outils
Workbench
Dashboard des développeurs
Shell Stripe
Stripe pour Visual Studio Code
Fonctionnalités
Workflows
Destinations d'événements
Alertes d'intégrité de StripeChargements de fichiers
Solutions d'IA
Boîte à outils des agents
Modèle de protocole contextuel
Sécurité et confidentialité
Sécurité
Stripebot web crawler
Confidentialité
Extensions Stripe
Créer des applications Stripe
Utiliser les applications de Stripe
Partenaires
Partner ecosystem
Certification des partenaires
AccueilRessources pour les développeursSDKs

Documentation React Stripe.js

Comprendre les composants React pour Stripe.js et Stripe Elements.

Voir le code

Vous souhaitez découvrir le fonctionnement de React Stripe.js ou contribuer à son développement, consultez notre projet sur GitHub.

React Stripe.js est un wrapper léger pour Stripe Elements qui vous permet d’ajouter Elements à n’importe quelle application React.

La documentation de Stripe.js fournit toutes les informations utiles pour la personnalisation d’Elements.

Vous pouvez utiliser Elements avec n’importe quel produit Stripe pour encaisser des paiements en ligne. Pour trouver le chemin d’intégration adapté à votre entreprise, consultez notre documentation.

Remarque

Cette documentation couvre l’intégralité de l’API React Stripe.js. Si vous préférez apprendre sur le tas, reportez-vous à notre documentation sur l’acceptation d’un paiement ou penchez-vous sur cet exemple d’intégration.

Avant de commencer

Dans cette documentation, nous partons du principe que vous disposez de connaissances de base suffisantes sur le fonctionnement de React et que vous avez déjà configuré un projet React. Si vous êtes novice en la matière, nous vous recommandons de lire le guide de démarrage avant de poursuivre.

Configuration

Installez React Stripe.js et le chargeur Stripe.js à partir du registre public npm.

Command Line
npm install --save @stripe/react-stripe-js @stripe/stripe-js

Fournisseur Elements

Le fournisseur Elements vous permet d’utiliser les composants Element et d’accéder à l’objet Stripe dans n’importe quel composant imbriqué. Générez un rendu d’un fournisseur Elements à la racine de votre application React afin qu’il soit disponible partout où vous en avez besoin.

Pour utiliser le fournisseur Elements, appelez loadStripe depuis @stripe/stripe-js avec votre clé publique. La fonction loadStripecharge le script Stripe.js et initialise un objet Stripe de manière asynchrone. Transmettez la Promise renvoyée à Elements.

index.jsx
import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; // Make sure to call `loadStripe` outside of a component’s render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
); export default function App() { const options = { // passing the client secret obtained from the server clientSecret: '{{CLIENT_SECRET}}', }; return ( <Elements stripe={stripePromise} options={options}> <CheckoutForm /> </Elements> ); };
propriétédescription

stripe

required Stripe | null | Promise<Stripe | null>

Objet Stripe ou Promise se résolvant en un objet Stripe. Le moyen le plus simple d’initialiser un objet Stripe est d’utiliser le module wrapper Stripe.js. Une fois que vous avez défini cette propriété, vous ne pouvez plus la modifier.

Vous pouvez aussi transmettre null ou une Promise se résolvant en null si vous effectuez un rendu initial côté serveur ou si vous générez un site statique.

options

Facultatif Object

Options de configuration facultatives d’Elements. Consultez les options disponibles. Pour créer des Payments Elements, vous devez inclure le clientSecret de l’Intent, à moins que vous n’affichiez l’Element avant de créer l’Intent.

Les propriétés étant immuables, vous ne pouvez pas modifier les options après les avoir définies. Cependant, vous pouvez modifier l’apparence d’un élément en appelant la méthode elements.update.

Composants Element

Les composants Element offrent un moyen flexible de collecter de manière sécurisée les informations de paiement dans votre application React.

Vous pouvez monter des composants Element individuels dans votre arbre Elements. Veuillez noter que vous ne pouvez monter qu’un seul composant Element de chaque type dans un même groupe <Elements>.

CheckoutForm.jsx
import {PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { return ( <form> <PaymentElement /> <button>Submit</button> </form> ); }; export default CheckoutForm;
propriétédescription

id

Facultatif string

Passe par le conteneur Element.

className

Facultatif string

Passe par le conteneur Element.

options

Facultatif Object

Objet contenant les options de configuration du composant Element. Prenez connaissance des options disponibles pour le composant Element Payment ou celles disponibles pour les composants Element de moyen de paiement individuels.

onBlur

Facultatif () => void

Déclenché lorsque le composant Element n’est plus actif.

onChange

Facultatif (event: Object) => void

Déclenché lorsque les données exposées par cet Element sont modifiées (par exemple, lorsqu’il y a une erreur).

Pour en savoir plus, consultez la documentation de Stripe.js.

onClick

Facultatif (event: Object) => void

Déclenché lorsque l’on clique sur <PaymentRequestButtonElement>.

Pour en savoir plus, consultez la documentation Stripe.js.

onEscape

Facultatif (event: Object) => void

Déclenché lorsque la touche Echap est enfoncée dans un Element.

Pour en savoir plus, consultez la documentation Stripe.js.

onFocus

Facultatif () => void

Déclenché lorsque le composant Element reçoit le focus.

onLoaderror

Facultatif (event: Object) => void

Déclenché lorsque le chargement de l’Element échoue.

Ces événements vous sont envoyés uniquement par les composants Elements payment, linkAuthentication, address et expressCheckout.

Pour en savoir plus, consultez la documentation Stripe.js.

onLoaderStart

Facultatif (event: Object) => void

Déclenché lorsque l’interface utilisateur du chargeur est montée dans le DOM et prête à être affichée.

Ces événements vous sont envoyés uniquement par les composants Elements payment, linkAuthentication et address.

Pour en savoir plus, consultez la documentation Stripe.js.

onReady

Facultatif (element: Element) => void

Déclenché lorsque le composant Element est intégralement rendu et peut accepter des appels element.focus() impératifs. Appelé avec une référence à l’instance Element sous-jacente.

Composants Element disponibles

Il existe de nombreux types de composants Element, très utiles pour collecter différentes sortes d’informations de paiement. Les composants Elements disponibles à l’heure actuelle sont les suivants :

ComposantUtilisation
AddressElementCollecte les informations d’adresse dans plus de 236 formats régionaux. Consultez la documentation sur le composant Address Element.
AfterpayClearpayMessageElementAffiche les messages relatifs aux versements échelonnés pour les paiements Afterpay.
AuBankAccountElementCollecte les informations relatives aux comptes bancaires australiens (BSB et numéro de compte) pour les paiements par prélèvement automatique BECS.
CardCvcElementCollecte le numéro CVC de la carte bancaire.
CardElementChamp flexible à ligne unique qui collecte toutes les informations nécessaires de la carte bancaire.
CardExpiryElementCollecte la date d’expiration de la carte bancaire.
CardNumberElementCollecte le numéro de carte bancaire.
ExpressCheckoutElementVous permet d’accepter des paiements par carte ou par portefeuille via un ou plusieurs boutons de paiement, notamment Apple Pay, Google Pay, Link ou PayPal. Consultez la documentation sur le composant Express Checkout Element.
FpxBankElementBanque du client pour les paiements FPX.
IbanElementNuméro de compte bancaire international (IBAN). Disponible pour les pays SEPA.
IdealBankElementBanque du client pour les paiements iDEAL.
LinkAuthenticationElementCollecte les adresses e-mail et permet aux utilisateurs de se connecter à Link. Consultez la documentation sur le composant Link Authentication Element.
PaymentElementCollecte les informations de paiement pour plus de 25 moyens de paiement dans le monde entier. Consultez la documentation sur le composant Payment Element.
PaymentRequestButtonElementBouton de paiement tout-en-un adossé à Apple Pay ou à l’API Payment Request. Pour en savoir plus, consultez la documentation sur le Payment Request Button.

hook useElements

useElements(): Elements | null

Pour transmettre en toute sécurité les informations de paiement collectées par le composant Payment Element à l’API Stripe, accédez à l’instance Elements afin de pouvoir l’utiliser avec stripe.confirmPayment. Si vous utilisez l’API React Hooks, nous vous recommandons d’utiliser useElements pour accéder à un composant Element monté. Si vous avez besoin d’accéder à un composant Element depuis un composant de classe, utilisez en revanche ElementsConsumer.

Remarque

Notez que si vous transmettez une Promise au fournisseur Elements et que cette Promise n’a pas été résolue, alors useElements renverra null.

CheckoutForm.jsx
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.error) { // Show error to your customer (for example, payment details incomplete) console.log(result.error.message); } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } }; return ( <form onSubmit={handleSubmit}> <PaymentElement /> <button disabled={!stripe}>Submit</button> </form> ) }; export default CheckoutForm;

hook useStripe

useStripe(): Stripe | null

Le hook useStripe renvoie une référence à l’instance Stripe transmise au fournisseur Elements. Si vous avez besoin d’accéder à l’objet Stripe d’un composant de classe, utilisez plutôt ElementsConsumer.

Remarque

Notez que si vous transmettez une Promise au fournisseur Elements et que cette Promise n’a pas été résolue, alors useStripe renverra null.

CheckoutForm.jsx
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.error) { // Show error to your customer (for example, payment details incomplete) console.log(result.error.message); } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } }; return ( <form onSubmit={handleSubmit}> <PaymentElement /> <button disabled={!stripe}>Submit</button> </form> ) }; export default CheckoutForm;

ElementsConsumer

Pour transmettre en toute sécurité les informations de paiement collectées par le Payment Element à l’API Stripe, accédez à l’instance Elements afin de pouvoir l’utiliser avec stripe.confirmPayment. Si vous avez besoin d’accéder à l’objet Stripe ou à un composant Element depuis un composant de classe, ElementsConsumer constitue une alternative aux hooks useElements et useStripe.

CheckoutForm.jsx
import {ElementsConsumer, PaymentElement} from '@stripe/react-stripe-js'; class CheckoutForm extends React.Component { handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); const {stripe, elements} = this.props; if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.error) { // Show error to your customer (for example, payment details incomplete) console.log(result.error.message); } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } }; render() { return ( <form onSubmit={this.handleSubmit}> <PaymentElement /> <button disabled={!this.props.stripe}>Submit</button> </form> ); } } export default function InjectedCheckoutForm() { return ( <ElementsConsumer> {({stripe, elements}) => ( <CheckoutForm stripe={stripe} elements={elements} /> )} </ElementsConsumer> ) }
propriétédescription

children

required ({elements, stripe}) => ReactNode

Ce composant prend une fonction en tant qu’enfant. La fonction que vous fournissez sera appelée avec l’objet Elements, qui gère vos composants Element et l’objet Stripe que vous avez transmis à <Elements>.

Notez que si vous transmettez une Promise au fournisseur Elements et que cette Promise n’a pas été résolue, alors stripe et elements renverront null.

Personnalisation et stylisation

Pourquoi utiliser des iframes ?

Nous sommes conscients que l’utilisation d’iframes complique la stylisation des composants Element. Ils vous permettent néanmoins de vous décharger de la responsabilité du traitement sécurisé des données de paiement et simplifient la conformité de votre site à la réglementation en vigueur.

Chaque Element est monté dans un iframe, raison pour laquelle les Elements ne fonctionnent généralement pas avec vos frameworks de stylisation et de composants existants. Cela dit, vous pouvez toujours configurer vos Elements pour qu’ils s’intègrent au design de votre site. La personnalisation d’Elements implique de répondre aux événements et de configurer les Elements avec l’option appearance. La mise en page de chaque Element reste la même, mais vous pouvez modifier les couleurs, les polices, les bordures, les marges, etc.

Pays du client
Taille
Thème
Disposition
Cette démo affiche uniquement Google Pay ou Apple Pay si vous disposez d'une carte active sur l'un de ces portefeuilles.

Prochaines étapes

Développez une intégration avec React Stripe.js et Elements.

  • Accepter un paiement
  • Accepter un paiement avec le composant Express Checkout Element
  • Ajouter le bouton de demande de paiement
  • En savoir plus sur l’API Elements Appearance
  • Documentation Stripe.js
Cette page vous a-t-elle été utile ?
OuiNon
  • Besoin d'aide ? Contactez le service Support.
  • Rejoignez notre programme d'accès anticipé.
  • Consultez notre log des modifications.
  • Des questions ? Contactez l'équipe commerciale.
  • LLM ? Lire llms.txt.
  • Propulsé par Markdoc