# Intégrer le portail client avec l'API Comment intégrer le portail client à l'aide de l'API Stripe. If your integration uses [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), replace `Customer` and event references in the code examples with the equivalent Accounts v2 API references. For more information, see [Represent customers with Account objects](https://docs.stripe.com/connect/use-accounts-as-customers.md). 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 : 1. [Configurez](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure) les fonctionnalités et l’interface utilisateur (IU) du portail. Pour ce faire, vous pouvez utiliser le Dashboard. 1. [Créez une redirection](https://docs.stripe.com/customer-management/integrate-customer-portal.md#redirect) pour intégrer le portail à votre application. 1. [Écoutez les webhooks](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks) pour recevoir des mises à jour concernant les abonnements et les moyens de paiement de vos clients. 1. [Passez en mode production](https://docs.stripe.com/customer-management/integrate-customer-portal.md#go-live) pour utiliser le portail dans votre environnement de production. Vous avez la possibilité de [personnaliser](https://docs.stripe.com/customer-management/integrate-customer-portal.md#customize) 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](https://dashboard.stripe.com/register/). 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* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) et le mode production, en fonction de votre catalogue de produits et de tarifs. > 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 voulez créer plusieurs configurations du portail pour différents ensembles de clients, ou si vous êtes une plateforme *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) et que vous souhaitez gérer les configurations pour vos comptes connectés, vous pouvez le faire via l’[API](https://docs.stripe.com/api/customer_portal/configurations/object.md) : ```curl curl https://api.stripe.com/v1/billing_portal/configurations \ -u "<>:" \ -d "features[invoice_history][enabled]=true" ``` ### 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](https://docs.stripe.com/products-prices/manage-prices.md#create-product) 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](https://docs.stripe.com/tax.md) 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* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) des clients. Pour autoriser les clients à définir leur numéro fiscal, accédez aux [paramètres du portail client](https://dashboard.stripe.com/settings/billing/portal) et activez **Numéro fiscal**. Pour en savoir plus, consultez la page sur le fonctionnement des numéros fiscaux pour les [abonnements](https://docs.stripe.com/billing/customer/tax-ids.md) et les [factures](https://docs.stripe.com/invoicing/taxes/account-tax-ids.md). Découvrez comment [configurer Stripe Tax](https://docs.stripe.com/tax/set-up.md), [collecter les taxes sur les paiements récurrents](https://docs.stripe.com/billing/taxes/collect-taxes.md), [collecter des taxes dans vos tunnels de paiement personnalisés](https://docs.stripe.com/tax/custom.md#existing-customer) et [définir les taux de taxe des factures et postes de facture](https://docs.stripe.com/tax/invoicing.md). ### 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 : ```html
``` 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](https://docs.stripe.com/api/customer_portal/sessions/create.md), 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`, qui contient l’[URL éphémère](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-url) de la session, avec laquelle vos clients accèdent au portail client. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ --data-urlencode "return_url=https://example.com/account" ``` ## É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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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. Lorsque vos clients mettent à jour leurs informations de facturation dans le portail client, il est important de mettre à jour vos dossiers clients. Écoutez les modifications à l’aide du webhook `customer.updated`. Stripe envoie également des notifications à votre intégration à l’aide de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md) de Stripe pour démarrer, puis écouter les événements décrits ci-dessous. | Événement | Description | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/billing/subscriptions/trials.md) 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](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.deleted) | Écoutez cet événement pour suivre les résiliations d’abonnement. Lorsque vous le recevez, révoquez l’accès du client au produit. Si vous configurez le portail pour résilier les abonnements à la fin d’une période de facturation, écoutez l’événement [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) afin d’être informé des résiliations avant qu’elles ne prennent effet. Pour les abonnements en [mode de facturation](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode) flexible, si `cancel_at` n’est pas `null`, l’abonnement est résilié à la fin de sa période de facturation. Pour les abonnements en mode de facturation classique, vérifiez que `cancel_at_period_end` est défini sur `true`. Si un client change d’avis, il peut réactiver son abonnement avant la fin de la période de facturation. Lorsqu’il le fait, un événement [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) est envoyé. Pour les abonnements en mode de facturation flexible, vérifiez que `cancel_at` est `null` pour confirmer la réactivation. Pour les abonnements en mode de facturation classique, vérifiez que `cancel_at_period_end` est défini sur `false`. | | [payment_method.attached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.attached) | Se produit lorsqu’un client ajoute un moyen de paiement. | | [payment_method.detached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.detached) | Se produit lorsqu’un client supprime un moyen de paiement. | | [customer.updated](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/billing/customer/tax-ids.md). | | [customer.tax_id.deleted](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/billing/customer/tax-ids.md). | | [customer.tax_id.updated](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/billing/customer/tax-ids.md). | | [billing_portal.configuration.created](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.created) | Se produit lorsqu’une configuration est créée. | | [billing_portal.configuration.updated](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.updated) | Se produit lorsqu’une configuration est modifiée. | | [billing_portal.session.created](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-url) 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](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-login_page). - Désactivez l’option **Afficher les données de test** dans le Dashboard. - [Configurez](https://dashboard.stripe.com/settings/billing/portal) le portail en mode production. - Ajoutez vos [webhooks](https://dashboard.stripe.com/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. ## Optional: Lien 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](https://docs.stripe.com/customer-management/portal-deep-links.md). ## Optional: Personnaliser 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](https://docs.stripe.com/api/customer_portal/configurations/object.md) uniquement. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} ``` 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](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant). ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} \ -d on_behalf_of={{CONNECTED_ACCOUNT_ID}} ``` ## Optional: Personnaliser l'image de marque Pour personnaliser le portail : 1. Accédez à la page des [paramètres de la marque](https://dashboard.stripe.com/settings/branding), chargez votre icône ou votre logo et personnalisez les couleurs. 1. Accédez à la page des [paramètres publics du compte](https://dashboard.stripe.com/settings/public) et vérifiez le nom et les informations publiques de votre entreprise.