# Intégrer les abonnements avec Checkout Créez et gérez des abonnements pour accepter des paiements récurrents avec Checkout. # Page entièrement hébergée > This is a Page entièrement hébergée for when payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/checkout/build-subscriptions?payment-ui=stripe-hosted. # Page entièrement hébergée > This is a Page entièrement hébergée for when platform is web and ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/checkout/build-subscriptions?platform=web&ui=stripe-hosted. #### Effort d’intégration Complexity: 2/5 #### Personnalisation de l’interface utilisateur Personnalisation limitée - 20 polices prédéfinies - 3 rayons de bordure prédéfinis - Couleur d’arrière-plan et de bordure personnalisée - Logo personnalisé #### Type d’intégration Utilisez des pages hébergées prédéfinies pour collecter les paiements et gérer vos *abonnements*. [Essayer](https://checkout.stripe.dev/) ## Ce que vous allez créer Ce guide décrit comment vendre des abonnements mensuels à prix fixe en utilisant [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Ce guide vous explique comment : - Modélisez votre entreprise en créant un catalogue de produits. - Ajoutez une session Checkout à votre site, avec un bouton et des pages de confirmation et d’annulation. - Surveillez les événements d’abonnement et fournissez l’accès à votre service. - Configurez le [portail client](https://docs.stripe.com/customer-management.md). - Ajoutez une session de portail client à votre site, avec un bouton et une redirection. - Permettre à vos clients de gérer leurs abonnements sur le portail. - Apprenez à utiliser le [mode de facturation flexible](https://docs.stripe.com/billing/subscriptions/billing-mode.md) pour accéder à un comportement de facturation amélioré et à des fonctionnalités supplémentaires. Si vous n’êtes pas prêt à coder une intégration, vous pouvez configurer les abonnements de base [manuellement](https://docs.stripe.com/no-code/subscriptions.md) ou utiliser [Payment Links](https://docs.stripe.com/payment-links.md) pour configurer les abonnements sans écrire de code. En savoir plus sur la [conception d’une intégration](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) pour comprendre les décisions et les ressources nécessaires à une intégration complète. Une fois l’intégration terminée, vous pouvez l’étendre pour : - Affichez les [taxes](https://docs.stripe.com/payments/checkout/taxes.md) - Appliquez des [ réductions](https://docs.stripe.com/billing/subscriptions/coupons.md#using-coupons-in-checkout). - Offrez à vos clients une [période d’essai gratuite](https://docs.stripe.com/billing/subscriptions/trials.md) - Ajoutez des [moyens de paiement](https://docs.stripe.com/payments/payment-methods/integration-options.md) - Intégrez la [page de facture hébergée](https://docs.stripe.com/invoicing/hosted-invoice-page.md). - Utilisez Checkout dans le [mode de configuration](https://docs.stripe.com/payments/save-and-reuse.md) - Établissez la [facturation à l’usage](https://docs.stripe.com/products-prices/pricing-models.md#usage-based-pricing), les[ niveaux de tarification](https://docs.stripe.com/products-prices/pricing-models.md#tiered-pricing) et la[tarification à l’usage](https://docs.stripe.com/products-prices/pricing-models.md#usage-based-pricing) - Gérez les [prorata](https://docs.stripe.com/billing/subscriptions/prorations.md) - Autorisez les clients à[s’abonner à plusieurs produits](https://docs.stripe.com/billing/subscriptions/quantities.md#multiple-product-sub). - Intégrez les[droits](https://docs.stripe.com/billing/entitlements.md) pour gérer l’accès aux fonctionnalités de votre produit. ## Configurer Stripe Installez le client Stripe de votre choix : #### 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' ``` En option, installez la Stripe CLI. La CLI permet de tester les [webhooks](https://docs.stripe.com/webhooks.md#test-webhook), et vous pouvez l’exécuter pour créer vos produits et tarifs. Pour davantage d’options d’installation, consultez la page consacrée à l’[interface de ligne de commande Stripe](https://docs.stripe.com/stripe-cli.md). ## Créer le modèle tarifaire [Dashboard ou Stripe CLI] Les [modèles de tarification récurrents](https://docs.stripe.com/products-prices/pricing-models.md) représentent les produits ou services que vous vendez, leur coût, la devise que vous acceptez pour les paiements et la période de service pour les abonnements. Pour élaborer le modèle de tarification, créez des [produits](https://docs.stripe.com/api/products.md) (ce que vous vendez) et des [prix](https://docs.stripe.com/api/prices.md) (combien et à quelle fréquence facturer vos produits). Cet exemple utilise une tarification forfaitaire avec deux options de niveau de service différentes : basique et premium. Pour chaque option de niveau de service, vous devez créer un produit et un prix récurrent. Pour ajouter des frais uniques, tels que des frais d’installation, créez un troisième produit avec un prix unique. Chaque produit est facturé à intervalles mensuels. Le prix du produit basique est de 5 USD. Le prix du produit premium est de 15 USD. Voir le[ guide des tarifs forfaitaires ](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md)pour un exemple à trois niveaux. #### Dashboard Accédez à la page [Ajouter un produit](https://dashboard.stripe.com/test/products/create) et créez deux produits. Ajoutez un tarif pour chaque produit, avec une période de facturation mensuelle récurrente : - Produit Premium : service Premium avec fonctionnalités supplémentaires - Prix : Appuyez sur **Payer 15 USD**. - Produit de base : service de base avec fonctionnalités minimales - Prix : Forfaitaire | 5 USD Après avoir créé vos tarifs, enregistrez les ID de tarif de manière à pouvoir les utiliser dans d’autres étapes. Les ID de tarif se présentent sous la forme suivante : `price_G0FvDp6vZvdwRZ`. Lorsque vous le souhaitez, cliquez sur le bouton **Copier en mode production** en haut à droite de la page pour dupliquer votre produit de l’[environnement de test en mode production](https://docs.stripe.com/keys.md#test-live-modes). #### API Vous pouvez utiliser l’API pour créer les[ produits](https://docs.stripe.com/api/products.md) et les[ prix](https://docs.stripe.com/api/prices.md). Créez le produit premium : ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Créez le produit de base : ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Enregistrez l’ID de chaque produit. Les ID de produit se présentent sous la forme suivante : ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Utilisez les ID de produit afin de créer un tarif pour chaque produit. La valeur du champ [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) est exprimé en centimes, donc `1500` = 15 USD, par exemple. Créer le prix premium : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Créer le prix basique : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Enregistrez l’ID de chaque tarif de manière à pouvoir l’utiliser par la suite. Les ID de tarif se présentent sous la forme suivante : ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` Si vous proposez plusieurs périodes de facturation, utilisez Checkout pour [inciter](https://docs.stripe.com/payments/checkout/upsells.md)les clients à opter pour des périodes de facturation plus longues et percevoir davantage de revenus à l’avance. Pour d’autres modèles de tarification, voir la section[Exemples de facturation](https://docs.stripe.com/products-prices/pricing-models.md). ## Créer une session Checkout [Client et serveur] Ajoutez à votre site internet un bouton de paiement qui appelle un endpoint côté serveur afin de créer une session Checkout. ```html Checkout
``` Dans le back-end de votre application, définissez un endpoint qui [crée la session](https://docs.stripe.com/api/checkout/sessions/create.md) que votre front-end pourra appeler. Vous aurez besoin des valeurs suivantes : - L’ID du prix de l’abonnement auquel le client s’inscrit (votre front-end transmet cette valeur) - Votre `success_url`, qui est une page de votre site internet à laquelle Checkout renvoie votre client après l’exécution du paiement. Vous pouvez éventuellement : - Configurez une [date de début](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) de cycle de facturation pour votre abonnement dans cet appel. - Utilisez un[texte personnalisé](https://docs.stripe.com/payments/checkout/custom-components.md?platform=web&payment-ui=stripe-hosted#customize-text) pour inclure vos conditions d’abonnement et d’annulation, ainsi qu’un lien vers l’endroit où vos clients peuvent mettre à jour ou annuler leur abonnement. Nous vous recommandons de configurer des[rappels et notifications par e-mail](https://docs.stripe.com/invoicing/send-email.md#email-configuration) pour vos abonnés. Si vous avez créé un prix unique lors de[étape 2](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md#create-pricing-model), transmettez également l’identifiant de ce prix. Après avoir créé une session Checkout, redirigez votre client vers l’[URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) renvoyée dans la réponse. Vous pouvez activer un comportement d’abonnement plus précis et prévisible lorsque vous créez une session Checkout en paramétrant le [mode de facturation](https://docs.stripe.com/billing/subscriptions/billing-mode.md) sur `flexible`. Vous devez utiliser la [version de l’API Stripe 2025-06-30.basil](https://docs.stripe.com/upgrades.md) ou une version ultérieure. > Vous pouvez utiliser [lookup_keys](https://docs.stripe.com/products-prices/manage-prices.md#lookup-keys) pour récupérer des prix plutôt que des identifiants de prix. Consultez cet [exemple concret](https://github.com/stripe-samples/subscription-use-cases/tree/main/fixed-price-subscriptions) pour plus de détails. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # The price ID passed from the front end. # price_id = params['priceId'] price_id = '{{PRICE_ID}}' session = client.v1.checkout.sessions.create({ success_url: 'https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}', mode: 'subscription', line_items: [{ # For usage-based billing, don't pass quantity quantity: 1, price: price_id }], subscription_data: { billing_mode: { type: 'flexible' } } }) # Redirect to the URL returned on the session # redirect session.url, 303 ``` Cet exemple personnalise l’adresse `success_url` en y ajoutant l’identifiant de la session. Apprenez-en davantage sur la [personnalisation de votre page de succès](https://docs.stripe.com/payments/checkout/custom-success-page.md). Depuis votre [Dashboard](https://dashboard.stripe.com/settings/payment_methods),activez les moyens de paiement que vous souhaitez accepter de vos clients. Checkout prend en charge [plusieurs moyens de paiement](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support). ## Fournir l'accès au service et suivre les abonnements [Serveur] Une fois l’inscription à l’abonnement réussie, le client revient sur votre site internet à l’adresse `success_url`, ce qui déclenche un webhook `checkout.session.completed`. À la réception de cet événement `checkout.session.completed`, utilisez [entitlements](https://docs.stripe.com/billing/entitlements.md) pour provisionner l’abonnement. Continuez à le provisionner chaque mois (en cas de facturation mensuelle) lorsque vous recevez des événements `invoice.paid`. Si vous recevez un événement `invoice.payment_failed`, informez votre client et redirigez-le vers le portail client pour qu’il mette à jour son moyen de paiement. Pour déterminer l’étape suivante de la logique de votre système, vérifiez le type d’événement et analysez la charge utile de chaque [objet event](https://docs.stripe.com/api/events/object.md), comme `invoice.paid`. Sauvegardez les identifiants des objets `Subscription` et `Customer` ou `Account` dans votre base de données pour effectuer la vérification. À des fins de test, vous pouvez surveiller les événements dans l’[onglet d’événements](https://dashboard.stripe.com/workbench/events) de [Workbench](https://docs.stripe.com/workbench.md). Pour la production, configurez un endpoint webhook et abonnez-vous aux types d’événements appropriés. Si vous ne connaissez pas votre clé `STRIPE_WEBHOOK_SECRET`, allez dans la vue des détails de destination de l’[onglet webhooks](https://dashboard.stripe.com/workbench/webhooks) dans Workbench pour la consulter. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') post '/webhook' do webhook_secret = '{{STRIPE_WEBHOOK_SECRET}}' # Exemple : whsec_c7681Dm payload = request.body.read if !webhook_secret.empty? # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts '⚠️ Webhook signature verification failed.' status 400 return end else data = JSON.parse(payload, symbolize_names: true) event = Stripe::Event.construct_from(data) end # Get the type of webhook event sent event_type = event['type'] data = event['data'] data_object = data['object'] case event_type when 'checkout.session.completed' # Payment is successful and the subscription is created. # Provision the subscription and save the customer ID to your database. when 'invoice.paid' # Continue to provision the subscription as payments continue to be made. # Store the status in your database and check when a customer accesses your service. # This approach helps you avoid hitting rate limits. when 'invoice.payment_failed' # The payment failed or the customer doesn't have a valid payment method. # The subscription becomes past_due. Notify your customer and send them to the # customer portal to update their payment information. else puts "Unhandled event type: \#{event.type}" end status 200 end ``` Voici les types d’événement à suivre, a minima : | Nom de l’événement | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | `checkout.session.completed` | Envoyé lorsqu’un client termine avec succès la session Checkout, vous informant d’un nouvel achat. | | `invoice.paid` | Envoyé à chaque période de facturation lorsqu’un paiement réussit. | | `invoice.payment_failed` | Envoyé à chaque période de facturation en cas de problème avec le moyen de paiement de votre client. | Pour plus d’événements à surveiller, voir les[webhooks d’abonnement](https://docs.stripe.com/billing/subscriptions/webhooks.md) ## Configurer le portail client [Dashboard] Le [portail client](https://docs.stripe.com/customer-management.md) permet à vos clients de gérer directement leurs abonnements et factures existants. Utilisez le [Dashboard](https://dashboard.stripe.com/test/settings/billing/portal) pour configurer le portail. Veillez au minimum à [configurer le portail](https://docs.stripe.com/customer-management.md) afin que les clients puissent mettre à jour leurs moyens de paiement. ## Créez une session de portail [Serveur] Définissez un endpoint qui [crée la session du portail client](https://docs.stripe.com/api/customer_portal/sessions/create.md) pour que votre front-end l’appelle. Incluez l’ID du client créé par la session Checkout et que vous avez enregistré lors du traitement du webhook `checkout.session.completed`. Vous pouvez également définir un lien de redirection par défaut pour le portail dans le Dashboard. Transmettez une valeur facultative `return_url` pour la page de votre site vers laquelle rediriger votre client une fois qu’il a terminé la gestion de son abonnement : #### Accounts v2 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # This is the URL that users are redirected to after they're done # managing their billing. return_url = '{{DOMAIN_URL}}' # Exemple : http://exemple.com customer_account_id = '{{CUSTOMER_ACCOUNT_ID}}' # Exemple : cus_GBV60HKsE0mb5v session = Stripe::BillingPortal::Session.create({ customer_account: customer_account_id, return_url: return_url, }) # Redirect to the URL for the session # redirect session.url, 303 ``` #### Customers v1 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # This is the URL that users are redirected to after they're done # managing their billing. return_url = '{{DOMAIN_URL}}' # Exemple : http://exemple.com customer_id = '{{CUSTOMER_ID}}' # Exemple : cus_GBV60HKsE0mb5v session = client.v1.billing_portal.sessions.create({ customer: customer_id, return_url: return_url, }) # Redirect to the URL for the session # redirect session.url, 303 ``` ## Redirigez les clients vers le portail client [Client] Sur votre interface, ajoutez un bouton sur la page à l’adresse `success_url`, afin de fournir un lien vers le portail client. ```html Manage Billing
``` Après avoir quitté le portail client, votre client revient sur votre site Web à l’URL : `return_url`. Continuez à [surveiller les événements](https://docs.stripe.com/billing/subscriptions/webhooks.md) pour suivre l’état de l’abonnement du client. Si vous configurez le portail client pour permettre des actions telles que l’annulation d’un abonnement, [surveillez les événements supplémentaires](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks) ## Tester votre intégration ### Tester les moyens de paiement Utilisez le tableau suivant pour tester différents scénarios et moyens de paiement. | Moyen de paiement | Scénario | Méthode de test | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prélèvement automatique BECS | Le montant dû est réglé par prélèvement automatique BECS. | Remplissez le formulaire à l’aide du numéro de compte `900123456` et du BSB `000000`. La confirmation de la demande de PaymentIntent passe d’abord à l’état `processing`, puis à l’état `succeeded` trois minutes plus tard. | | Prélèvement automatique BECS | Le paiement de votre client échoue avec un code d’erreur `account_closed`. | Remplissez le formulaire à l’aide du numéro de compte `111111113` et du BSB `000000`. | | Carte bancaire | Le paiement par carte bancaire aboutit et ne nécessite pas d’authentification. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte `4242 4242 4242 4242` ainsi que la date d’expiration, le CVC et le code postal de votre choix. | | Carte bancaire | Le paiement par carte bancaire requiert une *authentification* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte `4000 0025 0000 3155` ainsi que la date d’expiration, le CVC et le code postal de votre choix. | | Carte bancaire | La carte est refusée avec un code de refus de type `insufficient_funds`. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro `4000 0000 0000 9995` ainsi que la date d’expiration, le CVC et le code postal de votre choix… | | Prélèvement automatique SEPA | Le montant dû est réglé par prélèvement automatique SEPA. | Remplissez le formulaire à l’aide du numéro de compte `AT321904300235473204`. Le PaymentIntent confirmé passe d’abord à l’état processing, puis à l’état succeeded trois minutes plus tard. | | Prélèvement automatique SEPA | L’état du PaymentIntent de votre client passe de `processing` à `requires_payment_method`. | Remplissez le formulaire à l’aide du numéro de compte `AT861904300235473202`. | ### Écouter des événements Configurez des webhooks pour écouter les événements de changement d’abonnement, tels que les mises à niveau et les annulations. Vous pouvez visualiser les[événements webhook d’abonnement](https://docs.stripe.com/billing/subscriptions/webhooks.md)dans le[Dashboard](https://dashboard.stripe.com/test/events) ou avec la[Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Apprenez-en davantage sur le [test de votre intégration de facturation](https://docs.stripe.com/billing/testing.md) ## See also - [Proposez à vos clients une période d’essai gratuite](https://docs.stripe.com/billing/subscriptions/trials.md) - Appliquez [des réductions](https://docs.stripe.com/billing/subscriptions/coupons.md#using-coupons-in-checkout) - [Gérer les calculs au prorata](https://docs.stripe.com/billing/subscriptions/prorations.md) - [Intégrez les droits pour gérer l’accès aux fonctionnalités de votre produit](https://docs.stripe.com/billing/entitlements.md). # Page entièrement intégrée > This is a Page entièrement intégrée for when payment-ui is embedded-page. View the full page at https://docs.stripe.com/payments/checkout/build-subscriptions?payment-ui=embedded-page. # Page entièrement intégrée > This is a Page entièrement intégrée for when platform is web and ui is embedded-page. View the full page at https://docs.stripe.com/payments/checkout/build-subscriptions?platform=web&ui=embedded-page. #### Effort d’intégration Complexity: 2/5 #### Personnalisation de l’interface utilisateur Personnalisez l’apparence. #### Type d’intégration Utilisez les formulaires intégrés préconfigurés pour encaisser les paiements et gérer les abonnements**. ## Configurez le serveur ### Configurer Stripe Installez le client Stripe de votre choix : #### 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éez un produit et un tarif Les [modèles de tarification récurrents](https://docs.stripe.com/products-prices/pricing-models.md) représentent les produits ou services que vous vendez, leur coût, la devise que vous acceptez pour les paiements et la période de service pour les abonnements. Pour élaborer le modèle de tarification, créez des [produits](https://docs.stripe.com/api/products.md) (ce que vous vendez) et des [prix](https://docs.stripe.com/api/prices.md) (combien et à quelle fréquence facturer vos produits). Cet exemple utilise une tarification forfaitaire avec deux options de niveau de service différentes : basique et premium. Pour chaque option de niveau de service, vous devez créer un produit et un prix récurrent. Pour ajouter des frais uniques, tels que des frais d’installation, créez un troisième produit avec un prix unique. Chaque produit est facturé à intervalles mensuels. Le prix du produit basique est de 5 USD. Le prix du produit premium est de 15 USD. Voir le[ guide des tarifs forfaitaires ](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md)pour un exemple à trois niveaux. #### Dashboard Accédez à la page [Ajouter un produit](https://dashboard.stripe.com/test/products/create) et créez deux produits. Ajoutez un tarif pour chaque produit, avec une période de facturation mensuelle récurrente : - Produit Premium : service Premium avec fonctionnalités supplémentaires - Prix : Appuyez sur **Payer 15 USD**. - Produit de base : service de base avec fonctionnalités minimales - Prix : Forfaitaire | 5 USD Après avoir créé vos tarifs, enregistrez les ID de tarif de manière à pouvoir les utiliser dans d’autres étapes. Les ID de tarif se présentent sous la forme suivante : `price_G0FvDp6vZvdwRZ`. Lorsque vous le souhaitez, cliquez sur le bouton **Copier en mode production** en haut à droite de la page pour dupliquer votre produit de l’[environnement de test en mode production](https://docs.stripe.com/keys.md#test-live-modes). #### API Vous pouvez utiliser l’API pour créer les[ produits](https://docs.stripe.com/api/products.md) et les[ prix](https://docs.stripe.com/api/prices.md). Créez le produit premium : ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Créez le produit de base : ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Enregistrez l’ID de chaque produit. Les ID de produit se présentent sous la forme suivante : ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Utilisez les ID de produit afin de créer un tarif pour chaque produit. La valeur du champ [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) est exprimé en centimes, donc `1500` = 15 USD, par exemple. Créer le prix premium : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Créer le prix basique : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Enregistrez l’ID de chaque tarif de manière à pouvoir l’utiliser par la suite. Les ID de tarif se présentent sous la forme suivante : ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` Si vous proposez plusieurs périodes de facturation, utilisez Checkout pour [inciter](https://docs.stripe.com/payments/checkout/upsells.md)les clients à opter pour des périodes de facturation plus longues et percevoir davantage de revenus à l’avance. Pour d’autres modèles de tarification, voir la section[Exemples de facturation](https://docs.stripe.com/products-prices/pricing-models.md). ### Créer une session Checkout Ajoutez un endpoint sur votre serveur qui crée une session Checkout**. Lorsque vous créez la session [Checkout](https://docs.stripe.com/api/checkout/sessions/create.md), transmettez les paramètres suivants : - Pour utiliser la page de paiement intégrée, définissez [ui_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-ui_mode) sur `embedded_page`. - Pour créer des abonnements lorsque votre client paie, réglez le [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) sur `subscription`. - Pour définir la page sur laquelle votre client retourne après avoir effectué ou tenté d’effectuer un paiement, spécifiez une [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). Incluez la variable de modèle `{CHECKOUT_SESSION_ID}` dans l’URL. Checkout remplace cette variable par l’identifiant de la `CheckoutSession` avant de rediriger votre client. Vous créez et hébergez la page de retour sur votre site internet. - Pour inclure vos conditions d’abonnement et d’annulation, ainsi qu’un lien vers l’endroit où vos clients peuvent mettre à jour ou annuler leur abonnement, vous pouvez utiliser un [texte personnalisé](https://docs.stripe.com/payments/checkout/custom-components.md?ui=embedded-page#customize-payment-method-reuse-agreement-and-subscription-terms). Nous vous recommandons de configurer des [rappels et notifications par e-mail](https://docs.stripe.com/invoicing/send-email.md#email-configuration) pour vos abonnés. Pour monter Checkout, utilisez le `client_secret` de la session Checkout renvoyé dans la réponse. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=subscription \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d ui_mode=embedded_page \ --data-urlencode "return_url=https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}" ``` ## Créez votre page d'abonnement [Client] ### Monter Checkout #### HTML + JS #### Charger Stripe.js Utilisez *Stripe.js* (Use Stripe.js’ APIs to tokenize customer information, collect sensitive card data, and accept payments with browser payment APIs) pour rester en conformité avec la *norme PCI* (Any party involved in processing, transmitting, or storing credit card data must comply with the rules specified in the Payment Card Industry (PCI) Data Security Standards. PCI compliance is a shared responsibility and applies to both Stripe and your business) en veillant à ce que les informations de paiement soient envoyées directement à Stripe sans passer par votre serveur. Chargez toujours Stripe.js directement à partir de js.stripe.com pour maintenir votre conformité. Vous ne devez pas inclure ce script dans un lot ni en héberger de copie. #### Définir le formulaire de paiement Pour collecter les informations du client en toute sécurité, créez un espace réservé vide `div`. Stripe insère un iframe dans le `div`. Checkout est disponible dans : [Stripe.js](https://docs.stripe.com/js.md). Ajoutez le script Stripe.js à votre page en l’insérant dans l’en-tête de votre fichier HTML. Ensuite, créez un nœud DOM vide (conteneur) à utiliser pour le montage. ```html Accept a payment
``` #### Initialiser Stripe.js Initialisez Stripe.js avec votre clé API publique. #### Récupérez une clé secrète client de session Checkout Créez une fonction asynchrone `fetchClientSecret` qui envoie une requête à votre serveur[ pour créer une session Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) et récupérer la clé secrète du client. #### Initialiser Checkout Initialisez Checkout avec votre fonction `fetchClientSecret` et montez-la sur le placeholder `
` dans votre formulaire de paiement. Checkout est affiché dans un iframe qui envoie de façon sécurisée les informations de paiement à Stripe via une connexion HTTPS. Évitez de placer Checkout dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement. ```javascript // Initialize Stripe.js const stripe = Stripe('<>'); initialize(); // Fetch Checkout Session and retrieve the client secret async function initialize() { const fetchClientSecret = async () => { const response = await fetch("/create-checkout-session", { method: "POST", }); const { clientSecret } = await response.json(); return clientSecret; }; // Initialize Checkout const checkout = await stripe.createEmbeddedCheckoutPage({ fetchClientSecret, }); // Mount Checkout checkout.mount('#checkout'); } ``` #### React #### Ajoutez Stripe à votre application React Installez [React-Stripe.js](https://docs.stripe.com/sdks/stripejs-react.md) pour rester conforme aux normes PCI en vous assurant que les détails du paiement vont directement à Stripe et n’atteignent jamais votre serveur. ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` #### Charger Stripe.js Pour configurer la bibliothèque Stripe, appelez `loadStripe()` avec votre clé API publique Stripe. Créez un `EmbeddedCheckoutProvider`. Transmettez au fournisseur la `Promise` renvoyée. #### Récupérez une clé secrète client de session Checkout Créez une fonction asynchrone `fetchClientSecret` qui envoie une requête à votre serveur[ pour créer une session Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) et récupérer la clé secrète du client. #### Initialiser Checkout Pour permettre aux composants enfants d’accéder au service Stripe via le client Checkout intégré, transmettez la promesse renvoyée par`loadStripe`, et la fonction `fetchClientSecret` comme `option` au fournisseur Checkout intégré. ```jsx import * as React from 'react'; import {loadStripe} from '@stripe/stripe-js'; import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-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_123', { }); const App = ({fetchClientSecret}) => { const options = {fetchClientSecret}; return ( ) } ``` ## Afficher une page de retour Après que votre client a tenté d’effectuer un paiement, Stripe le redirige vers une page de retour que vous hébergez sur votre site. Lorsque vous avez créé la session Checkout, vous avez spécifié l’URL de cette page de retour dans le paramètre [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). > Lors du paiement, certains moyens de paiement redirigent le client vers une page intermédiaire, comme par exemple une page d’autorisation bancaire. Une fois cette étape validée, Stripe redirige le client vers votre page de retour. #### Créer un endpoint pour récupérer une session Checkout Ajoutez un endpoint pour récupérer l’état d’une session Checkout avec l’identifiant de session Checkout dans l’URL. #### Récupérez une session Checkout Pour exploiter les informations de la session Checkout, envoyez immédiatement une requête à l’endpoint de votre serveur pour [récupérer la session Checkout](https://docs.stripe.com/api/checkout/sessions/retrieve.md), en utilisant l’identifiant de la session Checkout présent dans l’URL, dès le chargement de votre page de retour. #### Gérer la session Traitez le résultat établi en fonction de l’état de la session : - `complete` : le paiement a abouti. Utilisez les informations de la session Checkout pour afficher une page de confirmation. - `open` : le paiement a échoué ou a été annulé. Montez à nouveau Checkout pour que votre client puisse effectuer une nouvelle tentative. ```js // Retrieve a Checkout Session // Use the session ID initialize(); async function initialize() { const queryString = window.location.search; const urlParams = new URLSearchParams(queryString); const sessionId = urlParams.get('session_id'); const response = await fetch(`/session-status?session_id=${sessionId}`); const session = await response.json(); // Handle the session according to its status if (session.status == 'open') { // Remount embedded Checkout window.location.replace('http://localhost:4242/checkout.html') } else if (session.status == 'complete') { document.getElementById('success').classList.remove('hidden'); document.getElementById('customer-email').textContent = session.customer_email; // Show success page // Optionally use session.payment_status or session.customer_email // to customize the success page } } ``` #### Accounts v2 ```javascript // Add an endpoint to fetch the Checkout Session status app.get('/session_status', async (req, res) => { const session = await stripe.checkout.sessions.retrieve(req.query.session_id); const customer_account = await stripe.v2.core.accounts(session.customer_account); res.send({ status: session.status, payment_status: session.payment_status, customer_email: customer_account.contact_email }); }); ``` #### Customers v1 ```javascript // Add an endpoint to fetch the Checkout Session status app.get('/session_status', async (req, res) => { const session = await stripe.checkout.sessions.retrieve(req.query.session_id); const customer = await stripe.customers.retrieve(session.customer); res.send({ status: session.status, payment_status: session.payment_status, customer_email: customer.email }); }); ``` ## Optional: Configurer le portail client Vous pouvez configurer le portail client** pour permettre à vos clients de gérer directement leurs abonnements et factures existants. Vous pouvez configurer le portail dans le Dashboard. Pour réduire le taux d’attrition, configurez le portail afin de permettre aux clients de mettre à jour leurs moyens de paiement en cas d’échec de paiement. Pour faciliter la recherche des clients, ajoutez sur votre site internet un bouton de redirection vers le portail client, afin de leur permettre de gérer leur abonnement. Lorsqu’ils cliquent sur ce bouton, vos clients sont redirigés vers la page du portail client hébergée par Stripe. Apprenez-en davantage sur le [ portail client](https://docs.stripe.com/customer-management.md)et les autres options de gestion des clients. #### Créez une session de portail Pour ajouter un portail client, définissez un endpoint qui [crée la session du portail client](https://docs.stripe.com/api/customer_portal/sessions/create.md) pour que votre front-end l’appelle. Incluez l’’identifiant client créé par une session Checkout et que vous avez enregistré lors du traitement du webhook `checkout.session.completed`. Vous pouvez également définir un lien de redirection par défaut pour le portail dans le Dashboard. Transmettez une valeur facultative `return_url` pour la page de votre site vers laquelle rediriger votre client une fois qu’il a terminé la gestion de son abonnement : #### Accounts v2 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # This is the URL that users are redirected to after they're done # managing their billing. return_url = '{{DOMAIN_URL}}' # Exemple : http://exemple.com customer_account_id = '{{CUSTOMER_ACCOUNT_ID}}' # Exemple : cus_GBV60HKsE0mb5v session = Stripe::BillingPortal::Session.create({ customer_account: customer_account_id, return_url: return_url, }) # Redirect to the URL for the session # redirect session.url, 303 ``` #### Customers v1 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # This is the URL that users are redirected to after they're done # managing their billing. return_url = '{{DOMAIN_URL}}' # Exemple : http://exemple.com customer_id = '{{CUSTOMER_ID}}' # Exemple : cus_GBV60HKsE0mb5v session = client.v1.billing_portal.sessions.create({ customer: customer_id, return_url: return_url, }) # Redirect to the URL for the session # redirect session.url, 303 ``` #### Redirigez les clients vers le portail client Sur votre interface, ajoutez un bouton sur la page à l’adresse `success_url`, afin de fournir un lien vers le portail client. ```html Manage Billing
``` Après avoir quitté le portail client, votre client revient sur votre site Web à l’URL : `return_url`. Continuez à [surveiller les événements](https://docs.stripe.com/billing/subscriptions/webhooks.md) pour suivre l’état de l’abonnement du client. Si vous configurez le portail client pour permettre des actions telles que l’annulation d’un abonnement, veillez à surveiller [ les événements supplémentaires ](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks). ## Fourniture de l'accès Lorsque l’abonnement est actif, donnez à votre client l’accès à votre service. Pour ce faire, écoutez les événements `customer.subscription.created`, `customer.subscription.updated` et `customer.subscription.deleted` (même si vous utilisez des `Accounts` configurés par le client). Ces événements transmettent un objet `Subscription` qui contient un champ `status` indiquant si l’abonnement est actif, en retard de paiement ou annulé. Pour obtenir la liste complète des états, consultez le [cycle de vie](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) de l’abonnement. Pour gérer l’accès aux fonctionnalités de votre produit, découvrez comment [intégrer les droits](https://docs.stripe.com/billing/entitlements.md) d’accès. Dans votre gestionnaire de webhooks : 1. Vérifiez l’état de l’abonnement. S’il est `active`, votre client a payé pour votre produit. 1. Vérifiez le produit auquel votre client s’est abonné et donnez-lui accès à votre service. La vérification du produit plutôt que du tarif vous permet de modifier la tarification ou la période de facturation si nécessaire. 1. Sauvegardez les `product.id`, `subscription.id` et `subscription.status` dans votre base de données avec le `customer_account.id` ou le `customer.id` déjà sauvegardé. Consultez cet enregistrement pour déterminer quelles fonctionnalités activer pour le client dans votre application. L’état d’un abonnement peut évoluer à tout moment pendant sa durée de vie, même si votre application n’effectue aucun appel direct à Stripe. Par exemple, un renouvellement peut échouer en raison d’une carte bancaire expirée, ce qui place l’abonnement en état de paiement en retard. Ou encore, si vous implémentez le [portail client](https://docs.stripe.com/customer-management.md), un client peut annuler son abonnement sans passer directement par votre application. Une implémentation correcte de votre gestionnaire garantit la synchronisation de l’état de votre application avec Stripe. ## Tester votre intégration ### Tester les moyens de paiement Utilisez le tableau suivant pour tester différents scénarios et moyens de paiement. | Moyen de paiement | Scénario | Méthode de test | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prélèvement automatique BECS | Le montant dû est réglé par prélèvement automatique BECS. | Remplissez le formulaire à l’aide du numéro de compte `900123456` et du BSB `000000`. La confirmation de la demande de PaymentIntent passe d’abord à l’état `processing`, puis à l’état `succeeded` trois minutes plus tard. | | Prélèvement automatique BECS | Le paiement de votre client échoue avec un code d’erreur `account_closed`. | Remplissez le formulaire à l’aide du numéro de compte `111111113` et du BSB `000000`. | | Carte bancaire | Le paiement par carte bancaire aboutit et ne nécessite pas d’authentification. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte `4242 4242 4242 4242` ainsi que la date d’expiration, le CVC et le code postal de votre choix. | | Carte bancaire | Le paiement par carte bancaire requiert une *authentification* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte `4000 0025 0000 3155` ainsi que la date d’expiration, le CVC et le code postal de votre choix. | | Carte bancaire | La carte est refusée avec un code de refus de type `insufficient_funds`. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro `4000 0000 0000 9995` ainsi que la date d’expiration, le CVC et le code postal de votre choix… | | Prélèvement automatique SEPA | Le montant dû est réglé par prélèvement automatique SEPA. | Remplissez le formulaire à l’aide du numéro de compte `AT321904300235473204`. Le PaymentIntent confirmé passe d’abord à l’état processing, puis à l’état succeeded trois minutes plus tard. | | Prélèvement automatique SEPA | L’état du PaymentIntent de votre client passe de `processing` à `requires_payment_method`. | Remplissez le formulaire à l’aide du numéro de compte `AT861904300235473202`. | ### Écouter des événements Configurez des webhooks pour écouter les événements de changement d’abonnement, tels que les mises à niveau et les annulations. Vous pouvez visualiser les[événements webhook d’abonnement](https://docs.stripe.com/billing/subscriptions/webhooks.md)dans le[Dashboard](https://dashboard.stripe.com/test/events) ou avec la[Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Apprenez-en davantage sur le [test de votre intégration de facturation](https://docs.stripe.com/billing/testing.md)