Créer une intégration pour les abonnements

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 la CLI Stripe. La CLI permet de tester les webhooks, et vous pouvez l’utiliser pour effectuer des appels API vers Stripe. La présent guide montre comment utiliser l’interface de programmation 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.

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.

Stripe a besoin d’un Client pour chaque abonnement. Dans la partie frontale de votre application, collectez toutes les informations nécessaires auprès de vos utilisateurs 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 l’objet Stripe Customer.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Laissez votre nouveau client choisir une offre, puis créez l’abonnement. Dans ce guide, le client a le choix entre l’option de base et l’option Premium.

Sur votre front-end, transmettez l’ID du tarif sélectionné et l’ID de l’enregistrement client à votre back-end.

fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerId: customerId,
  }),
})

Sur votre back-end, créez l’abonnement avec l’état incomplete à l’aide de payment_behavior=default_incomplete. Renvoyez ensuite le client_secret du premier PaymentIntent de l’abonnement vers votre front-end pour effectuer le paiement en développant le confirmation_secret sur la dernière facture de l’abonnement.

Pour activer comportement d’abonnement amélioré, définissez billing_mode[type] sur flexible. Vous devez utiliser Stripe API version 2025-06-30.basil ou une version ultérieure.

Définissez save_default_payment_method on_subscription pour enregistrer le moyen de paiement comme moyen de paiement par défaut pour un abonnement lorsqu’un paiement est effectué avec succès. L’enregistrement d’un moyen de paiement par défaut augmente le taux de réussite des futurs paiements d’abonnement.

# 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 '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: {type: 'flexible'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

À ce stade, l’objet Subscription est inactive et en attente de paiement. Voici un exemple de réponse. Les champs à sauvegarder impérativement sont en surbrillance, mais vous devez également sauvegarder tous les éléments auxquels votre application accède fréquemment.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Utilisez Stripe Elements pour collecter les données de paiement du client et activer son abonnement. Vous pouvez personnaliser Elements aux couleurs de votre application.

Le composant Payment Element prend en charge Link, les cartes bancaires, et les prélèvements automatiques SEPA et BECS pour les abonnements. Il affiche les moyens de paiement que vous avez activés et recueille de manière sécurisée les informations de paiement en fonction de la sélection du client.

Configurer Stripe Elements

Le Payment Element est automatiquement disponible en tant que fonctionnalité de Stripe.js. Intégrez le script Stripe.js à votre page de paiement en l’ajoutant au head votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour rester conforme aux normes PCI. N’incluez pas le script dans un lot et n’en hébergez pas de copie.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

Sur votre page de paiement, créez une instance de Stripe avec le code JavaScript suivant :

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Ajouter le composant Element Payment à votre page

Le composant Element Payment doit avoir un emplacement dédié sur votre page de paiement. Créez un nœud DOM (conteneur) vide avec un ID unique dans votre formulaire de paiement.

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Une fois le formulaire ci-dessus chargé, créez une instance de l’Element Payment et montez-la sur le nœud DOM conteneur. À l’étape de création de l’abonnement, vous avez transmis la valeur client_secret à votre front-end. Transmettez cette valeur en tant qu’option lors de la création de l’instance de l’Element.

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in payment form, passing the client secret obtained in step 5
const elements = stripe.elements(options);

const paymentElementOptions = {
  layout: "tabs",
};

// Create and mount the Payment Element
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Le composant Payment Element affiche un formulaire dynamique qui permet à votre client de sélectionner un moyen de paiement. Le formulaire collecte automatiquement toutes les informations de paiement nécessaires pour le moyen de paiement sélectionné.

Configurations facultatives du Payment Element

• Adaptez le Payment Element au design de votre site en transmettant l’objet Appearance dans les options lors de la création d’une instance d’Elements.
• Configurez l’interface Apple Pay afin de renvoyer un token de marchand pour prendre en charge les paiements récurrents, les paiements différés et les paiements par rechargement automatique.

Mener à bien le paiement

Utilisez stripe.confirmPayment pour mener à bien le paiement à l’aide des informations de le composant Element Payment et activer l’abonnement. Un PaymentMethod est alors créé et le premier PaymentIntent de l’abonnement incomplet est confirmé, ce qui déclenche le processus de paiement. Si une authentication forte du client (SCA) est requise pour le paiement, le composant Element Payment gère le processus d’authentification avant de confirmer le PaymentIntent.

Ajoutez une URL return_url à cette fonction pour indiquer la page vers laquelle Stripe doit rediriger l’utilisateur une fois le paiement effectué. Votre utilisateur peut être d’abord redirigé vers un site intermédiaire, comme une page d’autorisation bancaire, avant d’être redirigé vers l’URL return_url. Les paiements par carte sont immédiatement redirigés vers l’URL return_url à la réussite du paiement.

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = 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`.
  }
});

Lorsque votre client effectue un paiement, Stripe le redirige vers l’URL return_url et inclut les paramètres de requête d’URL suivants. La page de redirection peut utiliser ces paramètres pour récupérer l’état du PaymentIntent et ainsi afficher l’état du paiement pour le client.

Lorsque vous spécifiez une URL return_url, vous pouvez également ajouter vos propres paramètres de requête à utiliser sur la page de redirection.

Lorsque le client est redirigé vers votre site, vous pouvez utiliser le payment_intent_client_secret pour interroger le PaymentIntent et communiquer l’état de la transaction à votre client.

Utilisez l’un des paramètres de requête pour récupérer le PaymentIntent. Consultez l’état du PaymentIntent pour déterminer les informations à présenter à vos clients. Vous pouvez également ajouter vos propres paramètres de requête lorsque vous ajoutez l’URL return_url ; ils seront conservés tout au long du processus de redirection.

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` status.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Afin de compléter votre intégration, vous devez traiter les webhooks envoyés par Stripe. Les webhooks sont des événements qui se déclenchent lorsqu’un état change dans Stripe, par exemple lorsque des abonnement créent de nouvelles factures. Dans votre formulaire d’inscription, configurez un gestionnaire HTTP de sorte qu’il accepte les requêtes POST contenant l’événement de webhook, et vérifiez la signature de l’événement :

# 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
  # 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 l’interface de ligne de commande de Stripe pour observer les webhooks et les transférer vers votre application. Exécutez 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

Pour le mode production, définissez un endpoint webhook dans Workbench, ou utilisez l’API Webhook Endpoints.

Écoutez quelques événements pour terminer les étapes restantes de ce guide. Consultez la section Événements d’abonnement pour plus de détails sur les webhooks spécifiques à l’abonnement.

Maintenant que l’abonnement est actif, fournissez à votre client 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 Subscription, dans lequel un champ status indique si l’abonnement est actif, en retard de paiement ou annulé. Consultez la documentation consacrée au cycle de vie des abonnements pour prendre connaissance de la liste complète des états.

Dans votre gestionnaire de webhooks :

1. Vérifiez l’état de l’abonnement. S’il affiche active, cela signifie que votre client a payé son abonnement.
2. Vérifiez le produit auquel le client s’est abonné et accordez-lui l’accès à votre service. La vérification du produit plutôt que du tarif vous donne 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.id déjà stocké. Vérifiez cet enregistrement au moment de décider des fonctionnalités à activer pour l’utilisateur dans votre application.

L’état d’un abonnement peut changer à tout moment de son cycle de vie, même si votre formulaire d’inscription n’appelle pas directement Stripe. Par exemple, un renouvellement peut échouer en raison d’une carte bancaire expirée, ce qui fait passer l’abonnement à l’état en retard. Ou, si vous implémentez le portail client, un utilisateur peut choisir d’annuler son abonnement sans accéder directement à votre formulaire d’inscription. L’implémentation correcte de votre gestionnaire permet de synchroniser l’état de votre formulaire d’inscription avec celui de Stripe.

Il est courant de laisser aux clients la possibilité d’annuler leur abonnement. Cet exemple vous explique 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 votre back-end, définissez l’endpoint que votre front-end appellera.

# 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 '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

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

Après l’annulation de l’abonnement, mettez à jour votre base de données pour supprimer l’ID de l’abonnement Stripe précédemment sauvegardé, et limitez l’accès à votre service.

Une fois un abonnement annulé, il ne peut plus être réactivé. Collectez dès lors les informations de facturation actualisées de votre client, mettez à jour son moyen de paiement par défaut et créez un nouvel abonnement à partir du 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 modification d’abonnement, tels que les mises à niveau et les annulations. En savoir plus sur les webhooks d’abonnement. Vous pouvez afficher les événements dans le Dashboard ou via l’interface de ligne Stripe de commande.

Pour en savoir plus, consultez la page Tester votre intégration Billing.