Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
AperçuMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageUtiliser Managed Payments
Créer une intégration personnalisée avec Elements
Paiements par TPE
Moyens de paiement
Scénarios de paiement
Au-delà des paiements

Mettre à jour dynamiquement les postes

Apprenez à modifier les prix et le contenu d’un panier lors du paiement.

Version bêta privée

Cette fonctionnalité est disponible en version bêta privée.{ % collect-email modal=true modal_link_text=“Request access to dynamic updates to checkout.” list=“checkout-beta@stripe.com” send_direct_email=true intro_text=“Dynamic line items” body_text=“Cette fonctionnalité en version bêta vous permet de mettre à jour automatiquement les postes dans les Elements avec l’intégration de l’API Checkout Sessions. Saisissez votre adresse e-mail ci-dessous pour demander un accès anticipé.” form_cta_text=“Sign up” success_text=“Merci ! Nous vous contacterons bientôt.” show_email_confirmation=true % }

Découvrez comment ajouter, supprimer ou mettre à jour dynamiquement les postes inclus dans une session Checkout.

Cas d’usage

Ce guide vous explique comment mettre à jour des postes pour augmenter la vente d’un abonnement, mais vous pouvez également :

  • Vérifier l’inventaire : effectuez une vérification de vos stocks et réservez des articles lorsque les clients tentent de modifier des quantités d’articles.
  • Ajout de nouveaux produits : Ajoutez un produit gratuit si le total de la commande dépasse un certain montant.
  • Mise à jour des tarifs de livraison : Si le total de la commande change, mettez à jour les frais de livraison en combinant la méthode décrite dans ce guide avec celle indiqués à la rubrique Personnalisation des options de livraison lors du paiement.
  • Mise à jour des taux de taxe : Si vous n’utilisez pas Stripe Tax, vous pouvez mettre à jour de manière dynamique les taux de taxe appliqués aux postes de facture en fonction de l’adresse de livraison saisie.

API Payment Intents

Si vous utilisez l’API Payment Intents, vous devez suivre manuellement les mises à jour des postes et modifier le montant du paiement, ou créer un nouveau PaymentIntent avec les montants réajustés.

Configurer le SDK
Côté serveur

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

Command Line
Ruby
Python
PHP
Node.js
.NET
Go
Java
No results
gem install stripe -v 15.1.0-beta.2

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

Pour utiliser cette version bêta, mettez d’abord à jour votre SDK afin d’utiliser l’en-tête de version bêta checkout_server_update_beta=v1.

Ruby
Python
PHP
Node
.NET
Go
Java
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.basil; checkout_server_update_beta=v1;'

Configurer les autorisations de mise à jour pour la session Checkout
Côté serveur

Lorsque vous créez la session Checkout, transmettez l’option permissions.update_line_items=server_only pour désactiver les mises à jour côté client et permettre la mise à jour des postes, comme updateLineItemQuantity, à partir de votre serveur.

Command Line
cURL
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-03-31.basil; checkout_server_update_beta=v1;" \
  -d ui_mode=custom \
  -d "permissions[update_line_items]"=server_only \
  -d "line_items[0][price]"=
"{{PRICE_ID}}"
 \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  --data-urlencode return_url="https://example.com/return"

Mettre à jour dynamiquement les postes
Côté serveur

Créez un endpoint sur votre serveur pour mettre à jour les postes pendant la session Checkout. Vous l’appellerez à partir de l’interface dans une étape ultérieure.

Conseil en matière de sécurité

Le code côté client s’exécute dans un environnement contrôlé par l’utilisateur. Un utilisateur malveillant peut contourner votre validation côté client, intercepter et modifier des requêtes, ou créer de nouvelles requêtes vers votre serveur.

Lors de la création d’un endpoint, nous vous recommandons ce qui suit :

  • Créez des endpoints pour des interactions spécifiques avec les clients au lieu de les rendre génériques. Par exemple, « ajouter des éléments de vente croisée » au lieu d’une action générale de « mise à jour ». Des endpoints spécifiques peuvent faciliter l’écriture et la maintenance de la logique de validation.
  • Ne transmettez pas les données de session directement du 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 d’une session de paiement. Au lieu de cela, transmettez l’identifiant de session à votre serveur et utilisez-le pour récupérer en toute sécurité les données à partir de l’API Stripe.
Ruby
Python
PHP
Node
.NET
Go
Java
No results
require 'sinatra'
require 'json'
require 'stripe'

set :port, 4242

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.basil; checkout_server_update_beta=v1;'

MONTHLY_PRICE_ID = '{{MONTHLY_PRICE}}'
YEARLY_PRICE_ID = '{{YEARLY_PRICE}}'

post '/change-subscription-interval' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  interval = request_data['interval']

  if checkout_session_id.nil? || !['yearly', 'monthly'].include?(interval)
    status 400
    return {
      type: 'error',
      message: 'We couldn't process your request. Please try again later.'
    }.to_json
  end

  begin
    # 1. Create the new line items for the Checkout Session.
    new_price = interval == 'yearly' ? YEARLY_PRICE_ID : MONTHLY_PRICE_ID
    line_items = [{
      price: new_price,
      quantity: 1,
    }]

    # 2. Update the Checkout Session with the new line items.
    Stripe::Checkout::Session.update(checkout_session_id, {
      line_items: line_items,
    })

    # 3. Return a success response.
    { type: 'success' }.to_json
  rescue Stripe::StripeError
    # Handle Stripe errors with a generic error message
    status 400
    {
      type: 'error',
      message: 'We couldn't process your request. Please try again later.'
    }.to_json
  rescue StandardError
    # Handle unexpected errors
    status 500
    {
      type: 'error',
      message: 'Something went wrong on our end. Please try again later.'
    }.to_json
  end
end

Lors de la mise à jour des postes, vous devez retransmettre l’ensemble du tableau des postes.

  • Pour conserver un poste existant, indiquez son id.
  • Pour mettre à jour un poste existant, indiquez son id ainsi que les nouvelles valeurs des champs à mettre à jour.
  • Pour ajouter un nouvel élément, indiquez un price et une quantity sans id.
  • Pour supprimer un poste existant, omettez l’identifiant du poste dans le tableau retransmis.
  • Pour réorganiser un poste, indiquez son id à la position souhaitée dans le tableau retransmis.

Mettre à jour le SDK client
Côté client

Initialisez Stripe.js avec l’en-tête custom_checkout_server_updates_1 beta.

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

Requête de mise à jour du serveur
Côté client

À partir de votre interface, envoyez une requête de mise à jour à votre serveur et encapsulez-la dans runServerUpdate Une requête réussie met à jour l’objet Session avec les nouveaux postes.

index.html
<button id="change-subscription-interval" role="switch" aria-checked="false">
  Save with a yearly subscription
</button>
checkout.js
document.getElementById('change-subscription-interval')
  .addEventListener("click", async (event) => {
    const button = event.target;
    const isCurrentSubscriptionMonthly =
      button.getAttribute("aria-checked") === "false";

    const updateCheckout = () => {
      return fetch("/change-subscription-interval", {
        method: "POST",
        headers: {
          "Content-type": "application/json",
        },
        body: JSON.stringify({
          checkout_session_id: actions.getSession().id,
          interval: isCurrentSubscriptionMonthly ? "yearly" : "monthly",
        })
      });
    };

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

    // Update toggle state on success
    const isNewSubscriptionMonthly = !isCurrentSubscriptionMonthly;
    button.setAttribute("aria-checked", !isNewSubscriptionMonthly);
    button.textContent = isNewSubscriptionMonthly
      ? "Save with a yearly subscription"
      : "Use monthly subscription";
  });
Cette page vous a-t-elle été utile ?
OuiNon