# Proposez la gestion des abonnements sur iOS à l’aide d’une page de portail client Configurez un portail client et ouvrez-le dans un navigateur à partir de votre application. Pour les produits et contenus numériques, y compris les abonnements, vendus aux États-Unis ou dans l’Espace économique européen (EEE), votre application peut accepter Apple Pay en redirigeant le client vers une page de paiement externe. Ce guide décrit comment configurer un [portail client](https://docs.stripe.com/customer-management.md) pour la gestion des abonnements et rediriger vos clients vers ce portail depuis votre application. ![Paiement ponctuel](https://b.stripecdn.com/docs-statics-srv/assets/subscriptions_hero.647ac1dba5270dbf75e15c456c6bcf0d.png) Lien vers un site externe pour gérer les abonnements et les moyens de paiement ## Ce que vous allez créer > Ce guide décrit uniquement la gestion des abonnements. Si vous configurez des achats d’abonnements, consultez [Accepter des paiements pour des biens numériques sur iOS avec une page de paiement préconfigurée](https://docs.stripe.com/mobile/digital-goods/checkout.md). Ce guide vous explique comment : - Configurez une page de portail client que vos clients pourront utiliser pour gérer leurs abonnements - Utilisez les *liens universels* (Use Universal links on iOS and macOS to link directly to in-app content. They're standard HTTPS links, so the same URL works for your website and your app) pour rediriger les utilisateurs vers votre application à partir du portail client - Écoutez les *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) pour mettre à jour l’état de l’abonnement de votre client ## Ce qui n’est pas couvert Ce guide vous explique comment configurer un [portail client](https://docs.stripe.com/customer-management.md) Stripe et y accéder depuis votre application. Il ne couvre pas : - **Achats d’abonnements** : Afin d’utiliser Stripe Checkout pour vendre des biens et des abonnements dans l’application, consultez la page [Accepter des paiements pour des biens numériques sur iOS avec une page de paiement préconfigurée](https://docs.stripe.com/mobile/digital-goods/checkout.md). - **Authentification de l’utilisateur** : Si vous ne disposez pas encore d’un fournisseur d’authentification, vous pouvez faire appel à un tiers (par exemple, avec l’option [Se connecter avec Apple](https://developer.apple.com/sign-in-with-apple/) ou [Authentification Firebase](https://firebase.google.com/docs/auth)). - **Achats intégrés natifs** : Pour implémenter des achats dans l’application avec StoreKit, consultez le [guide d’Apple sur les achats intégrés à l’application](https://developer.apple.com/in-app-purchase/). ## 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. ## Configurer Stripe [Côté serveur] ### Côté serveur #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` Installez ensuite l’interface de ligne de commande Stripe. L’interface de ligne de commande vous permet d’exécuter les tests de [webhook](https://docs.stripe.com/webhooks.md#test-webhook) dont vous avez besoin. Pour davantage d’options d’installation, consultez la page consacrée à l’[interface de ligne de commande Stripe](https://docs.stripe.com/stripe-cli.md). ### Côté client Le [SDK iOS de Stripe](https://github.com/stripe/stripe-ios) est disponible en open source et [fait l’objet d’une documentation complète](https://stripe.dev/stripe-ios/index.html). Il est également compatible avec les applications prenant en charge iOS 13 et les versions ultérieures. #### Swift Package Manager Pour installer le SDK, veuillez suivre les étapes ci-dessous : 1. Dans Xcode, sélectionnez **File** > **Add Package Dependencies…** puis saisissez `https://github.com/stripe/stripe-ios-spm` en tant qu’URL du référentiel. 1. Sélectionnez le dernier numéro de version, visible sur notre [page des versions](https://github.com/stripe/stripe-ios/releases). 1. Ajoutez le produit **StripePaymentSheet** à la [cible de votre application](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app). #### CocoaPods 1. Si vous ne l’avez pas encore fait, installez la version la plus récente de [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 1. Si vous n’avez pas de fichier [Podfile](https://guides.cocoapods.org/syntax/podfile.html), exécutez la commande suivante pour en créer un : ```bash pod init ``` 1. Ajoutez cette ligne à votre `Podfile` : ```podfile pod 'StripePaymentSheet' ``` 1. Exécutez la commande suivante : ```bash pod install ``` 1. À partir de maintenant, n’oubliez pas d’utiliser le fichier .xcworkspace au lieu du fichier .xcodeproj pour ouvrir votre projet dans Xcode. 1. Pour mettre à jour ultérieurement le SDK vers la version la plus récente, il vous suffit d’exécuter : ```bash pod update StripePaymentSheet ``` #### Carthage 1. Si vous ne l’avez pas encore fait, installez la version la plus récente de [Carthage](https://github.com/Carthage/Carthage#installing-carthage). 1. Ajoutez cette ligne à votre `Cartfile` : ```cartfile github "stripe/stripe-ios" ``` 1. Suivez les [instructions d’installation de Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Veillez à intégrer tous les cadres requis listés [ici](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking). 1. Pour mettre à jour ultérieurement le SDK vers la version la plus récente, exécutez la commande suivante : ```bash carthage update stripe-ios --platform ios ``` #### Cadre manuel 1. Accédez à notre [page des versions GitHub](https://github.com/stripe/stripe-ios/releases/latest), puis téléchargez et décompressez **Stripe.xcframework.zip**. 1. Faites glisser **StripePaymentSheet.xcframework** vers la section **Embedded Binaries (Fichiers binaires incorporés)** des paramètres **General (Général)** de votre projet Xcode. Veillez à sélectionner **Copy items if needed (Copier les éléments si nécessaire)**. 1. Répétez l’étape 2 pour tous les cadres requis listés [ici](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking). 1. À l’avenir, pour mettre à jour vers la version la plus récente de notre SDK, répétez les étapes 1 à 3. > Pour obtenir de plus amples informations sur la version la plus récente du SDK et ses versions antérieures, consultez la page des [versions](https://github.com/stripe/stripe-ios/releases) sur GitHub. Pour recevoir une notification lors de la publication d’une nouvelle version, [surveillez les versions](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) à partir du référentiel. Vous devez également définir votre [clé publiable](https://dashboard.stripe.com/apikeys) afin que le SDK puisse effectuer des appels à l’API vers Stripe. Pour commencer rapidement, vous pouvez coder cela en dur côté client pendant l’intégration, mais récupérer la clé publiable sur votre serveur en mode production. ```swift // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys STPAPIClient.shared.publishableKey = "<>" ``` ## Créer une session de portail [Côté serveur] Lorsqu’un client souhaite apporter des changements à son abonnement, générez une URL pour la page du portail à l’aide de son ID client Stripe via l’API de session du portail. #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); app.get('/customer_portal_url', async (req, res) => { // Replace this with your actual customer lookup logic const customerId = 'cus_...'; // Get this from your database const billingSession = await stripe.billingPortal.sessions.create({ customer: customerId, return_url: 'https://example.com/portal_redirect', }); res.json({ url: billingSession.url }); }) ``` ## Configurer des liens universels [Côté client] [Côté serveur] Les *liens universels* (Use Universal links on iOS and macOS to link directly to in-app content. They're standard HTTPS links, so the same URL works for your website and your app) permettent au portail client d’établir un lien profond vers votre application. Pour configurer un lien universel : 1. Ajoutez un fichier `apple-app-site-association` à votre domaine. 1. Ajoutez un droit de domaine associé à votre application. 1. Ajoutez une page de renvoi pour les URL de redirection de votre portail. #### Définissez les domaines associés Ajoutez un fichier à votre domaine sur **.well-known/apple-app-site-association** pour définir les URL que votre application peut gérer. Ajoutez l’ID d’application avec votre ID d’équipe que vous pourrez trouver sur la [page d’abonnement du portail développeur d’Apple](https://developer.apple.com/account). ```json { "applinks": { "apps": [], "details": [ { "appIDs": [ "A28BC3DEF9.com.example.MyApp1", "A28BC3DEF9.com.example.MyApp1-Debug" ], "components": [ { "/": "/checkout_redirect*", "comment": "Matches any URL whose path starts with /checkout_redirect" } ] } ] } } ``` Vous devez traiter le fichier avec le type MIME `application/json`. Utilisez `curl -I` pour confirmer le type de contenu. ```bash curl -I https://example.com/.well-known/apple-app-site-association ``` Pour en savoir plus, consultez la page d’Apple relative aux [domaines associés pris en charge](https://developer.apple.com/documentation/xcode/supporting-associated-domains). #### Ajouter un droit de domaine associé à votre application 1. Ouvrez le volet **Signatures et fonctionnalités** de la cible de votre application. 1. Cliquez sur **+ Fonctionnalité**, puis sélectionnez **Domaines associés**. 1. Ajoutez une entrée pour `applinks:example.com` à la liste **Domaines associés**. Pour en savoir plus sur les liens universels, consultez la page d’Apple sur les [liens universels pour les développeurs](https://developer.apple.com/ios/universal-links/). Bien qu’iOS intercepte les liens vers les URL définies dans votre fichier `apple-app-site-association`, il se peut que la redirection ne parvienne pas à ouvrir votre application. Veillez à créer une page de renvoi au niveau de votre `return_url`. Par exemple, vous pouvez [définir un schéma d’URL personnalisé pour votre application](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) et l’utiliser pour créer un lien de retour en cas d’échec du lien universel. ## Ouvrir le portail client dans Safari [Côté client] Ajoutez un bouton pour ouvrir le portail client dans votre application. Ce bouton : 1. Appelle votre endpoint côté serveur pour créer une session de portail. 1. Renvoyez l’URL de la page du portail au client. 1. Ouvrez l’URL dans Safari. ```swift import Foundation import SwiftUI import StoreKit struct SubscriptionManagementView: View { @EnvironmentObject var myBackend: MyServer var body: some View { // Check if payments are blocked by Parental Controls on this device. if !SKPaymentQueue.canMakePayments() { Text("Payments are disabled on this device.") } else { Button { myBackend.createCustomerPortalSession { url in UIApplication.shared.open(url, options: [:], completionHandler: nil) } } label: { Text("Manage subscriptions") }.onOpenURL { url in // Handle the universal link from the customer portal. // Implement any necessary behavior, such as refreshing the customer's subscription status. } } } } ``` ## Gérer les modifications apportées à l’état de l’abonnement des clients [Côté serveur] Lorsque les clients modifient l’état de leur abonnement via le portail client, Stripe vous envoie des *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests), tels que `customer.subscription.created`, `customer.subscription.deleted` et `customer.subscription.updated`. Pour obtenir la liste complète des événements et les informations les concernant, consultez la page [Utiliser des webhooks avec des abonnements](https://docs.stripe.com/billing/subscriptions/webhooks.md). Assurez-vous de gérer tous les événements nécessaires pour surveiller avec précision les états des abonnements que vous avez configurés. Pour tester votre intégration, vous pouvez surveiller les événements dans le [Dashboard](https://dashboard.stripe.com/events) ou utiliser l’[interface de ligne de commande Stripe](https://docs.stripe.com/webhooks.md#test-webhook). En production, configurez un endpoint de webhook et abonnez-vous aux types d’événements pertinents. Si vous ne connaissez pas votre clé `STRIPE_WEBHOOK_SECRET`, cliquez sur le lien du [webhook](https://dashboard.stripe.com/webhooks) dans le Dashboard pour l’afficher. #### Node.js ```javascript const express = require('express'); const app = express(); // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')('') app.post('/webhook', async (req, res) => { let data; let eventType; // Check if webhook signing is configured. const webhookSecret = "{{STRIPE_WEBHOOK_SECRET}}" // Exemple : whsec_c7681Dm if (webhookSecret) { // Retrieve the event by verifying the signature using the raw body and secret. let event; let signature = req.headers["stripe-signature"]; try { event = stripe.webhooks.constructEvent( req.body, signature, webhookSecret ); } catch (err) { console.log(`⚠️ Webhook signature verification failed.`); return res.sendStatus(400); } // Extract the object from the event. data = event.data; eventType = event.type; } else { // Webhook signing is recommended, but if the secret is not configured in `config.js`, // retrieve the event data directly from the request body. data = req.body.data; eventType = req.body.type; } switch (eventType) { case 'customer.subscription.created': { const subscription = event.data.object; const customerId = subscription.customer; myUserDB.setUserSubscriptionIsActive(customerId, true); break; } case 'customer.subscription.deleted': { const subscription = event.data.object; const customerId = subscription.customer; myUserDB.setUserSubscriptionIsActive(customerId, false); break; } // Add other relevant event types as needed } res.sendStatus(200); // Acknowledge receipt of the webhook }) ``` ## Optional: Lien profond vers des pages spécifiques Vous pouvez personnaliser davantage les workflows 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). ## See also - [Portail client en libre-service](https://docs.stripe.com/customer-management.md) - [Cycle de vie d’un abonnement](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) - [Tester des abonnements](https://docs.stripe.com/billing/testing.md)