API et utilisation avancée

Vous pouvez créer une horloge de simulation distincte d’un abonnement afin d’effectuer des simulations avancées. Dans ce scénario, vous devez d’abord créer l’horloge de simulation, puis y ajouter différents cas de test.

Cycle de vie d’une horloge de simulation

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

1. Créez une horloge de simulation
2. Configurez votre simulation
3. Avancez la date et l’heure de l’horloge
4. Observez et traitez les modifications
5. Modifiez la simulation
6. Supprimer l’horloge

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

curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

Use cases

Tester les renouvellements d’abonnements

Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :

1. Créez une horloge de simulation
2. Configurez votre simulation
3. Avancez la date et l’heure de l’horloge
4. Observez et traitez les modifications
5. Modifiez la simulation

Ensuite, vous pouvez tester certains renouvellements d’abonnements à l’aide d’horloges de simulation. Imaginons que vous souhaitez tester si un abonnement à 50 USD/mois se renouvelle correctement. Pour simuler cette situation en utilisant des horloges de simulation :

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

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

• Avancez la date au 1er février. Vous devriez constater qu’une facture de 50 USD a été créée. Par défaut, la facture apparaît à l’état 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

Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :

1. Créez une horloge de simulation
2. Configurez votre simulation
3. Avancez la date et l’heure de l’horloge
4. Observez et traitez les modifications
5. Modifiez la simulation

Ensuite, vous pouvez tester des calculs au prorata pour les clients qui changent d’offre au milieu d’un cycle de facturation. Imaginons que vous avez deux produits : un à 50 USD/mois (‘basic plan‘) et l’autre à 100 USD/mois (‘premium plan‘). Dans ce cas, vous pourriez vouloir tester les calculs au prorata pour un client qui passe de l’offre ‘basic plan‘ à l’offre ‘premium plan‘ en cours de cycle de facturation. Pour simuler cette situation à l’aide d’horloges de simulation :

• Créez une nouvelle horloge de simulation et définissez son paramètre frozen_time sur le 1er janvier.
• Créez un client et ajoutez son moyen de paiement. Ici, utilisez la carte de test 4242424242424242
  .
• Créez un abonnement à ‘basic plan’ pour 50 USD/mois. Vous pourrez alors observer qu’une facture de 50 USD/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 USD/mois :

• 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 USD correspondant à la période non-consommée du ‘basic plan’, et un prorata positif de 50 USD 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 facturation en attente, y compris un prorata négatif, un prorata positif et le paiement complet pour le mois de février, qui s’élève à 125 USD. 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

Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :

1. Créer une horloge de simulation
2. Configurer votre simulation
3. Avancer la date et l’heure de l’horloge
4. Observer et traiter les modifications
5. Modifier la simulation

Ensuite, vous pouvez commencer à tester les périodes d’essai avec les horloges de simulation. Imaginons que vous voulez que vos clients testent vos produits gratuitement pendant une période d’essai de sept jours avant de commencer à payer et vous souhaitez collecter les informations de paiement en amont. Suivez les étapes ci-après pour simuler cette situation en utilisant des horloges de simulation :

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

• Suite à la création d’un abonnement avec une période d’essai gratuit de sept jours, un abonnement est créé dans un état trialing. L’essai gratuit donne lieu à la génération d’une facture de 0 $.
• Avancez la date au 5 janvier pour recevoir la notification d’événement customer.subscription.trial_will_end. Stripe envoie la notification trois 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 USD 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

Pour un fonctionnement efficace des horloges de test, Stripe limite la complexité de chaque simulation à :

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

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

Les API de liste de Stripe (telles que Liste de factures) omettent les résultats générés par les horloges de simulation pour toutes les requêtes de liste. Pour voir les résultats générés par les horloges de simulation dans ces cas, vous devez demander des résultats dans un parent spécifique, tel que test_clock, customer ou subscription.

Par exemple, GET /v1/invoices ne renverra pas les factures générées par l’horloge de simulation, mais GET {customer_id} renverra toutes les factures pour ce client, y compris celles qui sont générées par l’horloge 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.

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 simulation avancée, l’abonnement est toujours à l’état active. Cela signifie qu’aucune tentative d’encaissement du paiement n’a été effectuée durant l’avancement de l’horloge de simulation, et que l’abonnement n’est pas passé à l’état canceled suite au 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.