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.
Ou dupliquez l’un de nos exemples de projets :
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
Pour commencer, vous devez créer un compte Stripe. M’inscrire.
Avant d’intégrer le portail client, configurez ses fonctionnalités et adaptez-le à votre marque dans le Dashboard Stripe pour définir les actions que vos utilisateurs peuvent y effectuer. Ses fonctionnalités dépendent de votre catalogue de produits et de vos tarifs. Il existe donc différents paramètres pour les environnements de test et le mode production.
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, revenir à un abonnement inférieur ou modifier les quantités de leur abonnement, vous devez aussi définir un catalogue de produits. Celui-ci doit inclure les produits et tarifs pour lesquels vos clients peuvent opter, ainsi que les abonnements dont ils peuvent modifier les quantités. Consultez le guide 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 les clients définir et modifier leur numéros fiscaux sur le portail client. Stripe Billing ajoute alors ces numéros fiscaux aux factures des clients. Pour activer cette fonctionnalité, 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 les paramètres, vous pouvez afficher un aperçu du portail en cliquant sur le bouton Prévisualiser. 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 en utilisant un client dans un environnement de test. Accédez à un client dans le Dashboard, cliquez sur 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 siteCôté clientCô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_, 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 webhooksCô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 |
|---|---|
É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 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. 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. |
É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 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 | |
| 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_ 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_ 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 de portail : un pour le mode production et un pour chaque environnement de test. Pour vous aider à valider votre intégration, les modifications effectuées dans un mode n’affecte pas votre configuration dans l’autre.