Documentation React Stripe.js
Comprendre les composants React pour Stripe.js et Stripe Elements.
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 meilleur chemin d’intégration dans votre cas de figure, consultez notre documentation.
Note
Cette documentation couvre l’intégralité de l’API React Stripe.js. Si vous préférez apprendre en pratiquant, reportez-vous à notre documentation sur l’acceptation d’un paiement ou penchez-vous sur cet exemple d’intégration.
Avant de commencer
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 tel n’est pas le cas, nous vous recommandons de lire notre guide de démarrage avant de poursuivre.
Configuration
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 loadStripe
charge le script Stripe.js et initialise un objet Stripe de manière asynchrone. Transmettez la Promise
renvoyée à Elements
.
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(
); 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> ); };'pk_test_TYooMQauvdEDq54NiTphI7jx'
propriété | description |
---|---|
| required Objet Stripe ou Vous pouvez aussi transmettre |
| Facultatif Options de configuration facultatives d’Elements. Consultez les options disponibles. Pour créer des Payments Elements, vous devez inclure le Les propriétés étant immuables, vous ne pouvez pas modifier les |
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>
.
import {PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { return ( <form> <PaymentElement /> <button>Submit</button> </form> ); }; export default CheckoutForm;
propriété | description |
---|---|
| Facultatif Passe par le conteneur Element. |
| Facultatif Passe par le conteneur Element. |
| Facultatif 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. |
| Facultatif Déclenché lorsque le composant Element n’est plus actif. |
| Facultatif 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. |
| Facultatif Déclenché lorsque l’on clique sur Pour en savoir plus, consultez la documentation Stripe.js. |
| Facultatif Déclenché lorsque la touche Echap est enfoncée dans un Element. Pour en savoir plus, consultez la documentation Stripe.js. |
| Facultatif Déclenché lorsque le composant Element reçoit le focus. |
| Facultatif Déclenché lorsque le chargement de l’Element échoue. Cet événement n’est envoyé que par les Elements Pour en savoir plus, consultez la documentation Stripe.js. |
| Facultatif Déclenché lorsque l’interface utilisateur du chargeur est montée dans le DOM et prête à être affichée. Cet événement n’est envoyé que par les Elements Pour en savoir plus, consultez la documentation Stripe.js. |
| Facultatif Déclenché lorsque le composant Element est intégralement rendu et peut accepter des appels |
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 :
Composant | Utilisation |
---|---|
AddressElement | Collecte les informations d’adresse dans plus de 236 formats régionaux. Consultez la documentation sur le composant Address Element. |
AfterpayClearpayMessageElement | Affiche les messages relatifs aux versements échelonnés pour les paiements Afterpay. |
AuBankAccountElement | Collecte les informations relatives aux comptes bancaires australiens (BSB et numéro de compte) pour les paiements par prélèvement automatique BECS. |
CardCvcElement | Collecte le numéro CVC de la carte bancaire. |
CardElement | Champ flexible à ligne unique qui collecte toutes les informations nécessaires de la carte bancaire. |
CardExpiryElement | Collecte la date d’expiration de la carte bancaire. |
CardNumberElement | Collecte le numéro de carte bancaire. |
ExpressCheckoutElement | Vous 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. |
FpxBankElement | Banque du client pour les paiements FPX. |
IbanElement | Numéro de compte bancaire international (IBAN). Disponible pour les pays SEPA. |
IdealBankElement | Banque du client pour les paiements iDEAL. |
LinkAuthenticationElement | Collecte les adresses e-mail et permet aux utilisateurs de se connecter à Link. Consultez la documentation sur le composant Link Authentication Element. |
PaymentElement | Collecte les informations de paiement pour plus de 25 moyens de paiement dans le monde entier. Consultez la documentation sur le composant Payment Element. |
PaymentRequestButtonElement | Bouton 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.
Note
Notez que si vous transmettez une Promise
au fournisseur Elements et que cette Promise
n’a pas été résolue, alors useElements
renverra null
.
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.
Note
Notez que si vous transmettez une Promise
au fournisseur Elements et que cette Promise
n’a pas été résolue, alors useStripe
renverra null
.
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.
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 |
---|---|
| required 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 |
Personnalisation et stylisation
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.
Prochaines étapes
Développez une intégration avec React Stripe.js et Elements.