Personnaliser dynamiquement les options d'expédition

Actualisez les options de livraison en fonction de l'adresse de livraison du client.

Copier la page

Learn how to dynamically update shipping options based on the address that your customer enters in Checkout.

Use cases

Validate an address: Confirm whether you can ship a product to a customer’s address using your own custom validation rules. You can also create a custom UI for customers to confirm their preferred address.
Show relevant shipping options: Display only available shipping methods, based on the customer’s address. For example, show overnight shipping only for deliveries in your country.
Dynamically calculate shipping rates: Calculate and display shipping fees based on a customer’s delivery address.
Update shipping rates based on order total: Offer shipping rates based on the shipping address or order total, such as free shipping for orders over 100 USD. For checkouts allowing quantity changes or cross-sells, see Dynamically updating line items.

Limitations

Only supported in payment mode. Shipping rates aren’t available in subscription mode.
Doesn’t support updates in response to changes from outside of the checkout page.

Créer une session Checkout
Côté serveur

Sur votre serveur, créez une session Checkout.

Définissez le champ ui_mode sur embedded.
Définissez le champ permissions.update_shipping_details sur server_only.
Définissez le champ shipping_address_collection.allowed_countries sur la liste des pays auxquels vous souhaitez offrir des services de livraison.
Définissez l’attribut shipping_options.shipping_rate_data qui crée des frais de livraison fictifs avec un montant de 0 USD.

Par défaut, le client Stripe Checkout met automatiquement à jour le champ shipping_details de l’objet Checkout Session avec les informations d’expédition saisies par le client, y compris son nom et son adresse.

Avertissement

Lorsque le champ permissions.update_shipping_details est défini sur server_only, la mise à jour automatique côté client est désactivée et seul votre serveur peut mettre à jour les informations d’expédition à l’aide de votre clé secrète Stripe.

Personnaliser les options d'expédition
Côté serveur

À partir de votre serveur, créez un nouvel endpoint pour calculer les options d’expédition en fonction de l’adresse de livraison du client.

Récupérer la session Checkout en utilisant l’identifiant checkoutSessionId` du corps de la demande.
Validez les informations de livraison du client fournies dans le corps de la demande.
Calculez les options d’expédition en fonction de l’adresse de livraison du client et des articles de la session Checkout.
Modifiez la session Checkout avec les shipping_details et les shipping_options du client.

Ruby
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"


# Return a boolean indicating whether the shipping details are valid
def validate_shipping_details(shipping_details)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Validate the shipping details the customer has entered.
  MSG
end

# Return an array of the updated shipping options or the original options if no update is needed
def calculate_shipping_options(shipping_details, session)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Calculate shipping options based on the customer's shipping details and the
    Checkout Session's line items.
  MSG
end

post '/calculate-shipping-options' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  shipping_details = request_data['shipping_details']

  # 1. Retrieve the Checkout Session
  session = Stripe::Checkout::Session.retrieve(checkout_session_id)

  # 2. Validate the shipping details
  if !validate_shipping_details(shipping_details)
    return { type: 'error', message: "We can't ship to your address. Please choose a different address." }.to_json
  end

  # 3. Calculate the shipping options
  shipping_options = calculate_shipping_options(shipping_details, session)

  # 4. Update the Checkout Session with the customer's shipping details and shipping options
  if shipping_options
    Stripe::Checkout::Session.update(checkout_session_id, {
      collected_information: { shipping_details: shipping_details },
      shipping_options: shipping_options
    })

    return { type: 'object', value: { succeeded: true } }.to_json
  else
    return { type: 'error', message: "We can't find shipping options. Please try again." }.to_json
  end
end

Monter Checkout
Côté client

Checkout est disponible dans Stripe.js. Intégrez le script Stripe.js à votre page en l’ajoutant à l’en-tête de votre fichier HTML. Ensuite, créez un nœud DOM vide (conteneur) à utiliser pour le montage.

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialisez Stripe.js avec votre clé API publique.

index.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Créez une fonction fetchClientSecret asynchrone qui demande à votre serveur de créer la session Checkout et de récupérer la clé secrète du client.

Créez une fonction asynchrone onShippingDetailsChange qui envoie une requête à votre serveur pour calculer les options d’expédition en fonction de l’adresse de livraison du client. Stripe Checkout appelle la fonction lorsque le client remplit le formulaire avec les informations de livraison.

index.js
initialize();

async function initialize() {
  // Fetch Checkout Session and retrieve the client secret
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Call your backend to set shipping options
  const onShippingDetailsChange = async (shippingDetailsChangeEvent) => {
    const {checkoutSessionId, shippingDetails} = shippingDetailsChangeEvent;
    const response = await fetch("/calculate-shipping-options", {
      method: "POST",
      body: JSON.stringify({
        checkout_session_id: checkoutSessionId,
        shipping_details: shippingDetails,
      })
    })

    if (response.type === 'error') {
      return Promise.resolve({type: "reject", errorMessage: response.message});
    } else {
      return Promise.resolve({type: "accept"});
    }
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
    onShippingDetailsChange,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Mise en garde

Renvoyez toujours une Promise à partir de votre fonction onShippingDetailsChange et résolvez-la avec un objet ResultAction.

Le client Checkout met à jour l’interface utilisateur en fonction du résultat de la fonction onShippingDetailsChange.

Lorsque le résultat présente type: "accept", l’interface utilisateur de Checkout affiche les options d’expédition que vous avez définies sur votre serveur.
Lorsque le résultat est type: "reject", l’interface utilisateur de Checkout affiche le message d’erreur que vous avez défini dans le résultat.

Si vous le souhaitez, vous pouvez écouter onShippingDetailsChange et créer une interface utilisateur personnalisée permettant aux clients de sélectionner et de confirmer leur adresse préférée parmi plusieurs adresses possibles.

Checkout s’affiche dans un iframe qui envoie de manière sécurisée les informations de paiement à Stripe via une connexion HTTPS.

Erreur fréquente

Évitez de placer Checkout dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement.

Tester l'intégration

Follow these steps to test your integration, and ensure your custom shipping options work correctly.

Set up a sandbox environment that mirrors your production setup. Use your Stripe sandbox API keys for this environment.
Simulate various shipping addresses to verify that your calculateShippingOptions function handles different scenarios correctly.
Verify server-side logic by using logging or debugging tools to confirm that your server:
- Retrieves the Checkout Session.
- Validates shipping details.
- Calculates shipping options.
- Updates the Checkout Session with new shipping details and options. Make sure the update response contains the new shipping details and options.
Verify client-side logic by completing the checkout process multiple times in your browser. Pay attention to how the UI updates after entering shipping details. Make sure that:
- The onShippingDetailsChange function is called when expected.
- Shipping options update correctly based on the provided address.
- Error messages display properly when shipping is unavailable.
Enter invalid shipping addresses or simulate server errors to test error handling, both server-side and client-side.