Configurer des paiements futurs

Comment enregistrer les informations de paiement lors d’une session Checkout et débiter vos clients ultérieurement.

Pour collecter les informations de paiement du client que vous pourrez réutiliser ultérieurement, utilisez le mode configuration de Checkout. Le mode configuration utilise l’API Setup Intents pour créer des moyens de paiement.

Configurer Stripe
Côté serveur

Pour commencer, vous devez créer un compte Stripe. S’inscrire.

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

Créer une session Checkout
Côté serveur

Sur votre serveur, créez une session Checkout et définissez le paramètre ui_mode sur embedded. Pour créer une session Checkout en mode configuration, définissez le mode sur setup.

Pour rediriger vos clients vers une page personnalisée hébergée sur votre site Web, spécifiez l’URL de cette page dans le paramètre return_url. Incluez la variable de modèle {CHECKOUT_SESSION_ID} dans l’URL pour récupérer l’état de la session sur la page de retour. Checkout remplace automatiquement la variable par l’ID de session Checkout avant la redirection.

En savoir plus sur la configuration de la page de retour et d’autres options pour personnaliser le comportement de redirection.

Vous pouvez éventuellement spécifier le paramètre client pour associer automatiquement le moyen de paiement créé à un client existant.

Après avoir créé la session Checkout, utilisez la client_secret renvoyée dans la réponse pour monter Checkout.

Moyens de paiement

Par défaut, Stripe active les cartes bancaires et autres moyens de paiement courants. Vous avez la possibilité d’activer ou de désactiver des moyens de paiement directement depuis le Dashboard Stripe. Dans Checkout, Stripe évalue la devise et les restrictions éventuelles, puis présente dynamiquement au client les moyens de paiement pris en charge.

Pour visualiser l’affichage des moyens de paiement pour les clients, saisissez un ID de transaction ou définissez le montant et la devise d’une commande dans le Dashboard.

Vous pouvez activer Apple Pay et Google Pay dans vos paramètres des moyens de paiement. Par défaut, Apple Pay est activé et Google Pay est désactivé. Cependant, dans certains cas, Stripe les filtre même lorsqu’ils sont activés. Nous filtrons Google Pay si vous activez les taxes automatiques sans collecter d’adresse de livraison.

Aucune modification de l’intégration n’est requise pour activer Apple Pay ou Google Pay dans les pages hébergées par Stripe de Checkout. Stripe gère ces paiements de la même manière que les autres paiements par carte bancaire.

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/basil/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialisez Stripe.js avec votre clé API publique.

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. Transmettez cette fonction dans la propriété options lorsque vous créez l’instance Checkout :

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

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

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

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

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.

Personnaliser l’apparence

Personnalisez Checkout pour qu’il corresponde au design de votre site en définissant la couleur d’arrière-plan, la couleur des boutons, le rayon de la bordure et les polices dans les paramètres de marque de votre compte.

Par défaut, Checkout s’affiche sans espacement externe ni marge. Nous vous recommandons d’utiliser un élément de conteneur tel qu’un espace div pour appliquer la marge souhaitée (par exemple, 16 px sur tous les côtés).

Récupérer la session Checkout
Côté serveur

Une fois que votre client a terminé sa session Checkout, vous devez récupérer l’objet session. Il y a deux façons de procéder :

De manière asynchrone : en traitant les webhooks checkout.session.completed, qui contiennent un objet session. En savoir plus sur la configuration des webhooks.
De manière synchrone : obtenez l’ID de session à partir de l’URL return_url lorsqu’un utilisateur est redirigé vers votre site. Utilisez l’ID de session pour récupérer l’objet de session.

Le choix entre ces deux méthodes dépend de votre tolérance aux abandons de paiement. En effet, il peut arriver que vos clients n’arrivent pas à l’URL return_url après la réussite d’un paiement. Ils peuvent par exemple fermer l’onglet de leur navigateur avant d’être correctement redirigés. Si votre intégration traite les webhooks, elle ne sera pas exposée à ce type d’abandon de paiement.

Après avoir récupéré l’objet session, obtenez la valeur de la clé setup_intent, qui correspond à l’ID du SetupIntent créé lors de la session Checkout. Un SetupIntent est un objet permettant de configurer les coordonnées de compte bancaire de votre client en vue de paiements futurs.

Exemple de charge utile checkout.session.completed :

{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2019-03-14",
  "created": 1561420781,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session",
      "billing_address_collection": null,
      "client_reference_id": null,
      "customer": "",
      "customer_email": null,
      "display_items": [],
      "mode": "setup",
      "setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
      "submit_type": null,
      "subscription": null,
      "success_url": "https://example.com/success"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}

Prenez note de l’ID du setup_intent pour la prochaine étape.

Récupérer le SetupIntent
Côté serveur

À l’aide de l’ID du SetupIntent, récupérez l’objet SetupIntent. L’objet renvoyé contient un ID payment_method que vous pouvez associer à un client à l’étape suivante.

Remarque

Si vous récupérez ces informations de manière synchrone auprès de l’API Stripe (et non en traitant des webhooks), vous pouvez combiner cette étape-ci à l’étape précédente en développant l’objet SetupIntent dans votre requête au endpoint /v1/checkout/session. De cette manière, vous n’avez pas besoin d’effectuer deux requêtes réseau différentes pour accéder à l’ID du PaymentMethod qui vient d’être créé.

Débiter ultérieurement le moyen de paiement enregistré
Côté serveur

Si vous n’avez pas renseigné de client existant à la création de la session Checkout, utilisez l’ID de PaymentMethod pour associer l’objet PaymentMethod à un client. Une fois cette opération effectuée, vous pouvez effectuer un paiement hors session à l’aide d’un PaymentIntent :

Définissez customer sur l’ID du client et payment_method sur l’ID du PaymentMethod.
Définissez l’attribut off_session sur true pour indiquer que le client ne se trouve pas dans votre tunnel de paiement lors d’une tentative de paiement, et qu’il ne peut donc pas répondre à une demande d’authentification effectuée par un partenaire, comme un émetteur de cartes, une banque ou un autre établissement de paiement. Si un partenaire demande une authentification dans le tunnel de paiement, Stripe demande une exemption en s’appuyant sur les informations utilisée par le client pendant une session précédente. Si les conditions d’exemption ne sont pas remplies, le PaymentIntent peut renvoyer une erreur.
Définissez la propriété confirm du PaymentIntent sur la valeur true, ce qui aura pour effet de générer immédiatement une confirmation lorsque vous créez le PaymentIntent.

Lorsqu’une tentative de paiement échoue, la requête échoue également avec un code d’état HTTP 402. L’état du PaymentIntent est requires_payment_method. Vous devez inviter votre client à revenir dans votre application (par e-mail ou par une notification dans l’application par exemple) et orientez votre client vers une nouvelle session Checkout pour sélectionner un autre moyen de paiement.

Configurer des paiements futurs

Comment enregistrer les informations de paiement lors d’une session Checkout et débiter vos clients ultérieurement.

Configurer StripeCôté serveur

Créer une session CheckoutCôté serveur