# Personnaliser dynamiquement les options d'expédition Actualisez les options de livraison en fonction de l'adresse de livraison du client. # Page hébergée > This is a Page hébergée for when payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/checkout/custom-shipping-options?payment-ui=stripe-hosted. L’intégration de page hébergée ne prend pas en charge dynamiquement la personnalisation des options de livraison. Pour personnaliser dynamiquement les options de livraison, utilisez plutôt la [Page intégrée](https://docs.stripe.com/payments/checkout/custom-shipping-options.md?payment-ui=embedded-form) ou l’intégration des [éléments Checkout](https://docs.stripe.com/payments/checkout/custom-shipping-options.md?payment-ui=embedded-components). # Page intégrée > This is a Page intégrée for when payment-ui is embedded-form. View the full page at https://docs.stripe.com/payments/checkout/custom-shipping-options?payment-ui=embedded-form. Découvrez comment mettre à jour dynamiquement les options de livraison en fonction de l’adresse que votre client saisit lorsque vous utilisez Checkout. ### Cas d’utilisation - **Valider une adresse** : Confirmez si vous pouvez expédier un produit à l’adresse d’un client en utilisant vos propres règles de validation personnalisées. Vous pouvez également créer une interface utilisateur personnalisée permettant aux clients de confirmer leur adresse préférée. - **Afficher les options de livraison pertinentes** : Affichez uniquement les modes de livraison disponibles, en fonction de l’adresse du client. Par exemple, proposez la livraison le lendemain uniquement pour les adresses dans votre pays. - **Calculer de manière dynamique les frais de livraison** : Calculez et affichez les frais de livraison en fonction de l’adresse de livraison du client. - **Mettre à jour les frais de livraison en fonction du montant total de la commande** : Proposez des frais de livraison basés sur l’adresse de livraison ou le montant total de la commande (par exemple, la livraison gratuite pour les commandes supérieures à 100 USD). Pour les paiements autorisant les changements de quantité ou les ventes croisées, consultez la page [Mise à jour dynamique des postes](https://docs.stripe.com/payments/checkout/dynamically-update-line-items.md). ### Limitations - Uniquement pris en charge en [mode paiement](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-mode). Les [frais de livraison](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options) ne sont pas disponibles en mode abonnement. - Ne prend pas en charge les mises à jour en réponse à des modifications apportées en dehors de la page de paiement. ## Créer une session Checkout [Côté serveur] Sur votre serveur, créez une *session Checkout* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription). - Définissez [ui_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-ui_mode) sur `embedded_page`. - Définissez le champ [permissions.update_shipping_details](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-permissions-update_shipping_details) sur `server_only`. - Définissez le champ [shipping_address_collection.allowed_countries](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-collected_information-shipping_details) de l’objet [Checkout Session](https://docs.stripe.com/api/checkout/sessions/object.md) avec les informations d’expédition saisies par le client, y compris son [nom](https://docs.stripe.com/api/checkout/sessions/update.md#update_checkout_session-collected_information-shipping_details-name) et son [adresse](https://docs.stripe.com/api/checkout/sessions/update.md#update_checkout_session-collected_information-shipping_details-address). > Lorsque le champ [permissions.update_shipping_details](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d ui_mode=embedded_page \ -d "permissions[update_shipping_details]=server_only" \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d "shipping_options[0][shipping_rate_data][display_name]=Dummy shipping" \ -d "shipping_options[0][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]=0" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]=usd" \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "return_url=https://example.com/return" ``` ## 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. 1. [Récupérer](https://docs.stripe.com/api/checkout/sessions/retrieve.md) la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) en utilisant l’`identifiant`checkoutSessionId` du corps de la demande. 1. Validez les informations de livraison du client fournies dans le corps de la demande. 1. Calculez les options d’expédition en fonction de l’adresse de livraison du client et des articles de la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md). 1. [Modifiez](https://docs.stripe.com/api/checkout/sessions/update.md) la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) avec les [shipping_details](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-collected_information-shipping_details) et les [shipping_options](https://docs.stripe.com/api/checkout/sessions/update.md#update_checkout_session-shipping_options) du client. #### Ruby ```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 = "<>" # 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] #### HTML + JS Checkout est disponible dans [Stripe.js](https://docs.stripe.com/js.md). 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. ```html
``` Initialisez Stripe.js avec votre clé API publique. ```javascript // 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('<>'); ``` Créez une fonction `fetchClientSecret` asynchrone qui demande à votre serveur de créer la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) 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. ```javascript 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.createEmbeddedCheckoutPage({ fetchClientSecret, onShippingDetailsChange, }); // Mount Checkout checkout.mount('#checkout'); } ``` #### React Installez [react-stripe-js](https://docs.stripe.com/sdks/stripejs-react.md) et le chargeur Stripe.js à partir de npm : ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` Initialisez l’instance `stripe` avec votre clé API publique. ```jsx import {loadStripe} from '@stripe/stripe-js'; // Make sure to call `loadStripe` outside of a component’s render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe('<>'); ``` Pour utiliser le composant Embedded Checkout, créez un `EmbeddedCheckoutProvider`. Créez une fonction `fetchClientSecret` asynchrone qui demande à votre serveur de créer la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) 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. Transmettez `stripePromise` au fournisseur et les fonctionnalités dans la proposition `options` acceptée par le fournisseur. ```jsx import * as React from 'react'; import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-stripe-js'; const App = () => { const fetchClientSecret = useCallback(() => { // Create a Checkout Session return fetch("/create-checkout-session", { method: "POST", }) .then((res) => res.json()) .then((data) => data.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"}); } }; const options = {fetchClientSecret, onShippingDetailsChange}; return (
) } ``` > Retournez toujours une `Promise` depuis votre fonction `onShippingDetailsChange` et résolvez-la avec un object [ResultAction](https://docs.stripe.com/js/embedded_checkout/create#embedded_checkout_create-options-onShippingDetailsChange-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. > É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 Suivez ces étapes pour tester votre intégration et vous assurer que vos options de livraison personnalisées fonctionnent correctement. 1. Configurez un environnement de test qui reflète votre configuration en mode production. Utilisez les clés API d’environnement de test Stripe pour cet environnement. 1. Simulez différentes adresses de livraison pour vérifier que votre fonction `calculateShippingOptions` traite correctement les différents scénarios. 1. Vérifiez la logique côté serveur en utilisant des outils de journalisation ou de débogage pour confirmer que votre serveur : - Récupère la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md). - Valide les informations de livraison. - Calcule les options de livraison. - Ajoute de nouvelles informations et options de livraison à la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md). Assurez-vous que la réponse de modification contient les nouvelles informations et options d’expédition. 1. Vérifiez la logique côté client en effectuant plusieurs fois le processus de paiement dans votre navigateur. Observez la façon dont l’interface utilisateur se met à jour après avoir saisi les informations de l’expédition. Vérifiez que : - La fonction `onShippingDetailsChange` est appelée comme prévu. - Les options de livraison sont correctement mises à jour en fonction de l’adresse fournie. - Les messages d’erreur s’affichent correctement lorsque l’expédition n’est pas disponible. 1. Saisissez des adresses de livraison non valides ou simulez des erreurs de serveur pour tester la gestion des erreurs, côté serveur et côté client.