VOXIBLY
← Retour aux fonctions

Intégration de la passerelle de paiement Stripe au checkout (Projet Aurora)

D'une consigne orale, un brief structuré prêt à être transmis.

Exemple de résultat réel

Résumé

Marc, de l'équipe Paiements, a dicté un brief pour brancher la passerelle de paiement Stripe sur le checkout de l'e-shop Projet Aurora. L'objectif est de remplacer la facturation manuelle actuelle par le paiement par carte en ligne, avec la prise en charge d'Apple Pay et Google Pay. L'échéance pour la mise en production est le 15 juillet, avec un MVP sur l'environnement de test d'ici la fin juin.

Compte-rendu détaillé

Ce qui doit être construit

L'objectif est d'ajouter le paiement par carte via Stripe au checkout existant du Projet Aurora. Après avoir rempli son panier, le client choisit un mode de paiement et paie directement sur la page, sans redirection vers une passerelle externe. Marc a insisté pour que le formulaire de paiement soit intégré via Stripe Elements, afin qu'il reste dans le design de l'e-shop.

Outre la carte classique, Apple Pay et Google Pay doivent être pris en charge, car selon les analyses, les commandes mobiles représentent plus de la moitié du trafic. Le paiement en espèces et sur facture restent disponibles comme alternatives ; Stripe n'est qu'une troisième option supplémentaire.

Exigences techniques et garde-fous

La fiabilité de la confirmation du paiement est essentielle. Le statut de la commande ne doit jamais changer en fonction de la réponse du navigateur, mais exclusivement via un webhook Stripe sur le backend (l'événement payment_intent.succeeded). Marc a explicitement mis en garde contre le cas où le client paie, mais la connexion tombe et la commande reste bloquée comme impayée.

Chaque appel doit être idempotent (le relancer ne crée pas de second paiement) grâce à un idempotency key. Les webhooks doivent être vérifiés par signature pour qu'on ne puisse pas les falsifier. En cas de panne de Stripe, un fallback est requis — le checkout ne doit pas tomber entièrement ; on masque simplement la carte et on propose les autres modes de paiement.

Tâches

  • Créer un endpoint backend pour la création d'un PaymentIntent avec Stripe (montant, devise, idempotency key). · responsable équipe backend · échéance d'ici le 27 juin élevée
  • Intégrer Stripe Elements au checkout du frontend (carte, Apple Pay, Google Pay) dans le design de l'e-shop. · responsable équipe frontend · échéance d'ici le 30 juin élevée
  • Implémenter un handler de webhook pour payment_intent.succeeded et payment_intent.payment_failed avec vérification de signature. · responsable équipe backend · échéance d'ici le 27 juin élevée
  • Ajouter un fallback : en cas d'indisponibilité de Stripe, masquer le paiement par carte et proposer les espèces et la facture. · responsable équipe frontend · échéance d'ici le 3 juillet moyenne
  • Préparer les scénarios de test (succès, échec de carte, panne de webhook, paiement en double) sur l'environnement de test. · responsable Lucie (QA) · échéance d'ici le 8 juillet moyenne

Décisions

  • Le formulaire de paiement sera intégré via Stripe Elements directement dans le checkout, sans redirection vers une page externe. 💬 de la transcription: „"Je le veux à l'intérieur, dans le même design, pas un truc qui balance la personne sur une page tierce."“
  • La confirmation du paiement est gérée par le webhook côté serveur payment_intent.succeeded, et non par la réponse du client. 💬 de la transcription: „"La source de vérité, c'est le webhook sur le backend, point."“
  • Apple Pay et Google Pay font partie du premier MVP, pas d'une phase ultérieure. 💬 de la transcription: „"Considère Apple Pay et Google Pay comme faisant partie de la base, pas comme un bonus pour plus tard."“

Idées clés

  • Le statut de la commande est piloté exclusivement par le webhook côté serveur, et non par la réponse du navigateur — cela protège contre la perte d'un paiement lorsque la connexion tombe. 💬 de la transcription: „"Jamais, vraiment jamais, ne confirmez une commande selon ce qui revient au navigateur. Uniquement selon le webhook sur le serveur."“
  • Les commandes mobiles représentent plus de 50 % du trafic, c'est pourquoi Apple Pay et Google Pay font partie du MVP, et non d'une deuxième phase. 💬 de la transcription: „"Plus de la moitié des gens achètent depuis leur téléphone, donc Apple Pay et Google Pay doivent être là tout de suite, pas plus tard."“
  • En cas de panne de Stripe, l'ensemble du checkout ne doit pas casser — seul le paiement par carte est masqué, et les espèces et la facture restent. 💬 de la transcription: „"Si Stripe tombe, ne laissez pas tout le checkout planter. On masque juste la carte et les gens paient autrement."“

Données

  • 15 juillet date Mise en production Échéance pour le lancement de la passerelle de paiement en exploitation réelle.
  • fin juin date MVP sur l'environnement de test Une intégration fonctionnelle prête à être testée.
  • élevée priorité Priorité de la tâche Marc a désigné le paiement par carte comme bloquant pour la campagne d'été.
  • plus de 50 % Part des commandes mobiles La raison d'inclure Apple Pay et Google Pay dans le MVP.

Incertitudes / risques

  • Il n'est pas précisé si l'enregistrement des cartes pour les paiements récurrents (saved cards) doit être pris en charge, ou seulement les paiements ponctuels.
  • Marc n'a pas mentionné de seuil précis pour le remboursement automatique (refund) — à finaliser avec l'équipe support.
  • Il n'a pas été dit dans quelles devises s'effectueront les paiements (uniquement CZK, ou aussi EUR pour les clients étrangers).

Brief pour l'implémenteur

Brief d'implémentation — Intégration de la passerelle de paiement Stripe (Projet Aurora)

Objectif

Ajouter le paiement par carte via Stripe au checkout existant de l'e-shop Projet Aurora, y compris Apple Pay et Google Pay, comme troisième mode de paiement à côté des espèces et de la facture.

Périmètre (scope)

  • Formulaire de paiement intégré via Stripe Elements directement dans le checkout (aucune redirection vers une passerelle externe).
  • Prise en charge des modes de paiement : carte, Apple Pay, Google Pay.
  • Confirmation des paiements côté serveur via webhooks (source de vérité = backend, pas le navigateur).
  • Fallback en cas d'indisponibilité de Stripe (dégradation sans faire tomber tout le checkout).

Hors périmètre (out of scope)

  • Enregistrement des cartes pour les paiements récurrents (saved cards) — non traité pour l'instant, en attente de décision.
  • Remboursements via l'UI d'administration — pour le MVP, le remboursement via le Stripe Dashboard suffit.

Exigences fonctionnelles

  1. Création du paiement
    • L'endpoint backend crée un PaymentIntent (montant, devise, idempotency_key).
    • Le frontend demande le client_secret et affiche Stripe Elements.
  2. Confirmation du paiement
    • Le statut de la commande est modifié exclusivement par le webhook payment_intent.succeeded.
    • La réponse du client sert uniquement à afficher l'écran « merci », jamais à confirmer la commande.
  3. Échec du paiement
    • Webhook payment_intent.payment_failed → la commande reste à l'état « en attente de paiement », et le client a la possibilité de réessayer.
  4. Fallback
    • En cas d'indisponibilité de Stripe, le paiement par carte est masqué et les espèces + la facture s'affichent. Le checkout ne doit pas tomber entièrement.

Exigences non fonctionnelles

  • Idempotence : chaque appel PaymentIntent utilise un idempotency key (un renvoi ne crée pas de second paiement).
  • Sécurité des webhooks : vérification de signature (Stripe-Signature), rejet des requêtes non vérifiées.
  • Secrets : les clés API Stripe exclusivement dans GCP Secret Manager, jamais dans le code ni dans un fichier .env versionné dans git.
  • Journalisation : chaque échec de paiement et chaque webhook entrant vont dans le structured logging (Cloud Logging).

Critères d'acceptation

  • Le client paie par carte et la commande est marquée comme payée uniquement après réception du webhook payment_intent.succeeded.
  • Apple Pay et Google Pay apparaissent sur les appareils compatibles et fonctionnent de bout en bout.
  • Si la connexion tombe après le paiement (navigateur fermé), la commande est tout de même marquée comme payée grâce au webhook.
  • Soumettre un paiement deux fois ne crée pas deux paiements (vérifié via l'idempotency key).
  • Un webhook falsifié sans signature valide est rejeté (HTTP 400).
  • Lors d'une panne simulée de Stripe, le checkout ne casse pas — le paiement par carte disparaît simplement.

Échéances

  • MVP sur l'environnement de test : fin juin
  • Production : 15 juillet

Questions ouvertes

  • Enregistrement des cartes pour les paiements récurrents — oui/non ?
  • Devises : uniquement CZK, ou aussi EUR ?
  • Seuil pour le remboursement automatique ?

Exemple de transcription

Marc (demandeur)

Bon, passons aux paiements. Je veux qu'on intègre enfin le paiement par carte via Stripe au checkout d'Aurora. Aujourd'hui les gens paient soit en espèces à la livraison, soit sur facture, et ça nous freine.

Marc (demandeur)

L'important, c'est que ça reste à l'intérieur, dans le même design. Pas de bascule sur une page tierce. On l'intègre via leurs Elements, pour que ça ressemble à une partie de l'e-shop.

Marc (demandeur)

Et maintenant le plus important. Jamais, vraiment jamais, ne confirmez une commande selon ce qui revient au navigateur. Uniquement selon le webhook sur le serveur. On a déjà eu un cas où quelqu'un a payé, sa connexion est tombée, et la commande est restée bloquée comme impayée. Ça ne doit pas se reproduire.

Marc (demandeur)

Considère Apple Pay et Google Pay comme faisant partie de la base, pas comme un bonus pour plus tard. Plus de la moitié des gens achètent depuis leur téléphone, donc ça doit être là tout de suite.

Marc (demandeur)

Et encore une chose. Si Stripe tombe, ne laissez pas tout le checkout planter. On masque juste la carte et les gens paient autrement. Je ne veux pas perdre une vente entière à cause d'une panne de la passerelle.

Marc (demandeur)

Au final je le veux en production pour le quinze juillet, à cause de la campagne d'été. Sur l'environnement de test, qu'il fonctionne d'ici la fin juin, pour que Lucie ait le temps de tout passer en revue correctement.

Essayer Voxibly