Mettre à jour de manière dynamique la durée des périodes d’essaiVersion bêta privée

Mettez à jour la durée des périodes d’essai en fonction des modifications apportées lors du paiement.

Version bêta privée

Cette fonctionnalité est disponible en version bêta privée. Request access to dynamic trial updates.

Découvrez comment mettre à jour de manière dynamique la durée des périodes d’essai des sessions Checkout pour les abonnements.

Cas d’usage

Gestion dynamique des périodes d’essai : ajoutez ou supprimez des essais en fonction des conditions promotionnelles ou des actions des clients.
Prolonger les périodes d’essai pour les ventes incitatives : proposez des périodes d’essai plus longues lorsque les clients passent à des offres de niveau supérieur (par exemple, une période de 7 jours pour un abonnement mensuel est prolongée à 14 jours pour un abonnement annuel).

Configurer le SDK
Côté serveur

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

Mettre à jour le SDK du serveur
Côté serveur

Pour utiliser cette version bêta, commencez par mettre à jour votre SDK afin d’utiliser la version bêta privée de l’API et l’en-tête de version bêta checkout_server_update_beta=v1.

Mettre à jour de manière dynamique la durée des périodes d’essai
Côté serveur

Créez un nouvel endpoint sur votre serveur pour mettre à jour la durée de l’essai en vue d’une vente incitative vers un abonnement annuel sur la session Checkout. Vous l’appelez à partir du front-end dans une étape ultérieure.

Conseil en matière de sécurité

Le code côté client s’exécute dans un environnement entièrement contrôlé par l’utilisateur. Un utilisateur malveillant peut contourner votre validation côté client, intercepter et modifier les requêtes, voire même créer des requêtes entièrement nouvelles pour votre serveur.

Pour concevoir l’endpoint, nous recommandons ce qui suit :

Concevez des endpoints pour des interactions spécifiques avec le client plutôt que de les formuler de manière trop générique (par exemple, « prolonger l’essai pour passer à un abonnement supérieur à l’année » plutôt qu’une action générale de « mise à jour »). Des endpoints spécifiques permettent de garder l’objectif clair et facilitent l’écriture et le maintien de la logique de validation.
Évitez de transmettre les données de session directement depuis le client à votre endpoint. Des clients malveillants peuvent modifier les données de requête, ce qui en fait une source peu fiable pour déterminer l’état de la session Checkout. Transmettez plutôt l’ID de session à votre serveur et utilisez-le pour récupérer en toute sécurité les données de l’API de Stripe.

Vous pouvez modifier la durée des périodes d’essai avec l’un des deux paramètres suivants :

trial_period_days : un nombre entier qui représente le nombre de jours de la période d’essai, ou une chaîne vide pour supprimer la période d’essai
trial_end : un horodatage Unix indiquant la date de fin de la période d’essai, ou une chaîne vide pour supprimer la période d’essai

À retenir :

Les paramètres trial_period_days et trial_end s’excluent mutuellement. Vous ne pouvez en indiquer qu’un seul dans une même requête de mise à jour.
Lorsque vous supprimez un essai, utilisez le même champ que celui avec lequel il a été défini. Un essai défini avec trial_period_days ne peut être supprimé qu’avec trial_period_days: "", et un essai défini avec trial_end ne peut être supprimé qu’avec trial_end: "".

Mettre à jour le SDK du client
Côté client

Initialisez stripe.js avec l’en-tête bêta % code %}custom_checkout_server_updates_1.

checkout.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_server_updates_1'],
});

Appeler les mises à jour du serveur
Côté client

Déclenchez la mise à jour à partir de votre front-end en envoyant une requête à votre serveur et en l’incluant dans runServerUpdate. Si la requête aboutit, l’objet Session est actualisé avec la nouvelle durée d’essai.

index.html
<button id="extend-trial-yearly">
  Upgrade to a yearly subscription and get an extended trial
</button>

checkout.js
document.getElementById('extend-trial-yearly')
  .addEventListener("click", async (event) => {
    const updateCheckout = () => {
      return fetch("/extend-trial-for-yearly", {
        method: "POST",
        headers: {
          "Content-type": "application/json",
        },
        body: JSON.stringify({
          checkout_session_id: checkout.session().id,
        })
      });
    };

    const response = await checkout.runServerUpdate(updateCheckout);
    if (!response.ok) {
      // Handle error state
      return;
    }

    // Update UI to reflect the extended trial
    event.target.textContent = "Trial extended to 14 days!";
    event.target.disabled = true;
  });

Tester l'intégration

Testez votre intégration pour vous assurer que les modifications apportées à la durée de la période d’essai fonctionnent correctement :

Créez une session Checkout d’abonnement avec une période d’essai initiale.
Déclenchez votre endpoint de serveur par une interaction avec l’élément d’interface utilisateur que vous avez créé.
Vérifiez que la durée de l’essai est correctement mise à jour dans la session Checkout.
Finalisez le paiement pour vous assurer que l’abonnement est créé avec les paramètres d’essai adéquats.

Remarque

Pour les vérifications, utilisez le mode test de Stripe pour éviter de créer des abonnements réels. Vous pouvez vérifier les modifications de la durée de la période d’essai en examinant l’objet Checkout Session ou l’abonnement créé.

Scénarios de test courants

Prolongation de l’essai : commencez par un essai de 7 jours, prolongez-le à 14 jours, puis vérifiez que la modification est reflétée dans l’interface utilisateur et l’objet Session.
Suppression de l’essai existant : commencez par un essai de 7 jours, supprimez-le, puis vérifiez que la modification est reflétée dans l’interface utilisateur et l’objet Session. Supprimez la période d’essai en utilisant le même champ que celui avec lequel elle était définie.
Gestion des erreurs : testez les requêtes non valides pour vous assurer que votre gestion des erreurs fonctionne correctement.