Intégrez les abonnements à Elements

Installez le client Stripe de votre choix :

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Installez ensuite l’interface CLI Stripe. L’interface CLI permet de tester les webhooks et vous pouvez l’utiliser pour effectuer des appels à l’API vers Stripe. Ce guide explique comment utiliser l’interface CLI pour configurer un modèle de tarification dans une section ultérieure.

# 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.

Les modèles de tarification récurrents 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 (ce que vous vendez) et des prix (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 pour un exemple à trois niveaux.

Stripe a besoin d’un client pour chaque abonnement. Dans le front-end de votre application, collectez les informations nécessaires auprès de vos clients et transmettez-les au back-end.

Si vous avez besoin de collecter des données d’adresse, Address Element vous permet de collecter une adresse de livraison ou de facturation pour vos clients. Pour plus d’informations sur l’Address Element, voir la page Address Element.

<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

Sur le serveur, créez un objet pour représenter le client. Il peut s’agir d’un objet Account côté client ou d’un objet Customer. Enregistrez l’ID de l’objet pour l’utiliser dans la Checkout Session.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_VePHdqKTYQjKNInc7u56JBrQ
" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

Côté back-end, définissez un endpoint qui crée la session et que le front-end pourra appeler. Cette étape nécessite l’identifiant de prix de l’abonnement choisi par le client, transmis automatiquement par votre front-end.

Si vous avez créé un prix unique lors de l’étape 2, transmettez également l’identifiant de ce prix. Après avoir créé une session Checkout, veillez à renvoyer la clé secrète du client au client dans la réponse.

require 'stripe'
require 'sinatra'

# This test secret API key is a placeholder. Don't include personal details in requests with this key.
# To see your test secret API key embedded in code samples, sign in to your Stripe account.
# You can also find your test secret API key at https://dashboard.stripe.com/test/apikeys.
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
Stripe.api_key = 
'sk_test_VePHdqKTYQjKNInc7u56JBrQ'
Stripe.api_version = '2026-06-24.dahlia'

set :static, true
set :port, 4242

YOUR_DOMAIN = 'http://localhost:3000'

post '/create-checkout-session' do
  content_type 'application/json'

  session = Stripe::Checkout::Session.create({
    ui_mode: 'elements',
    # Provide the Account ID of the account you previously created
    customer_account: '{{CUSTOMER_ACCOUNT_ID}}',
    line_items: [{
      # Provide the exact Price ID (for example, price_1234) of the product you want to sell
      price: '{{PRICE_ID}}',
      quantity: 1,
    }],
    mode: 'subscription',
    return_url: YOUR_DOMAIN + '/return?session_id={CHECKOUT_SESSION_ID}',
  })

  { clientSecret: session.client_secret }.to_json
end

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

Collectez les informations de paiement de votre client à l’aide de Payment Element. Payment Element est un composant d’interface utilisateur préconfiguré qui simplifie la collecte des informations pour de nombreux moyens de paiement.

Le Payment Element contient un iframe qui envoie les informations de paiement à Stripe de manière sécurisée via une connexion HTTPS. Évitez de placer le Payment Element dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement.

Si vous choisissez d’utiliser un iframe et que vous souhaitez accepter Apple Pay ou Google Pay, l’attribut allow de l’iframe doit être défini sur égal à "payment *".

Pour que votre intégration fonctionne, l’adresse de la page de paiement doit commencer par https:// et non par http://. Vous pouvez tester votre intégration sans utiliser le protocole HTTPS, mais n’oubliez pas de l’activer lorsque vous souhaitez commencer à accepter des paiements réels.

<div id="payment-element"></div>

const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

Pour compléter l’intégration, vous devez traiter les webhooks envoyés par Stripe. Ces événements se déclenchent lorsqu’un statut change dans Stripe, par exemple quand un abonnement génère une nouvelle facture. Dans votre application, configurez un gestionnaire HTTP pour accepter les requêtes POST contenant l’événement de webhook et vérifiez la signature de l’événement :

# 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(
'sk_test_VePHdqKTYQjKNInc7u56JBrQ')

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Pendant le développement, utilisez la Stripe CLI pour observer les webhooks et les transmettre à votre formulaire d’inscription. Exécutez ensuite la commande suivante dans un nouveau terminal pendant que votre application de développement est en cours d’exécution :

stripe listen --forward-to localhost:4242/webhook

En production, configurez une URL d’endpoint webhook dans le Dashboard, ou utilisez l’API Webhook Endpoints.

Vous devez écouter quelques événements pour effectuer les étapes restantes de ce guide. Consultez lesÉvénements d’abonnement pour plus de détails sur les webhooks spécifiques aux abonnements.

Maintenant que l’abonnement est actif, donnez à votre utilisateur l’accès à votre service. Pour ce faire, écoutez les événements customer.subscription.created, customer.subscription.updated, et customer.subscription.deleted. Ces événements transmettent un objet d’abonnement qui contient un champ status indiquant si l’abonnement est actif, en retard ou annulé. Pour obtenir la liste complète des états, consultez le cycle de vie de l’abonnement.

Dans votre gestionnaire de webhooks :

1. Vérifiez l’état de l’abonnement. S’il est active, cela signifie que l’utilisateur a payé pour votre produit.
2. Vérifiez le produit auquel le client s’est abonné et accordez-lui l’accès à votre service. Le fait de contrôler le produit plutôt que le tarif vous offre plus de flexibilité si vous devez modifier la tarification ou la période de facturation.
3. 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à stocké. Vérifiez ce dossier au moment de décider des fonctionnalités à activer pour l’utilisateur dans votre application.

L’état d’un abonnement peut changer à 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 retard. Ou, si vous implémentez le portail client, un utilisateur peut annuler son abonnement sans passer directement par votre application. Une implémentation correcte de votre gestionnaire permet de synchroniser le statut de votre application avec celui de Stripe.

Il est courant de laisser aux clients la possibilité d’annuler leur abonnement. Cet exemple montre comment ajouter une option d’annulation sur la page des paramètres du compte.

Paramètres d’un compte ayant la possibilité d’annuler son abonnement

function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

Sur le back-end, définissez le endpoint que votre front-end doit appeler.

# 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(
'sk_test_VePHdqKTYQjKNInc7u56JBrQ')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Votre application reçoit un événement customer.subscription.deleted.

Après la résiliation de l’abonnement, mettez à jour votre base de données pour supprimer l’identifiant de l’abonnement Stripe que vous aviez précédemment stocké, et limitez l’accès à votre service.

Lorsqu’un abonnement est annulé, vous ne pouvez pas le réactiver. À la place, collectez les informations de facturation mises à jour auprès de votre client, actualisez son moyen de paiement par défaut et créez un nouvel abonnement à partir de son dossier client existant.

Tester les moyens de paiement

Utilisez le tableau suivant pour tester différents scénarios et moyens de paiement.

Écouter des événements

Configurez des webhooks pour écouter les événements de changement d’abonnement, tels que les mises à niveau et les annulations. Apprenez-en plus sur les webhooks d’abonnement. Vous pouvez visualiser les événements dans le Dashboard ou via laStripe CLI.

Pour plus d’informations, voir la sectiontester votre intégration Billing.