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 Stripe CLI. Elle vous permet de tester vos webhooks et d’effectuer des appels API vers Stripe. Dans une section suivante, ce guide vous montre comment utiliser la CLI pour mettre en place un modèle de tarification.

# 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

Permettez à votre client de choisir une offre, puis créez l’abonnement. Dans l’exemple de ce guide, le client choisit entre une offre Basic et une offre Premium.

Sur le front-end, transmettez l’identifiant de prix sélectionné ainsi que l’identifiant d’enregistrement du client au back-end.

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

Dans le back-end, créez l’abonnement avec l’état incomplete en utilisant payment_behavior=default_incomplete. Ensuite, renvoyez le client_secret du premier PaymentIntent de l’abonnement au front-end pour exécuter le paiement. Pour ce faire, développez le confirmation_secret de la dernière facture de l’abonnement.

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

Définissez save_default_payment_method sur on_subscription pour enregistrer le moyen de paiement comme moyen 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

L’abonnement est maintenant inactif et en attente de paiement. L’exemple de réponse ci-dessous met en évidence les champs minimaux à sauvegarder, mais vous pouvez sauvegarder les champs auxquels votre formulaire d’inscription 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 les Stripe Elements pour collecter les détails du paiement et activer l’abonnement. Vous pouvez personnaliser les Elements pour qu’ils correspondent à l’aspect et à la convivialité de votre formulaire d’inscription.

LePayment Element prend en charge Link, les cartes bancaires, le prélèvement automatique SEPA et le prélèvement automatique BECS pour les abonnements. Vous pouvez afficher les moyens de paiement activés et collecter en toute sécurité les informations de paiement en fonction de la sélection de votre client.

Configurer les 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 à la section head de votre fichier HTML. Chargez toujours Stripe.js directement depuis js.stripe.com pour rester conforme aux normes PCI. N’incluez pas ce script dans un lot et n’en hébergez pas de copie.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/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 Payment Element à votre page

Le Payment Element doit avoir un emplacement dédié dans votre page de paiement. Créez un nœud DOM (conteneur) vide avec un identifiant 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>

Après le chargement du formulaire, créez une instance du Payment Element et montez-la dans le nœud DOM du conteneur. Lorsque vous avez créé l’abonnement, vous avez transmis la valeur client_secret au front-end. Passez cette valeur en tant qu’option lorsque vous créez une instance d’Elements.

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

// Set up Stripe.js and Elements to use in the 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 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

Vous pouvez éventuellement effectuer les opérations suivantes :

• Personnalisez le composant Payment Element pour qu’il corresponde 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 pour qu’elle renvoie untoken marchand afin de prendre en charge les paiements récurrents, les recharges automatiques et les paiements différés.

Finaliser le paiement

Utilisez stripe.confirmPayment pour finaliser le paiement à partir des informations du composant Payment Element et activer l’abonnement. Cette opération crée un PaymentMethod, confirme le premier PaymentIntent de l’abonnement incomplet et déclenche un débit. Si une Strong Customer Authentication (SCA) est nécessaire, le Payment Element prend en charge le processus avant de confirmer le PaymentIntent.

Fournissez un return_url pour indiquer où Stripe doit rediriger l’utilisateur après l’exécution du paiement. Il se peut que votre utilisateur soit d’abord redirigé vers un site intermédiaire (par ex. une page d’autorisation bancaire), avant d’être renvoyé vers le return_url. Les paiements par carte bancaire redirigent immédiatement vers le return_url lorsque le paiement est effectué avec succès.

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 is reached only if there's an immediate error when
    // confirming the payment. Show an error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer redirects to your `return_url`. For some payment
    // methods, such as iDEAL, your customer redirects to an intermediate
    // site first to authorize the payment, and then redirects 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. Contrôlez l’état du PaymentIntent pour décider de ce que vous allez montrer à vos clients. Vous pouvez également ajouter vos propres paramètres de requête lorsque vous fournissez le return_url, qui est conservé dans le 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 [immediately succeed or fail][0] upon
  // confirmation, while others 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. Ces événements se déclenchent lorsqu’un état change dans Stripe, par exemple lorsqu’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.

# 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, see 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

Pour la production, configurez 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 d’informations sur les webhooks spécifiques à l’abonnement.

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 Subscription qui contient un champ status indiquant si l’abonnement est actif, en retard ou annulé. Consultez le cycle de vie de l’abonnement pour obtenir la liste complète des états.

Dans votre gestionnaire de webhooks :

1. Vérifiez l’état de l’abonnement. S’il s’agit de active, votre 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 contrôle basé sur le produit, plutôt que sur le prix, vous offre plus de flexibilité si vous devez modifier la tarification ou la période de facturation.
3. Enregistrez lesproduct.id, subscription.id et subscription.status dans votre base de données avec le customer.id que vous avez déjà enregistré. Utilisez cet enregistrement pour déterminer quelles fonctionnalités activer pour l’utilisateur 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 de crédit expirée, ce qui place l’abonnement en état past due. Ou encore, si vous implémentez le portail client, un utilisateur peut annuler son abonnement sans passer par votre application. Une implémentation correcte de votre gestionnaire garantit la synchronisation de l’état de votre application avec Stripe.

Donnez à vos clients la possibilité d’annuler leur abonnement. L’exemple ci-dessous ajoute une option d’annulation directement 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.

# 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 la résiliation de l’abonnement, mettez à jour votre base de données pour supprimer l’identifiant 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 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.