Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous

API et utilisation avancée

Découvrez des stratégies avancées d'utilisation des horloges de simulation dans le Dashboard et l'API.

Vous pouvez exécuter une simulation indépendamment d’un abonnement pour effectuer des simulations avancées. Dans ce scénario, vous créez d’abord la simulation, puis vous y ajoutez différents cas de test.

Vous n’êtes pas prêt(e) à tester une intégration complète ? Consultez notre guide pour effectuer des simulations sur des abonnements.

Suivez ces étapes pour commencer à utiliser des horloges de simulation :

  1. Créer une simulation
  2. Configurer votre simulation
  3. Avancer la date et l’heure
  4. Observez et traitez les modifications
  5. Modifiez la simulation
  6. Supprimer la simulation

Vous pouvez avancer la date et l’heure, observer les changements et mettre à jour la simulation autant que nécessaire pour tester différents cas.

Créer une simulation et définir sa date et son heure

Une simulation repose sur une horloge comme objet, vous permettant de vous référer à l’heure de cette horloge de simulation. Pour lancer une simulation, créez une horloge et définissez la date figée, qui sert de point de départ à vos tests. La date figée peut être positionnée dans le passé ou dans le futur, mais une fois configurée, elle ne peut évoluer que vers l’avant.

Créez un environnement de test pour commencer la simulation.

  1. Dans l’onglet Facturation, accédez à la section Abonnements.
  2. Cliquez sur le lien Simulations dans la bannière.
  3. Cliquez sur Créer une simulation.
  4. Dans la fenêtre modale Créer une simulation, donnez un nom à votre simulation. Il peut s’agir d’un nom résumant l’objectif de la simulation, par exemple Annual renewal (renouvellement annuel) ou Free trial (essai gratuit).
  5. Définissez la date figée pour la simulation.

Configurer votre simulation

Ensuite, configurez le cas de test à simuler. Vous devez d’abord créer un client, puis son abonnement.

Afin de créer un client pour votre simulation via le Dashboard :

  1. Accédez à la page Simulations et recherchez votre simulation.
  2. Cliquez sur Ajouter > Ajouter un client.

Vous ne pouvez pas sélectionner des clients existants pendant les simulations. Vous pouvez ajouter jusqu’à trois nouveaux clients à chaque simulation.

Vous pouvez éventuellement renseigner d’autres propriétés disponibles pour le client, comme son nom, son e-mail et ses informations de facturation, mais aucune n’est obligatoire. Pour certaines simulations, comme le test des périodes d’essai gratuites, vous pouvez choisir de ne pas collecter d’informations de facturation au préalable.

Vous pouvez ensuite créer jusqu’à trois abonnements ou planifications d’abonnement pour votre client. Pour créer un abonnement au nom de votre client via le Dashboard :

  1. Accédez à la page Simulations et recherchez la simulation.

  2. Cliquez sur Ajouter > Ajouter un abonnement. Sélectionnez votre client ou recherchez-le à l’aide du menu déroulant. Vous pouvez également ajouter le client à un abonnement via la page du client, en cliquant sur Actions > Créer un abonnement.

  3. Sélectionnez un produit et un tarif récurrents dans la section Tarifs.

  4. Pour la Planification d’abonnement, définissez la date de début et de fin de l’abonnement et le moment où la période de facturation doit commencer.

  5. Choisissez une méthode d’encaissement :

    • Sélectionnez Débiter automatiquement un moyen de paiement enregistré si vous souhaitez débiter votre client au début de la période de facturation.
    • Sélectionnez Envoyer la facture au client par e-mail pour paiement manuel si vous souhaitez facturer votre client à terme échu.

  6. Cliquez sur Démarrer l’abonnement test pour démarrer l’abonnement et la période de facturation.

Le client et l’abonnement sont associés à la simulation que vous avez créée à la première étape.

Avancer la date et l'heure de la simulation

Après avoir créé une simulation et configuré votre cas de test, avancez le temps simulé. La première fois, le temps avance à partir de la date initiale figée définie au départ. L’avancement du temps permet d’observer le fonctionnement de votre intégration lorsque des abonnements se terminent, se renouvellent ou changent d’état, par exemple lors du passage d’une période d’essai gratuite à un abonnement payant.

Configurez l’avancement du temps par intervalles de deux unités au maximum. La longueur de l’intervalle dépend de la période de service la plus courte associée à l’abonnement, définie par le tarif récurrent. Par exemple, pour un abonnement mensuel, l’avancement peut être effectué sur deux mois au maximum à chaque fois. Si vous n’avez pas configuré d’abonnements ou de planifications d’abonnement, vous pouvez avancer le temps jusqu’à deux ans à partir de la date initiale figée.

Pour avancer la date et l’heure via le Dashboard :

  1. Accédez à la page Simulations et recherchez votre simulation.

  2. Cliquez sur Avancer la date et l’heure.

  3. Utilisez la fenêtre modale du calendrier pour sélectionner la date à laquelle avancer l’horloge.

  4. Cliquez sur Avancer.

Surveiller et gérer les modifications

Après une requête API ou une opération effectuée dans le Dashboard, l’avancement jusqu’à l’heure définie peut prendre quelques secondes. Pour détecter le changement d’état de la simulation, vous pouvez écouter les notifications d’événements via des webhooks ou interroger l’objet horloge de simulation. Le Dashboard reflète également les changements.

Par exemple, vous pouvez consulter la page Factures pour vérifier si une facture a été créée ou réglée pour votre abonnement.

Si vous utilisez des webhooks, écoutez les notifications d’événements suivantes. Avant de passer au mode production, pensez à vérifier que votre intégration est capable de gérer les notifications d’événements de facturation autres que celles listées ci-dessous.

ÉvénementDescription
test_helpers.test_clock.advancingL’horloge a commencé à avancer mais n’a pas atteint la date et l’heure spécifiées.
test_helpers.test_clock.readyL’horloge a atteint à la date et à l’heure spécifiées.

Pour interroger l’état de horloge de simulation, récupérez-la par ID afin d’examiner son status.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:"

Modifier la simulation

Vous pouvez continuer à apporter des changements à votre simulation et à avancer l’horloge pour différentes simulations, par exemple pour :

Après chaque modifications, observez à nouveau les changements survenus. Réitérez l’opération autant de fois que votre cas de test l’exige.

Supprimer une simulation

Les simulations sont automatiquement supprimées 30 jours après leur création. Vous pouvez également les supprimer lorsque vos tests sont terminés pour garder un environnement de test propre.

Pour supprimer une simulation ainsi que l’ensemble de ses objets de test associés via le Dashboard :

  1. Accédez à la page simulations et recherchez votre simulation.
  2. Cliquez sur Terminer la simulation.
  3. Dans la fenêtre modale de confirmation, cliquez sur Terminer.

La suppression de la simulation supprime aussi les clients de test associés à l’horloge de simulation et annule leurs abonnements. Les simulations sont uniquement disponibles dans l’environnement de test, vous ne pouvez pas supprimer d’objets en production lorsque vous supprimez une horloge de simulation.

Cas d’usage

Dans chaque cas, commencez par créer une nouvelle simulation :

  1. Créer une simulation
  2. Configurer votre simulation
  3. Avancer la date et l’heure
  4. Observez et traitez les modifications
  5. Modifiez la simulation

Tester les renouvellements d’abonnements

Imaginons que vous souhaitiez vérifier le renouvellement correct d’un abonnement à 50 EUR par mois :

  • Créez une nouvelle simulation et définissez son paramètre frozen_time sur le 1er janvier.
  • Ajoutez un client et associez-y un moyen de paiement :

Pour associer un moyen de paiement à un client dans le Dashboard :

  1. Depuis la page de compte du client, cliquez sur **Ajouter > Ajouter une carte ** dans la section Moyens de paiement.
  2. Saisissez les informations de paiement. Dans ce cas, utilisez la carte de test .
  3. Dans la boîte de dialogue, cliquez sur Ajouter une carte.

  • Quand vous avez ajouté un moyen de paiement à votre client, créez-lui un abonnement de 50 EUR/mois. Ce faisant, la facture de 50 EUR est payée automatiquement et l’abonnement passe à l’état active.

  • Avancez la date au 1er février pour voir qu’une facture de 50 EUR est créée. Par défaut, la facture à l’état de draft pendant une heure.

  • Avancez l’horloge d’une heure pour vérifier que la facture a bien été finalisée et payée automatiquement.

Tester un changement d’abonnement en cours de cycle avec calcul au prorata

Imaginons que vous disposiez de deux produits. L’un coûte 50 EUR par mois (offre de base) et l’autre 100 EUR par mois (offre premium). Vous pouvez tester les proratas lorsqu’un client met à niveau son offre de base vers l’offre premium en cours de période de facturation. Pour simuler cette situation :

  • Créez une simulation et définissez le paramètre frozen_time sur le 1er janvier.
  • Créez un client et ajoutez son moyen de paiement. Ici, utilisez la carte de test .
  • Créez un abonnement à ‘basic plan’ pour 50 EUR/mois. Vous pourrez alors observer qu’une facture de 50 EUR/mois a été créée, finalisée et payée automatiquement.
  • Avancez la date de deux semaines. Ici, nous définirons la date sur le 16 janvier.
  • Passez à l’abonnement ‘premium plan’, de 100 EUR/mois :

Pour passer à un abonnement supérieur via le Dashboard :

  1. Depuis la page de compte du client ou la page des détails de l’abonnement, cliquez sur le menu déroulant () associé à un abonnement, puis sur Mettre à jour l’abonnement.
  2. Effectuez les modifications souhaitées.
  3. Cliquez sur Mettre à jour l’abonnement dans le coin supérieur droit pour appliquer les modifications.

  • Après le passage à un abonnement supérieur, l’événement webhook customer.subscription.updated est créé.

  • Les postes de facture en attente sont aussi créés pour les calculs au prorata. Vous remarquerez un prorata négatif de -25 EUR correspondant à la période non-consommée du ‘basic plan’, et un prorata positif de 50 EUR pour la consommation du ‘premium plan’ correspondant à la moitié du mois restant. À ce stade, aucune facture n’a été générée.

  • Avancez la date de deux semaines. Dans ce cas, nous réglerons la date au 1er février. Vous remarquerez que l’abonnement a effectué son cycle. Une facture a été générée à l’état draft. Elle inclut les postes de poste de facture, y compris un prorata négatif, un prorata positif et le paiement complet pour le mois de février, qui s’élève à 125 EUR. Par défaut, la facture apparaît à l’état draft pendant environ une heure).

  • Avancez l’horloge d’une heure afin de finaliser la facture.

Périodes d’essai

Imaginons que vous souhaitiez permettre à vos clients de tester votre produit gratuitement pendant 7 jours avant le début de la facturation et que vous vouliez collecter les informations de paiement à l’avance. Pour simuler cette situation avec les horloges de simulation, suivez les étapes suivantes :

  • Créez une nouvelle simulation et définissez le paramètre frozen_time sur le 1er janvier.
  • Ajoutez un client et spécifiez son moyen de paiement. Dans ce cas, utilisez une carte de test.
  • Créez un abonnement et ajoutez une période d’essai gratuit de 7 jours :

Pour ajouter une période d’essai à un abonnement existant via le Dashboard :

Recherchez l’abonnement que vous souhaitez modifier.

  1. Cliquez sur Actions.
  2. Cliquez sur Mettre à jour l’abonnement.
  3. Cliquez sur Ajouter une période d’essai et saisissez sept dans le champ Nombre de jours de l’essai gratuit.
  4. Cliquez sur Mettre à jour l’abonnement.
  • La création d’un abonnement avec une période d’essai gratuite de 7 jours crée un abonnement à l’état trialing. Une facture de 0,00 USD est générée pour cet essai gratuit.
  • Avancez la date au 5 janvier pour recevoir la notification d’événement customer.subscription.trial_will_end. Stripe envoie la notification 3 jours avant la fin de la période d’essai. Vous pouvez utiliser cet événement webhook pour informer vos clients que la période d’essai arrive bientôt à son terme.
  • Avancez la date au 8 janvier pour vérifier que l’abonnement est désormais à l’état paid et qu’une facture de 50 EUR a été créée.
  • Avancez la date d’un cycle (par exemple, au 8 février pour un abonnement mensuel) pour constater le renouvellement.

Limites

Vous pouvez simuler jusqu’à :

  • Trois clients
  • Trois abonnements (qui peuvent être des abonnements planifiés) par client
  • Dix devis non associés à des clients

Clients existants

Vous pouvez créer une horloge de simulation pour un client existant avec les limitations suivantes :

  • Le client ne doit pas déjà dépasser le nombre autorisé d’abonnements, d’abonnements planifiés et de devis.
  • La frozen_time initiale ne peut pas être dans le passé, ce qui signifie que vous ne pouvez pas antidater l’horloge de simulation pour un client existant.
  • Votre compte ne doit pas avoir d’Automations configurées. Pour utiliser une horloge de simulation avec un client existant, supprimez d’abord vos Automations, ou créez directement un nouveau client sur l’horloge de simulation.

Le client ne peut pas être retiré de l’horloge de simulation. Lorsque l’horloge de simulation est supprimée, le client et tous les abonnements sont également supprimés.

Objets de l’horloge de simulation omis dans la liste de tous les résultats

Les méthodes de type liste de l’API (comme List Invoices) ne renvoient pas les objets générés par des horloges de simulation, sauf si vous spécifiez une clause de requête. Les paramètres de requête requis varient selon la ressource, consultez donc l’entrée correspondante dans la documentation de l’API.

Par exemple, GET /v1/invoices ne renvoie pas les factures générées par des horloges de simulation, mais GET /v1/invoices avec une clause de requête comme customer :"cus_123" renvoie toutes les factures de ce client, y compris celles générées par des horloges de simulation.

De même, vous pouvez spécifier un identifiant d’horloge de simulation dans cet exemple pour obtenir toutes les factures liées à cette horloge, ou spécifier un identifiant d’abonnement pour obtenir toutes les factures relatives à cet abonnement, y compris les factures générées par l’horloge de simulation.

Erreurs de limite de taux

Si vous effectuez plusieurs mises à jour d’un abonnement associé à une horloge de simulation, Stripe peut renvoyer une erreur de limite de taux. Étant donné que l’abonnement est gelé à l’heure de l’horloge de simulation, toutes les requêtes API comptent pour cette heure, ce qui peut déclencher la limite de taux.

Pour éviter cela, avancez l’heure simulée de l’horloge de quelques minutes avant d’effectuer des demandes d’API supplémentaires sur l’abonnement.

L’API Subscriptions limite le nombre maximal de requêtes comme suit :

  • 10 nouvelles factures par abonnement, par minute
  • 20 nouvelles factures par abonnement et par jour
  • 200 mises à jour de quantité par abonnement et par heure

Mises en garde concernant le traitement des paiements

L’avancement de l’horloge de simulation ne prend pas encore en charge la collecte des paiements par prélèvement bancaire (comme les types de moyen de paiement us_bank_account). Stripe encaisse les paiements après avancement de l’horloge de simulation. Pour tester les échecs de paiement :

  1. Sélectionnez le paramètre Annuler l’abonnement après l’échec de toutes les relances de paiement.

  2. Associez un moyen de paiement de type us_bank_accountà un client dont les paiements échouent.

  3. Créez un abonnement pour le client.

  4. Faites avancer l’horloge de simulation pour collecter le paiement d’un abonnement.

Une fois l’horloge de test avancée, l’abonnement reste active. Cela indique que le prélèvement n’a pas été tenté pendant l’avancement de l’horloge de test et que l’abonnement n’est pas passé à l’état canceled en raison d’un payment_failed.

Écoutez l’événement invoice.payment_failed pour surveiller l’état de l’abonnement en retard de paiement et le paiement de la facture. L’événement customer.subscription.deleted indique que l’abonnement est à l’état canceled.

Sur cette page