# Modifier les informations de paiement Découvrez comment mettre à jour le moyen de paiement à utiliser pour les prochaines factures. Suivez les étapes ci-dessous pour créer une page Checkout qui recueille les informations de paiement de votre client et renvoie un objet Payment Method. Ensuite, utilisez l’API Stripe REST pour mettre à jour le moyen de paiement utilisé en vue de prochaines *factures* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice). > Ce guide utilise Checkout pour la mise à jour des moyens de paiement des abonnements, mais vous pouvez aussi implémenter le [portail client Billing](https://docs.stripe.com/customer-management.md) pour fournir à vos clients un Dashboard hébergé par Stripe, sur lequel ils pourront gérer leur abonnement et leurs informations de facturation. ## Configurer Stripe [Côté serveur] Pour commencer, il vous faut un compte Stripe. [Créez un compte](https://dashboard.stripe.com/register). Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application : #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Créer une session Checkout [Côté serveur] Pour créer une session en mode configuration, utilisez le paramètre `mode` défini sur `setup` lors de la création de la session. Vous trouverez la liste complète des paramètres utilisables pour la création d’une session dans la [documentation relative à l’API sur les sessions Checkout](https://docs.stripe.com/api/checkout/sessions/create.md). Associez la variable de modèle `{CHECKOUT_SESSION_ID}` à l’URL `success_url` afin d’obtenir l’ID de session une fois que votre client a terminé sa session Checkout. Enfin, utilisez le dictionnaire [setup_intent_data.metadata](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-setup_intent_data-metadata) pour transmettre le paramètre `subscription_id` Stripe existant de votre client à la session Checkout. Bien qu’il existe d’autres méthodes pour transmettre ces données à votre serveur, nous utiliserons dans ce guide les métadonnées. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="card" \ -d "mode"="setup" \ -d "customer"="cus_FOsk5sbh3ZQpAU" \ -d "setup_intent_data[metadata][subscription_id]"="sub_8epEF0PuRhmltU" \ -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` ## Rediriger vers Checkout [Côté client] Checkout s’appuie sur [Stripe.js](https://docs.stripe.com/payments/elements.md), la bibliothèque JavaScript de Stripe, pour créer des tunnels de paiement. #### HTML + JS Pour commencer, incluez la balise de script suivante sur votre site Web. Chargez-la toujours directement depuis **https://js.stripe.com**. Vous ne devez pas l’inclure dans un lot ni en héberger de copie. Pour consulter des exemples, veuillez afficher la page d’[exemples pour Stripe](https://github.com/stripe-samples). ```javascript npm install @stripe/stripe-js ``` Créez ensuite une instance de l’[objet Stripe](https://docs.stripe.com/js.md#stripe-function) en indiquant comme premier paramètre votre [clé API](https://docs.stripe.com/keys.md) publiable : ```javascript import {loadStripe} from '@stripe/stripe-js'; const stripe = await loadStripe('<>'); ``` Pour utiliser Checkout sur votre site Web, vous devez ajouter un extrait de code qui inclut l’`id` de session obtenu à l’[étape précédente](https://docs.stripe.com/payments/checkout/subscriptions/update-payment-details.md#create-checkout-session). Lorsque votre client est prêt à enregistrer ou à mettre à jour son moyen de paiement, appelez [redirectToCheckout](https://docs.stripe.com/js.md#stripe-redirect-to-checkout) et fournissez l’`id` de session comme paramètre. ```javascript const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. }); ``` #### React Pour commencer, installez le module Stripe.js. Chargez-le toujours directement depuis **https://js.stripe.com**. Vous ne devez pas l’inclure dans un lot ni en héberger de copie. ```npm npm install @stripe/stripe-js ``` ### Ajoutez Stripe.js à votre page Appelez `loadStripe` avec votre clé publiable. Il renvoie un `Promise` qui se résout avec l’objet `Stripe` après le chargement de Stripe.js. Lorsque votre client est prêt à enregistrer ou à mettre à jour son moyen de paiement, appelez [redirectToCheckout](https://docs.stripe.com/js.md#stripe-redirect-to-checkout) et fournissez l’`id` de session comme paramètre. ```jsx import React from 'react'; import ReactDOM from 'react-dom'; 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('<>'); function App() { const handleClick = async (event) => { // Call your backend to create the Checkout session. const { sessionId } = await fetchCheckoutSession(); // When the customer clicks on the button, redirect them to Checkout. const stripe = await stripePromise; const { error } = await stripe.redirectToCheckout({ sessionId }); // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. }; return ( ); } ReactDOM.render(, document.getElementById('root')); ``` Ce code est généralement appelé depuis un gestionnaire d’événements qui se déclenche suite à une action de votre client, par exemple un clic sur le bouton de paiement. ## Récupérer la session Checkout [Côté serveur] Une fois que votre client a terminé sa session Checkout, vous devez récupérer l’objet session. Il y a deux façons de procéder : - **De manière asynchrone** : en traitant les *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) `checkout.session.completed`, qui contiennent un objet session. En savoir plus sur la [configuration des webhooks](https://docs.stripe.com/webhooks.md). - **De manière synchrone** : obtenez l’ID de session à partir de l’URL `success_url` lorsqu’un utilisateur est redirigé vers votre site. Utilisez l’ID de session pour [récupérer](https://docs.stripe.com/api/checkout/sessions/retrieve.md) l’objet de session. ```curl curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \ -u "<>:" ``` Le choix entre ces deux méthodes dépend de votre tolérance aux abandons de paiement. En effet, il peut arriver que vos clients n’arrivent pas à l’URL `success_url` après la réussite d’un paiement. Ils peuvent par exemple fermer l’onglet de leur navigateur avant d’être correctement redirigés. Si votre intégration traite les webhooks, elle ne sera pas exposée à ce type d’abandon de paiement. Après avoir récupéré l’objet session, obtenez la valeur de la clé `setup_intent`, qui correspond à l’ID du SetupIntent créé lors de la session Checkout. Un [SetupIntent](https://docs.stripe.com/payments/setup-intents.md) est un objet permettant de configurer les coordonnées de compte bancaire de votre client en vue de paiements futurs. Exemple de charge utile `checkout.session.completed` : ```json { "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0", "object": "event", "api_version": "2019-03-14", "created": 1561420781, "data": { "object": { "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k", "object": "checkout.session", "billing_address_collection": null, "client_reference_id": null, "customer": "cus_FOsk5sbh3ZQpAU", "customer_email": null, "display_items": [], "mode": "setup","setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM", "submit_type": null, "subscription": null, "success_url": "https://example.com/success" } }, "livemode": false, "pending_webhooks": 1, "request": { "id": null, "idempotency_key": null }, "type": "checkout.session.completed" } ``` Prenez note de l’ID du `setup_intent` pour la prochaine étape. ## Récupérer le SetupIntent [Côté serveur] À l’aide de l’ID de `setup_intent`, récupérez l’objet SetupIntent à l’aide de l’endpoint [/v1/setup_intents/:id](https://docs.stripe.com/api/setup_intents/retrieve.md). ```curl curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \ -u "<>:" ``` Exemple de réponse : ```json { "id": "seti_1EzVO3HssDVaQm2PJjXHmLlM", "object": "setup_intent", "application": null, "cancellation_reason": null, "client_secret": null, "created": 1561420781,"customer": "cus_FOsk5sbh3ZQpAU", "description": null, "last_setup_error": null, "livemode": false, "metadata": {"subscription_id": "sub_8epEF0PuRhmltU" }, "next_action": null, "on_behalf_of": null,"payment_method": "pm_1F0c9v2eZvKYlo2CJDeTrB4n", "payment_method_types": [ "card" ], "status": "succeeded", "usage": "off_session" } ``` Notez les ID `customer`, `subscription_id` et `payment_method` en vue des prochaines étapes. > Si vous récupérez ces informations de manière synchrone auprès de l’API Stripe (et non en traitant des webhooks), vous pouvez combiner cette étape-ci à l’étape précédente en [développant](https://docs.stripe.com/api/expanding_objects.md) l’objet SetupIntent dans votre requête au endpoint /v1/checkout/session. De cette manière, vous n’avez pas besoin d’effectuer deux requêtes réseau différentes pour accéder à l’ID du PaymentMethod qui vient d’être créé. ## Configurer un moyen de paiement par défaut [Côté serveur] Il existe deux manières de paramétrer l’utilisation d’un moyen de paiement pour les prochaines factures : - Le configurer en tant que paramètre `invoice_settings.default_payment_method` de l’objet Customer - Le configurer en tant que paramètre `default_payment_method` de l’objet Subscription Si vous définissez le paramètre `invoice_settings.default_payment_method` sur l’objet Customer, toutes les factures à venir de ce client seront réglées avec le moyen de paiement spécifié. Définir le paramètre `default_payment_method` de l’objet Subscription revient à dire que toutes les factures à venir pour cet abonnement seront réglées avec le moyen de paiement spécifié, et ce, quel que soit le paramètre `invoice_settings.default_payment_method` défini au niveau de l’objet Customer associé. ### Définir le paramètre invoice_settings.default_payment_method de l’objet Customer À l’aide des ID de client et de PaymentMethod récupérés, définissez le paramètre `invoice_settings.default_payment_method` de l’objet Customer à partir de l’endpoint [/v1/customers/:id](https://docs.stripe.com/api/customers/update.md). ```curl curl https://api.stripe.com/v1/customers/cus_FOsk5sbh3ZQpAU \ -u "<>:" \ -d "invoice_settings[default_payment_method]"=pm_1F0c9v2eZvKYlo2CJDeTrB4n ``` Toutes les factures à venir pour ce client débiteront désormais le nouvel objet PaymentMethod créé à l’aide de la session Checkout du mode configuration. ### Définir le paramètre default_payment_method de l’objet Subscription À l’aide des ID d’abonnement et de PaymentMethod récupérés, définissez le paramètre `default_payment_method` de l’abonnement à partir de l’endpoint [/v1/subscriptions/:id](https://docs.stripe.com/api/subscriptions/update.md). #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_8epEF0PuRhmltU \ -u <>: \ -X "POST" \ -d "default_payment_method"="pm_1F0c9v2eZvKYlo2CJDeTrB4n" ``` Toutes les factures à venir pour cet abonnement débiteront désormais le nouvel objet PaymentMethod créé à l’aide de la session Checkout du mode configuration, et ce, quel que soit le paramètre `invoice_settings.default_payment_method` de l’objet Customer associé. ## See also Félicitations ! Vous pouvez désormais définir un moyen de paiement par défaut pour les prochaines factures. Lors du test de votre intégration à l’aide de votre clé API de test, vous pouvez utiliser un [numéro de carte de test](https://docs.stripe.com/testing.md#cards) pour vérifier que tout fonctionne correctement. - [Cartes de test](https://docs.stripe.com/testing.md#cards)