Intégrer le portail client avec l'API

Comment intégrer le portail client à l'aide de l'API Stripe.

Le portail client vous permet de fournir à vos clients des fonctionnalités de gestion des abonnements et de facturation, sans devoir les développer vous-même. Une fois que vous aurez configuré et intégré le portail, les clients seront redirigés vers un Dashboard comarqué où ils pourront gérer leur compte à l’aide des fonctionnalités que vous aurez configurées.

Pour intégrer votre application au portail client :

Configurez les fonctionnalités et l’interface utilisateur (IU) du portail. Pour ce faire, vous pouvez utiliser le Dashboard.
Créez une redirection pour intégrer le portail à votre application.
Écoutez les webhooks pour recevoir des mises à jour concernant les abonnements et les moyens de paiement de vos clients.
Passez en mode production pour utiliser le portail dans votre environnement de production.

Vous avez la possibilité de personnaliser des sessions de portail de manière à activer différentes fonctionnalités pour différents clients.

Configurer le portail

Tout d’abord, vous devez créer un compte Stripe.

Avant d’intégrer le portail client, utilisez le Dashboard pour définir les actions que vos utilisateurs peuvent y effectuer. Choisissez vos paramètres pour les environnements de test et le mode production, en fonction de votre catalogue de produits et de tarifs.

Erreur fréquente

Si vous utilisez le portail client avec Stripe Connect, veillez à configurer le portail client pour la plateforme, et non pour un compte connecté.

Si vous souhaitez créer plusieurs configurations de portail pour différents ensembles de clients, ou si vous êtes une plateforme Connect et souhaitez gérer les configurations de vos comptes connectés, vous pouvez le faire en utilisant l’API :

Définir un catalogue de produits

Si vous autorisez les clients à passer à un abonnement supérieur ou inférieur, ou à modifier les quantités relatives à leurs abonnements, vous devez définir un catalogue de produits. Celui-ci inclut les produits et tarifs pour lesquels vos clients peuvent opter, ainsi que les abonnements dont ils peuvent ajuster les quantités. Consultez la section dédiée à la création d’un produit pour en savoir plus sur la création de produits et de tarifs. Si vous utilisez le portail client uniquement à des fins de facturation, vous n’avez pas besoin de définir un catalogue de produits.

Le portail affiche les attributs suivants de votre catalogue de produits :

Nom et description du produit : ces attributs sont modifiables dans le Dashboard et l’API.
Restrictions de quantité par produit : ces attributs sont modifiables dans le Dashboard.
Devise, période de facturation et montant du tarif : ces attributs sont immuables et peuvent uniquement être définis au moment de leur création dans le Dashboard ou l’API.

Activer la collecte du numéro fiscal

Si vous utilisez Stripe Tax pour collecter automatiquement les taxes sur les abonnements ou factures, vous pouvez laisser vos clients définir et modifier leurs numéros fiscaux sur le portail client. Stripe Billing ajoute les numéros fiscaux aux factures des clients. Pour autoriser les clients à définir leur numéro fiscal, accédez aux paramètres du portail client et activez Numéro fiscal. Pour en savoir plus, consultez la page sur le fonctionnement des numéros fiscaux pour les abonnements et les factures.

Découvrez comment configurer Stripe Tax, collecter les taxes sur les paiements récurrents, collecter des taxes dans vos tunnels de paiement personnalisés et définir les taux de taxe des factures et postes de facture.

Prévisualiser et tester

Lorsque vous configurez vos paramètres, cliquez sur Prévisualiser pour prévisualiser le portail. Cela lancera une version en lecture seule du portail vous permettant de visualiser la manière dont vos clients peuvent gérer leurs abonnements et informations de facturation.

Après avoir enregistré vos paramètres, vous pouvez lancer le portail et le tester avec un client du environnement de test. Accédez à un client dans le Dashboard et cliquez sur le bouton Actions, puis sélectionnez Ouvrir le portail client.

La prévisualisation du portail en lecture seule n’est disponible que lorsque votre Dashboard se trouve dans un environnement de test. Si vous ne parvenez pas à prévisualiser et tester le portail, vérifiez vos paramètres pour vous assurer que votre configuration est enregistrée dans un environnement de test. Pour que la prévisualisation et les tests fonctionnent, vous devez également disposer d’autorisations en écriture dans le Dashboard.

Implémenter une redirection sur votre site
Côté client
Côté serveur

Une session de portail est le point d’entrée dans le portail client. Elle fournit un lien unique et temporaire vers le portail. Lorsqu’un client souhaite gérer sa facturation, créez une nouvelle session du portail et redirigez-le vers l’url de la session.

Sur votre site, ajoutez un bouton sur lequel les clients peuvent cliquer pour accéder au portail. Utilisez une requête POST pour créer une session du portail :

<form method="POST" action="/create-customer-portal-session">
  <button type="submit">Manage billing</button>
</form>

Ajoutez ensuite un endpoint qui crée une session de portail et redirige vos clients. Assurez-vous d’authentifier les clients sur votre site avant de créer des sessions pour eux. Pour créer une session, vous avez besoin de l’ID du client et d’une URL return_url, qui est obligatoire lorsque aucune URL de retour par défaut n’est définie dans la configuration du Dashboard.

Lorsque vous créez une session de portail, Stripe renvoie l’objet portal session object, qui contient l’URL éphémère de la session, avec laquelle vos clients accèdent au portail client.

Écouter les webhooks
Côté serveur

Quand un client passe à une offre inférieure ou supérieure, ou annule son abonnement, vous devez vous assurer qu’il reçoit uniquement les produits ou services auquel il s’est abonné. Stripe envoie des notifications à votre intégration à l’aide de webhooks pour vous prévenir de ces modifications. Dans l’objet Event, observez l’ID de l’abonnement ou du client pour déterminer à quel client s’applique l’événement.

Stripe envoie également des notifications à votre intégration à l’aide de webhooks quand une facture est payée. Dans l’objet Event, observez l’ID de la facture ou du client pour déterminer à quel client s’applique l’événement.

Si vous n’avez pas encore configuré d’endpoint de webhook avec Stripe, vous pouvez utiliser la documentation sur les webhooks de Stripe pour démarrer, puis écouter les événements décrits ci-dessous.

Événement	Description
customer.subscription.updated	Écoutez cet événement pour surveiller les passages à un abonnement inférieur ou supérieur. Pour les passages à une offre supérieure, consultez l’attribut `subscription.items.data[0].price` de l’objet Subscription pour retrouver le tarif souscrit par le client, puis accordez-lui un accès au nouveau produit. Pour les passages à une offre inférieure, consultez le même attribut et réajustez ou révoquez l’accès en conséquence. Lorsqu’un client bénéficiant d’une période d’essai utilise le portail pour passer à un abonnement supérieur ou inférieur, la période d’essai prend fin dès que le client passe au nouveau tarif.
customer.subscription.updated	Écoutez cet événement pour suivre les changements de quantité des abonnements. Lorsque vous recevez cet événement, consultez l’attribut `subscription.items.data[0].quantity` pour retrouver la quantité d’abonnements à laquelle le client a souscrit. Puis validez cette nouvelle quantité d’abonnements et accordez l’accès correspondant à votre client.
customer.subscription.deleted	Écoutez cet événement pour suivre les annulations d’abonnement. Lorsque vous recevez cet événement, révoquez l’accès du client. Si vous configurez le portail de manière à annuler les abonnements à la fin de la période de facturation, écoutez l’événement customer.subscription.updated pour être informé des annulations à l’avance. Si `cancel_at_period_end` est `true`, l’abonnement sera annulé à la fin de sa période de facturation. Si un client revient sur sa décision, il peut réactiver son abonnement avant la fin de la période de facturation. Lorsqu’il effectue cette action, un événement customer.subscription.updated est envoyé. Vérifiez que `cancel_at_period_end` est `false` pour confirmer la réactivation de son abonnement.
payment_method.attached	Se produit lorsqu’un client ajoute un moyen de paiement.
payment_method.detached	Se produit lorsqu’un client supprime un moyen de paiement.
customer.updated	Consultez l’attribut `invoice_settings.default_payment_method` pour retrouver le nouveau moyen de paiement par défaut sélectionné par le client. Si certains de vos abonnements sont configurés pour ignorer le moyen de paiement par défaut des clients, ceux-ci peuvent supprimer cette configuration à leur niveau. Pour vérifier qu’elle a bien été supprimée, consultez l’attribut `default_payment_method` quand vous recevez cet événement. Utilisez ce webhook pour mettre à jour toutes les informations pertinentes dans votre base de données. Toutes les modifications doivent être traitées uniquement comme des modifications d’informations de facturation. N’utilisez pas l’adresse e-mail de facturation du client comme identifiant de connexion.
customer.tax_id.created	Se produit lorsque des clients gèrent leurs numéros fiscaux. Stripe peut valider certains types de numéros fiscaux. Pour en savoir plus, consultez le guide dédié aux numéros fiscaux.
customer.tax_id.deleted	Se produit lorsque des clients gèrent leurs numéros fiscaux. Stripe peut valider certains types de numéros fiscaux. Pour en savoir plus, consultez le guide dédié aux numéros fiscaux.
customer.tax_id.updated	Écoutez cet événement pour obtenir les mises à jour de validation concernant les numéros fiscaux des clients. Pour en savoir plus, consultez le guide consacré aux numéros fiscaux.
billing_portal.configuration.created	Se produit lorsqu’une configuration est créée.
billing_portal.configuration.updated	Se produit lorsqu’une configuration est modifiée.
billing_portal.session.created	Se produit lorsqu’une session de portail est créée.

Passer en production

Veillez à tester le portail avant de l’activer en mode production. Au moment de passer en mode production :

Quand vous créez une session de portail, Stripe renvoie l’objet portal session, qui contient l’URL éphémère de la session avec laquelle vos clients peuvent accéder au portail client. Vous pouvez également créer un lien à partager pour chaque configuration du portail avec le paramètre login_page.

Désactivez l’option Afficher les données de test dans le Dashboard.
Configurez le portail en mode production.
Ajoutez vos webhooks en mode production.

Stripe gère plusieurs ensembles distincts de configurations du portail : l’un pour le mode production, l’autre pour environnement de test. Pour vous aider dans votre intégration, les modifications effectuées dans un mode n’ont pas d’impact sur l’autre mode.

FacultatifLien profond vers des pages spécifiques

Il se peut que vous souhaitiez simplifier les actions de vos clients et personnaliser davantage les flux entre votre propre application et Stripe. Les liens profonds du portail client vous permettent de vous connecter directement à une page contenant l’action à effectuer, mais également de personnaliser le comportement de redirection une fois l’action effectuée par votre client. En savoir plus sur l’utilisation des liens profonds du portail client.

FacultatifPersonnaliser une session du portail
Côté serveur

Il se peut que vous souhaitiez activer un ensemble différent de produits, de tarifs ou de fonctionnalités dans le portail pour différents groupes de clients. Pour appliquer une configuration spécifique à une session de portail, définissez-la en tant que remplacement lors du lancement du portail. Sinon, la configuration par défaut sera appliquée.

Le Dashboard prend en charge la création et la modification de la configuration par défaut. Vous pouvez gérer les autres configurations à l’aide de l’API uniquement.

Si vous êtes une plateforme Connect, vous pouvez spécifier l’attribut on_behalf_of au lancement du portail. Ainsi, la marque, le logo et le nom de l’entreprise affichés dans la session du portail reflèteront le compte on_behalf_of. De plus, le portail n’affichera que les abonnements et les factures du compte on_behalf_of spécifié. Pour en savoir plus, consultez la documentation dédiée à l’attribut on_behalf_of.

FacultatifPersonnaliser l'image de marque

Pour personnaliser le portail :

Accédez à la page des paramètres de la marque, chargez votre icône ou votre logo et personnalisez les couleurs.
Accédez à la page des paramètres publics du compte et vérifiez le nom et les informations publiques de votre entreprise.