Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
Aperçu
Billing
PrésentationÀ propos des API Billing
Abonnements
Tax
Présentation
Rapports
PrésentationRapports sur plusieurs comptes
Données
Présentation

Créer une intégration pour les abonnements

Créez et gérez des abonnements pour les paiements récurrents.

Page de paiement d'abonnement
Low-code

Personnalisez le logo, les images et les couleurs.

Utilisez des pages hébergées prédéfinies pour collecter les paiements et gérer vos abonnements.

Clonez un exemple d’intégration depuis GitHub

Pour une version immersive de ce guide, consultez le guide de démarrage rapide de l’intégration de la facturation.

Explorez l’exemple sur GitHub ou la démo.

Ce que vous allez créer

Ce guide décrit comment vendre des abonnements mensuels à prix fixe en utilisant Stripe Checkout.

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.
  • 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 pour accéder à un comportement de facturation amélioré et à des fonctionnalités supplémentaires.

Une fois l’intégration terminée, vous pouvez l’étendre pour :

Configurer Stripe

Installez le client Stripe de votre choix :

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# 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, et vous pouvez l’exécuter pour créer vos produits et tarifs.

Command Line
homebrew
Installer à partir d'une source
No results
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Pour davantage d’options d’installation, consultez la page consacrée à l’interface de ligne de commande Stripe.

Créer le modèle tarifaire
Dashboard ou Stripe CLI

Créez vos produits et leurs tarifs dans le Dashboard ou via l’interface de ligne de commande Stripe.

Cet exemple utilise un service à tarif fixe avec deux options de niveau de service différentes : Basic et Premium. Pour chaque option de niveau de service, vous devez créer un produit et un tarif récurrent. (Si vous souhaitez ajouter un paiement ponctuel, par exemple des frais d’installation, créez un troisième produit avec un tarif unique. Par souci de simplicité, cet exemple n’inclut pas de paiement ponctuels.)

Dans cet exemple, chaque produit est facturé mensuellement. Le tarif du produit de base est de 5 USD. Celui du produit premium est de 15 USD.

Accédez à la page Ajouter un produit 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.

Si vous proposez plusieurs périodes de facturation, utilisez Checkout pour inciterles 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 sectionExemples de facturation.

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.

index.html
Afficher l'exemple dans son intégralité
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <!-- Note: If using PHP set the action to /create-checkout-session.php -->

      <input type="hidden" name="priceId" value="price_G0FvDp6vZvdwRZ" />
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Sur le back-end de votre application, définissez un endpoint qui crée la session pour que votre front-end l’appelle. Vous avez besoin de ces valeurs :

  • L’identifiant du prix de l’abonnement que souscrit votre client (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 :

  • Utilisez cancel_url pour afficher une page de votre site internet sur laquelle Checkout renvoie votre client s’il annule le processus de paiement.
  • Configurez une date de début de cycle de facturation pour votre abonnement dans cet appel.
  • Utilisez untexte personnalisé 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 desrappels et notifications par e-mail pour vos abonnés.

Si vous avez créé un prix unique lors deétape 2, transmettez également l’identifiant de ce prix. Après avoir créé une session Checkout, redirigez votre client vers l’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 sur flexible. Vous devez utiliser la version de l’API Stripe 2025-06-30.basil ou une version ultérieure.

Remarque

Vous pouvez utiliser lookup_keys pour récupérer des prix plutôt que des identifiants de prix. Consultez cet exemple concret pour plus de détails.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Afficher l'exemple dans son intégralité
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


# The price ID passed from the front end.
#   price_id = params['priceId']
price_id = '{{PRICE_ID}}'

session = Stripe::Checkout::Session.create({
  success_url: 'https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/canceled.html',
  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.

Depuis votre Dashboard,activez les moyens de paiement que vous souhaitez accepter de vos clients. Checkout prend en charge plusieurs moyens de paiement.

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 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 les données utiles de chaque event object, tel que invoice.paid. Sauvegardez les objets subscription.id et customer.id dans votre base de données pour vérification.

À des fins de test, vous pouvez surveiller les événements dans l’onglet d’événements de Workbench. 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 dans Workbench pour la consulter.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Afficher l'exemple dans son intégralité
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/webhook' do
  webhook_secret = 
'{{STRIPE_WEBHOOK_SECRET}}'

  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.
    # You should 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 user 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énementDescription
checkout.session.completedEnvoyé lorsqu’un client termine avec succès la session Checkout, vous informant d’un nouvel achat.
invoice.paidEnvoyé à chaque période de facturation lorsqu’un paiement réussit.
invoice.payment_failedEnvoyé à 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 leswebhooks d’abonnement

Configurer le portail client
Dashboard

Le portail client permet à vos clients de gérer directement leurs abonnements et factures existants.

Utilisez le Dashboard pour configurer le portail. Veillez au minimum à configurer le portail 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 pour que votre front-end l’appelle. L’identifiant CUSTOMER_ID fait référence à l’identifiant du client créé par une session Checkout que vous avez enregistré en traitant l’événement 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 :

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Afficher l'exemple dans son intégralité
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


# This is the URL that users are redirected to after they're done
# managing their billing.
return_url = 
'{{DOMAIN_URL}}'

customer_id = 
'{{CUSTOMER_ID}}'


session = Stripe::BillingPortal::Session.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 front-end, ajoutez un bouton sur la page success_url qui redirige vers le portail client :

success.html
Afficher l'exemple dans son intégralité
<html>
  <head>
    <title>Manage Billing</title>
  </head>
  <body>
    <form action="/customer-portal" method="POST">
      <!-- Note: If using PHP set the action to /customer-portal.php -->
      <button type="submit">Manage Billing</button>
    </form>
  </body>
</html>

Après avoir quitté le portail client, votre client revient sur votre site Web à l’URL : return_url. Continuez à surveiller les événements 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

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 paiementScénarioMéthode de test
Prélèvement automatique BECSLe 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 de traitement, puis à l’état réussi trois minutes plus tard.
Prélèvement automatique BECSLe 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 bancaireLe 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 bancaireLe paiement par carte bancaire requiert une authentification.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 bancaireLa 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 SEPALe 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 SEPAL’é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’abonnementdans leDashboard ou avec laStripe CLI.

Apprenez-en davantage sur le test de votre intégration de facturation

Voir aussi

Cette page vous a-t-elle été utile ?
OuiNon