Créer une intégration pour les abonnements
Créez et gérez des abonnements pour les paiements récurrents.
Apprenez à vendre des abonnements à tarif fixe. Vous apprendrez à utiliser le composant Element Mobile Payment pour créer un formulaire de paiement personnalisé que vous intégrerez à votre application.
Remarque
Si vous vendez des produits ou des services numériques dont l’utilisation a lieu dans votre application (par exemple, des abonnements, des devises de jeu, des niveaux de jeu, l’accès à du contenu premium ou le déverrouillage d’une version complète), vous devez utiliser les API d’achats intégrés d’Apple. Cette règle comporte quelques exceptions : par exemple, les services personnels sur mesure et les applications accessibles dans des régions spécifiques ne sont pas concernés. Pour en savoir plus, consultez les directives de vérification de l’App Store.
Créer votre abonnement
Ce guide vous explique comment :
- Modéliser votre offre en créant un catalogue de produits.
- Créer un processus d’enregistrement pour ajouter des clients.
- Créer des abonnements et collecter les informations de paiement de vos clients.
- Tester et surveiller l’état des paiements et des abonnements.
- Permettre aux clients de modifier leur plan ou d’annuler l’abonnement.
- Découvrez comment utiliser mode de facturation flexible pour accéder à un comportement de facturation amélioré et à des fonctionnalités supplémentaires.
Comment modéliser un abonnement sur Stripe
Les abonnements facilitent votre facturation en créant automatiquement des factures et des PaymentIntents. Afin de créer et d’activer un abonnement, vous devez d’abord créer un objet Product pour modéliser ce que vous vendez, ainsi qu’un objet Price, qui détermine la fréquence et le montant de la facturation. Vous avez également besoin d’un objet Customer pour enregistrer les PaymentMethods utilisés dans le cadre des paiements récurrents.
Définitions des objets API
| Ressource | Définition |
|---|---|
| Customer | Représente un client qui achète un abonnement. Utilisez l’objet Customer associé à un abonnement pour effectuer et suivre ses paiements récurrents et gérer les produits auxquels il est abonné. |
| Entitlement | Représente l’accès d’un client à une fonctionnalité incluse dans un produit de service auquel il est abonné. Lorsque vous créez un abonnement représentant l’achat récurrent d’un produit par un client, un droit d’accès actif est automatiquement créé pour chaque fonctionnalité associée à ce produit. Lorsqu’un client accède à vos services, utilisez ses droits d’accès actifs pour activer les fonctionnalités incluses dans son abonnement. |
| Feature | Représente une fonctionnalité à laquelle vos clients peuvent accéder lorsqu’ils s’abonnent à un produit de service. Vous pouvez inclure des fonctionnalités dans un produit en créant des objets ProductFeatures. |
| Invoice | Relevé des montants dus par un client et qui suit les états des paiements, de l’ébauche initiale au paiement ou à la finalisation. Les abonnements génèrent automatiquement des factures. |
| PaymentIntent | Un moyen de créer des tunnels de paiement dynamiques. Un PaymentIntent suit le cycle de vie du tunnel de paiement d’un client et déclenche des étapes d’authentification supplémentaires lorsque des mandats réglementaires, des règles Radar personnalisées de lutte contre la fraude, ou des moyens de paiement avec redirection l’exigent. Les objets Invoice créent automatiquement des PaymentIntents. |
| PaymentMethod | Les moyens de paiement qu’un client utilise pour payer vos produits. Vous pouvez par exemple enregistrer une carte bancaire dans un objet Customer et l’utiliser pour les paiements récurrents de ce client. Généralement utilisés avec les API Payment Intents ou Setup Intents. |
| Price | Définit le tarif unitaire, la devise et le cycle de facturation d’un produit. |
| Product | Un bien ou un service que votre entreprise vend. Un produit de service peut comporter une ou plusieurs fonctionnalités. |
| ProductFeature | Représente l’inclusion d’une fonctionnalité unique dans un produit unique. Chaque produit est associé à un objet ProductFeature pour chaque fonctionnalité qu’il inclut, et chaque fonctionnalité est associée à un objet ProductFeature pour chaque produit qui l’inclut. |
| Subscription | Représente l’achat récurrent et programmé d’un produit par un client. L’abonnement permet d’encaisser des paiements et de fournir des livraisons répétées ou un accès continu à un produit. |
Voici un exemple de la manière dont les produits, les fonctionnalités et les droits d’accès fonctionnent ensemble. Imaginons que vous créez un service récurrent proposant deux niveaux : un produit standard avec des fonctionnalités de base et un produit Advanced qui ajoute des fonctionnalités étendues.
- Vous créez deux fonctionnalités :
basic_etfeatures extended_.features - Vous créez deux produits :
standard_etproduct advanced_.product - Pour le produit standard, vous créez un objet ProductFeature qui associe
basic_àfeatures standard_.product - Pour le produit avancé, vous créez deux objets ProductFeature : un qui associe
basic_àfeatures advanced_et un qui associeproduct extended_àfeatures advanced_.product
Un client, first_, s’abonne au produit standard. Lorsque vous créez l’abonnement, Stripe crée automatiquement un objet Entitlement qui associe first_ à basic_.
Un autre client, second_, s’abonne au produit avancé. Lorsque vous créez l’objet Subscription correspondant, Stripe crée automatiquement deux objets Entitlement : un qui associe second_ à basic_, et un qui associe second_ à extended_.
Pour savoir quelles fonctionnalités vous devez fournir à un client, récupérez ses droits d’accès actifs ou écoutez l’événement Active Entitlement Summary. Il n’est pas nécessaire de récupérer ses abonnements, produits et fonctionnalités.
Le SDK React Native est disponible en open source et fait l’objet d’une documentation complète. En interne, il utilise des SDK Android et iOS natifs. Pour installer le SDK React Native de Stripe, exécutez l’une des commandes suivantes dans le répertoire de votre projet (selon le gestionnaire de paquets que vous utilisez) :
Ensuite, installez les autres dépendances nécessaires :
- Pour iOS, accédez au directeur ios et exécutez
pod installpour vous assurer que vous installez également les dépendances natives requises. - Pour Android, il n’y a plus de dépendances à installer.
Remarque
Nous vous recommandons de suivre le guide officiel de TypeScript pour ajouter la prise en charge de TypeScript.
Initialisation de Stripe
Pour initialiser Stripe dans votre application React Native, wrappez votre écran de paiement avec le composant StripeProvider ou utilisez la méthode d’initialisation initStripe. Seule la clé publiable de l’API dans publishableKey est nécessaire. L’exemple suivant montre comment initialiser Stripe à l’aide du composant StripeProvider.
Remarque
Utilisez vos clés de test d’API lors de vos activités de test et de développement, et vos clés du mode production pour la publication de votre application.
Installez ensuite l’interface de ligne de commande Stripe. Cette dernière vous permet d’exécuter les tests webhook dont vous avez besoin, et d’exécuter des appels à l’API vers Stripe. Ce guide vous explique dans une section ultérieure comment utiliser l’interface de ligne de commande pour définir un modèle tarifaire.
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 objet Customer pour chaque abonnement. Sur le front-end de votre application, collectez toutes les informations nécessaires sur vos utilisateurs et transmettez-les à votre back-end.
Si vous avez besoin de recueillir une adresse, le composant Address Element vous permet de recueillir l’adresse de livraison ou de facturation de vos clients. Pour plus d’informations sur ce composant, consultez la page consacrée à Address Element.
Sur le serveur, créez l’objet Customer Stripe.
Remarque
Si vous souhaitez afficher le Payment Element sans créer d’abonnement au préalable, consultez Collecter les informations de paiement avant de créer un Intent.
Laissez votre nouveau client choisir une offre, puis créez l’abonnement. Dans ce guide, le client a le choix entre l’option de base et l’option Premium.
Dans votre application, transmettez l’ID du tarif sélectionné et l’ID du dossier client à votre back-end.
Sur votre back-end, créez l’abonnement à l’état incomplete à l’aide de payment_. Renvoyez ensuite le client_ du premier PaymentIntent de l’abonnement vers le front-end pour finaliser le paiement en développant le confirmation_ sur la dernière facture de l’abonnement.
Pour activer comportement d’abonnement amélioré, définissez billing_ sur flexible. Vous devez utiliser Stripe API version 2025-06-30.basil ou une version ultérieure.
Définissez save_default_payment_method sur on_ afin d’enregistrer un moyen de paiement comme moyen de paiement par défaut pour l’abonnement lorsque le paiement aboutit. L’enregistrement d’un moyen de paiement par défaut augmente le taux de réussite des paiements futurs.
Remarque
Si vous utilisez un tarif multidevise, utilisez le paramètre currency pour indiquer à l’abonnement quelle devise utiliser. (Si vous omettez le paramètre currency, l’abonnement utilise la devise par défaut associée au tarif.)
À ce stade, l’abonnement est inactive et en attente de paiement. Voici un exemple de réponse. Les champs à sauvegarder impérativement sont en surbrillance, mais vous devez également sauvegarder tous les éléments auxquels votre application accède fréquemment.
Utilisez la Payment Sheet pour collecter les détails du paiement et activer l’abonnement. Vous pouvez personnaliser Elements pour qu’il corresponde à l’aspect et à la convivialité de votre formulaire d’inscription.
La Payment Sheet collecte en toute sécurité tous les détails nécessaires au paiement pour un large éventail de moyens de paiement. Découvrez les moyens de paiement pris en charge par pour la Payment Sheet et les Abonnements.
Ajouter le composant Payment Element à votre application
Remarque
Cette étape ne montre qu’une seule façon de commencer, mais vous pouvez utiliser n’importe quelle intégration de paiements dans l’application.
Initialiser et présenter le composant Mobile Payment Element à l’aide de la classe PaymentSheet.
Le composant Mobile Payment Element affiche un formulaire qui permet à votre client de sélectionner un moyen de paiement. Le formulaire collecte automatiquement toutes les informations de paiement requises pour le moyen de paiement sélectionné.
Si vous définissez allowsDelayedPaymentMethods sur true, les moyens de paiement à notification différée, comme les comptes bancaires étasuniens, seront acceptés. Pour ces moyens de paiement, l’état final du paiement n’est pas connu une fois le processus du PaymentSheet achevé, et le paiement peut plus tard aboutir comme échouer. Si vous prenez en charge ces types de moyens de paiement, informez votre client que sa commande est confirmée et ne la traitez (en lui expédiant son produit, par exemple) qu’une fois le paiement reçu.
Vous pouvez personnaliser le composant Payment Element afin qu’il corresponde au design de votre application en utilisant la propriété appearance de votre objet PaymentSheet..
Confirmer le paiement
Le composant Mobile Payment Element crée un PaymentMethod et le premier PaymentIntent de l’abonnement incomplet est confirmé, ce qui déclenche le processus de paiement. Si une authentication forte du client (SCA) est requise pour le paiement, le composant Payment Element gère le processus d’authentification avant de confirmer le PaymentIntent.
Lorsqu’un client quitte votre application (par exemple, pour s’authentifier dans Safari ou dans son application bancaire), donnez-lui un moyen de revenir automatiquement dans votre application. De nombreux types de moyens de paiement nécessitent une URL de redirection. Si vous n’en fournissez pas, nous ne pourrons pas présenter à vos utilisateurs les moyens de paiement nécessitant une URL de redirection, même si vous les avez activés.
Pour fournir une URL de redirection :
- Enregistrez une URL personnalisée. Les liens universels ne sont pas pris en charge.
- Configurez votre URL personnalisée.
- Configurez votre composant racine pour qu’il transfère l’URL au SDK de Stripe, comme illustré ci-dessous.
Remarque
Si vous utilisez Expo, définissez votre schéma dans le fichier app..
Définissez aussi la returnURL lorsque vous appelez la méthode initPaymentSheet :
Pour plus d’informations sur les schémas d’URL natifs, consultez la documentation Android et iOS.
Demander un ID de marchand Apple
Pour obtenir un ID de marchand Apple, demandez un nouvel identifiant sur le site Web Apple Developer.
Renseignez le formulaire en indiquant une description et un identifiant. La description n’est destinée qu’à votre propre information et vous pourrez la modifier ultérieurement au besoin. En ce qui concerne l’identifiant, Stripe vous recommande d’utiliser le nom de votre application (par exemple, merchant.).
Créer un nouveau certificat Apple Pay
Créez un certificat permettant à votre application de chiffrer les données de paiement.
Accédez aux paramètres des certificats iOS dans le Dashboard, cliquez sur Ajouter une nouvelle application et suivez le guide.
Téléchargez un fichier CSR (Certificate Signing Request) pour obtenir d’Apple un certificat sécurisé vous autorisant à utiliser Apple Pay.
Un fichier CSR peut émettre exactement un certificat. Si vous changez d’ID de marchand Apple, vous devez accéder aux paramètres des certificats iOS dans le Dashboard pour obtenir un nouveau fichier CSR et un nouveau certificat.
Réaliser une intégration avec Xcode
Ajoutez la fonctionnalité Apple Pay à votre application. Dans Xcode, ouvrez vos paramètres de projet, cliquez sur l’onglet Signature et fonctionnalités, puis ajoutez Apple Pay. Vous serez peut-être alors invité(e) à vous connecter à votre compte développeur. Sélectionnez l’ID du marchand créé plus tôt. Il est désormais possible d’utiliser Apple Pay sur votre application.
Activez la fonctionnalité Apple Pay dans Xcode
Ajouter Apple Pay
Suivi des commandes
Pour ajouter des informations de suivi de commande dans iOS 16 ou les versions ultérieures, configurez une fonction de rappel setOrderTracking. Stripe appelle votre déploiement une fois le paiement effectué, mais avant qu’iOS ne ferme le formulaire de paiement Apple Pay.
Dans votre déploiement de la fonction de rappel setOrderTracking, récupérez les détails de la commande validée sur votre serveur et transmettez-les à la fonction completion indiquée.
Pour en savoir plus sur le suivi des commandes, consultez la documentation d’Apple sur les commandes Wallet.
Afin de compléter votre intégration, vous devez traiter les webhooks envoyés par Stripe. Les webhooks sont des événements qui se déclenchent lorsqu’un état change dans Stripe, par exemple lorsque des abonnements créent de nouvelles factures. Dans votre application, configurez un gestionnaire HTTP de sorte qu’il accepte les requêtes POST contenant l’événement de webhook, et vérifiez la signature de l’événement :
Pendant le développement, utilisez l’interface de ligne de commande de Stripe pour observer les webhooks et les transférer vers votre application. Exécutez la commande suivante dans un nouveau terminal pendant que votre application de développement est en cours d’exécution :
Pour le mode production, définissez une URL d’endpoint de webhook dans le Dashboard, ou utilisez l’API Webhook Endpoints.
Les étapes restantes de ce guide vont vous amener à écouter quelques événements. Pour plus d’informations sur les webhooks spécifiques aux abonnements, consultez notre documentation consacrée aux événements Subscription.
Maintenant que l’abonnement est actif, fournissez à votre client l’accès à votre service. Pour ce faire, écoutez les événements customer., customer. et customer.. Ces événements transmettent un objet Subscription, dans lequel un champ status indique si l’abonnement est actif, en retard de paiement ou annulé. Consultez la documentation consacrée au cycle de vie des abonnements pour prendre connaissance de la liste complète des états.
Dans votre gestionnaire de webhooks :
- Vérifiez l’état de l’abonnement. S’il est
active, cela signifie que votre client a payé son abonnement. - Vérifiez le produit auquel le client s’est abonné et fournissez l’accès à votre service. Le fait de vérifier le produit plutôt que le tarif vous assure une plus grande souplesse si vous devez modifier la tarification ou la fréquence de facturation.
- Sauvegardez les
product.,id subscription.etid subscription.dans votre base de données avec lestatus customer.déjà stocké. Vérifiez ce dossier au moment de décider des fonctionnalités à activer pour l’utilisateur dans votre application.id
L’état d’un abonnement peut changer à tout moment de son cycle de vie, même si votre application n’appelle pas directement Stripe. Par exemple, un renouvellement peut échouer en raison d’une carte expirée, ce qui fait passer l’abonnement à l’état « past due ». Ou, si vous implémentez le portail client, un utilisateur peut choisir d’annuler son abonnement sans accéder directement à votre application. L’implémentation correcte de votre gestionnaire permet de synchroniser l’état de votre application avec celui de Stripe.
Il est courant de laisser aux clients la possibilité d’annuler leur abonnement. Cet exemple vous explique comment ajouter une option d’annulation sur la page des paramètres du compte.
Dans cet exemple, l’ID de l’abonnement est collecté sur votre front-end, mais votre application peut obtenir cette information depuis votre base de données pour votre utilisateur connecté.
Paramètres d’un compte ayant la possibilité d’annuler son abonnement
Sur votre back-end, définissez l’endpoint que votre application appellera.
Votre back-end reçoit un événement customer..
Après l’annulation de l’abonnement, mettez à jour votre base de données pour supprimer l’ID 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.
| Moyen de paiement | Scénario | Méthode de test |
|---|---|---|
| Prélèvement automatique BECS | Le montant dû est réglé par prélèvement automatique BECS. | Remplissez le formulaire à l’aide du numéro de compte 900123456 et du BSB 000000. La confirmation de la demande de PaymentIntent passe d’abord à l’état de traitement, puis à l’état réussi trois minutes plus tard. |
| Prélèvement automatique BECS | Le paiement de votre client échoue avec un code d’erreur account_. | Remplissez le formulaire à l’aide du numéro de compte 111111113 et du BSB 000000. |
| Carte bancaire | Le paiement par carte bancaire aboutit et ne nécessite pas d’authentification. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte 4242 4242 4242 4242 ainsi que la date d’expiration, le CVC et le code postal de votre choix. |
| Carte bancaire | Le paiement par carte bancaire requiert une authentification. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro de carte 4000 0025 0000 3155 ainsi que la date d’expiration, le CVC et le code postal de votre choix. |
| Carte bancaire | La carte est refusée avec un code de refus de type insufficient_. | Remplissez le formulaire de paiement par carte bancaire en saisissant le numéro 4000 0000 0000 9995 ainsi que la date d’expiration, le CVC et le code postal de votre choix… |
| Prélèvement automatique SEPA | Le montant dû est réglé par prélèvement automatique SEPA. | Remplissez le formulaire à l’aide du numéro de compte AT321904300235473204. Le PaymentIntent confirmé passe d’abord à l’état processing, puis à l’état succeeded trois minutes plus tard. |
| Prélèvement automatique SEPA | L’état du PaymentIntent de votre client passe de processing à requires_. | Remplissez le formulaire à l’aide du numéro de compte AT861904300235473202. |
Écouter des événements
Configurez des webhooks afin qu’ils écoutent les événements de modification d’abonnement, tels que les passages à un autre abonnement et les annulations. En savoir plus sur les webhooks d’abonnement. Vous pouvez afficher les événements dans le Dashboard ou à l’aide de la CLI Stripe.
Pour en savoir plus, consultez la page Tester votre intégration Billing.
Pour permettre à vos clients de modifier leur abonnement, collectez l’ID de tarif de l’option vers laquelle ils souhaitent migrer. Envoyez ensuite ce nouvel ID de tarif depuis votre application vers un endpoint du back-end. Dans cet exemple, l’ID de l’abonnement est également transmis, mais vous pouvez le récupérer depuis votre base de données pour votre utilisateur connecté.
Sur votre back-end, définissez l’endpoint que votre front-end appellera et transmettez les ID de l’abonnement et du nouveau tarif. L’abonnement est maintenant Premium et coûte 15 USD par mois au lieu des 5 USD par mois de l’abonnement de base.
Votre application reçoit un événement customer..
Lorsque votre client modifie son abonnement, un réajustement du montant dû, ou calcul au prorata, est souvent effectué. Vous pouvez utiliser l’endpoint permettant la création de l’aperçu de la facture afin d’afficher le montant ajusté à vos clients.
Depuis l’application, transmettez les détails de l’aperçu de la facture à un endpoint du back-end.
Sur votre back-end, définissez l’endpoint que votre front-end appellera.
L’affichage de la marque et des quatre derniers chiffres de la carte de votre client peut aider ce dernier à savoir quelle carte est débitée, ou encore s’il doit mettre à jour son moyen de paiement.
Sur votre front-end, envoyez l’ID du moyen de paiement à un endpoint du back-end qui récupère les informations du moyen de paiement.
Sur votre back-end, définissez l’endpoint que votre application appellera.
Exemple de réponse :
Remarque
Nous vous recommandons d’enregistrer les valeurs paymentMethod. et last4 dans votre base de données, par exemple paymentMethod. sous stripeCustomerPaymentMethodId dans votre collection ou votre tableau users. Vous pouvez également, si vous le souhaitez, enregistrer les valeurs exp_, exp_, fingerprint et billing_. Ceci limitera le nombre d’appels à Stripe, vous garantissant de meilleures performances et évitant de potentielles limitations de débit.
Divulguer Stripe à vos clients
Stripe recueille des informations sur les interactions des clients avec Elements afin de vous fournir des services, de prévenir la fraude et d’améliorer ses services. Cela inclut l’utilisation de cookies et d’adresses IP pour identifier les Elements qu’un client a vus au cours d’une même session Checkout. Vous êtes responsable de la divulgation et de l’obtention de tous les droits et consentements nécessaires pour que Stripe puisse utiliser les données à cette fin. Pour en savoir plus, visitez notre Centre de confidentialité.