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

Personnaliser dynamiquement les options d'expédition

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

Découvrez comment mettre à jour automatiquement les options de livraison en fonction de l’adresse que votre client saisit dans 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.

Limitations

Configurer les autorisations de mise à jour de Checkout Session
Côté serveur

Définissez le champ shipping_address_collection.allowed_countries sur la liste des pays auxquels vous souhaitez offrir des services de livraison.

Transmettez permissions.update_shipping_details=server_only lors de la création de la session Checkout pour activer la mise à jour de l’adresse de livraison et des options de livraison à partir de votre serveur. La transmission de cette option désactive également la méthode updateShippingAddress, ce qui garantit que toutes les mises à jour transitent par votre serveur.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d "permissions[update_shipping_details]"=server_only \
  -d "shipping_address_collection[allowed_countries][0]"=US \
  -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 la session Checkout en utilisant l’identifiant checkoutSessionId` du corps de la demande.
  2. Validez les informations de livraison du client fournies dans le corps de la demande.
  3. Calculez les options d’expédition en fonction de l’adresse de livraison du client et des articles de la session Checkout.
  4. Modifiez la session Checkout avec les shipping_details et les shipping_options du client.
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"


# 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

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

Initialisez stripe.js avec l’en-tête bêta 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

Créez une fonction asynchrone qui envoie une requête à votre serveur pour mettre à jour les options de livraison et intégrez-la dans runServerUpdate. Si la demande aboutit, l’objet Session est mis à jour avec les nouvelles options de livraison.

L’exemple de code suivant montre comment mettre à jour les options de livraison avec l’AddressElement.

index.html
<div id="shipping-form">
    <!-- Shipping Address Element will be mounted here -->
    <div id="shipping-address-element"></div>
    <button id="save-button">Save</button>
    <div id="error-message"></div>
  </div>

  <div id="shipping-display" style="display: none">
    <div id="address-display"></div>
    <button id="edit-button">Edit</button>
  </div>
checkout.js
// mount the Shipping Address Element
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address-element');

const toggleViews = (isEditing) => {
  document.getElementById('shipping-form').style.display = isEditing ? 'block' : 'none';
  document.getElementById('shipping-display').style.display = isEditing ? 'none' : 'block';
}

const displayAddress = (address) => {
  const displayDiv = document.getElementById('address-display');
  displayDiv.innerHTML = `
    <div>${address.name}</div>
    <div>${address.address.line1}</div>
    <div>${address.address.city}, ${address.address.state} ${address.address.postal_code}</div>
  `;
}

const updateShippingOptions = async (shippingDetails) => {
  const response = await fetch("/calculate-shipping-options", {
    method: "POST",
    headers: { 'Content-type': 'application/json' },
    body: JSON.stringify({
      checkout_session_id: 'session_id',
      shipping_details: shippingDetails
    })
  });

  const result = await response.json();

  if (result.type === 'error') {
    document.getElementById('error-message').textContent = result.message;
    toggleViews(true);
  } else {
    document.getElementById('error-message').textContent = '';
    toggleViews(false);
    displayAddress(checkout.session().shippingAddress);
  }

  return result;
}

const handleSave = async () => {
  const addressElement = await checkout.getShippingAddressElement();
  if (!addressElement) {
    return;
  }

  const result = await addressElement.getValue();
  if (!result.complete) {
    return;
  }

  try {
    await checkout.runServerUpdate(() => updateShippingOptions(result.value));
  } catch (error) {
    document.getElementById('error-message').textContent = error?.message;
    toggleViews(true);
  }
}

// Event Listeners
document.getElementById('save-button').addEventListener('click', handleSave);
document.getElementById('edit-button').addEventListener('click', () => toggleViews(true));

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.

  2. Simulez différentes adresses de livraison pour vérifier que votre fonction calculateShippingOptions traite correctement les différents scénarios.

  3. 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.
    • Valide les informations de livraison.
    • Calcule les options de livraison.
    • Ajoute de nouvelles informations et options de livraison à la session Checkout. Assurez-vous que la réponse de modification contient les nouvelles informations et options d’expédition.

  4. 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 runServerUpdate 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.

  5. 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.

Cette page vous a-t-elle été utile ?
OuiNon