Aller au contenu
Meubles Morinière

Les choix d’ingénierieÉtudes de cas techniques8 min de lecture

Tenir une pièce pendant un paiement

Le site et le magasin vendent le même stock, et l’argent arrive par Stripe des minutes ou des jours plus tard. Je raconte comment on évite qu’une pièce unique se vende deux fois, sans table de réservations à faire expirer ni à nettoyer.

Le problème

Le magasin vend beaucoup de pièces uniques : un tableau accroché au showroom, un meuble d’exposition, une fin de série. Le 1er septembre 2026, 40 fiches sur 215 n’existaient qu’en un seul exemplaire (293ee3e03b). Ces pièces se vendent au magasin comme sur le site.

Le paiement en ligne se fait chez Stripe, en dehors de l’application. Entre la page de commande et la confirmation, il peut se passer plusieurs minutes. Et entre le paiement et le webhook qui l’annonce à l’ERP, il se passe parfois plusieurs heures. Au début, le tunnel de commande vérifiait le stock sans rien retenir, et le stock ne baissait qu’à l’arrivée du webhook. L’audit du stock du 1er septembre a montré ce que ça donnait. Deux acheteurs passent le contrôle à dix minutes d’écart et paient tous les deux. Quand le second webhook arrive, le stock est déjà à zéro. La commande reste payée et une alerte part, mais deux clients ont été débités pour un seul objet. À l’époque, une session Stripe durait vingt-quatre heures.

Les contraintes

  • Stripe impose ses limites. Une session expire entre trente minutes et vingt-quatre heures après sa création, et Stripe refuse un expires_at à moins de trente minutes de son horloge. Un webhook non acquitté est relivré pendant trois jours (STRIPE_EVENT_RETRY_SECONDS). Du coup, une session payée peut rester « en attente » dans la base longtemps après son expiration.
  • Seul l’ERP peut marquer une commande payée. Le site, lui, crée seulement des commandes en attente de paiement (Le site n’a que les droits qu’il lui faut). Donc ce qui retient la pièce doit pouvoir se lire depuis cette commande.
  • Une pièce fabriquée à la commande n’a pas besoin d’être retenue. Si deux clients commandent le même modèle, l’atelier en fabrique deux. Dans ce cas, laisser vingt-quatre heures au client pour réfléchir, c’est juste du confort, et ça ne risque rien.
  • Le magasin doit voir ce que le site retient, et inversement. Et la fiche ne doit pas afficher une rupture le temps d’un paiement.
  • Aucune tâche planifiée ne tourne à la minute. Il n’y en a qu’une, la veille, et elle passe une fois par jour. On ne peut pas compter sur elle pour nettoyer des réservations expirées.

Les alternatives

Il y avait quatre façons de faire.

  • Raccourcir la session. C’est ce qui a été fait le 1er septembre (293ee3e03b) : trente minutes dès qu’une ligne a un stock suivi, alors qu’avant c’était vingt-quatre heures. Le commit le dit lui-même : « Ce n’est PAS une réservation […] Réduire la fenêtre ne ferme pas le trou, elle le rétrécit de 48× ». C’était une solution d’attente.
  • Créer une table de réservations. Le même commit l’a reportée : elle attendait de savoir quelles familles de meubles le magasin tient en stock, parce que sans ça, on ne sait pas ce qu’il faudrait réserver. Une vraie réservation « persiste l’intention de PRENDRE la pièce et coûte une colonne, une expiration à balayer et un chemin de libération ». Et chaque chemin oublié laisse une pièce bloquée, ou la libère trop tôt.
  • Décrémenter le stock dès la création de la commande et le rendre à l’expiration. Ça revient au même qu’une table. En plus, le solde est faux tant que la session est ouverte, et il faut écrire un mouvement de stock pour une vente qui n’a pas eu lieu.
  • Déduire la réservation d’un état qui existe déjà. Une commande du site, en attente et assez récente pour être encore payable, retient ses pièces. On n’écrit rien pour réserver, donc il n’y a rien à faire expirer ni à libérer.

La décision

La réservation n’est écrite nulle part, on la déduit. Une commande retient ses pièces tant qu’elle remplit quatre conditions : elle a été passée sur le site, elle attend son paiement, l’atelier ne l’a pas annulée, et elle a été créée il y a moins longtemps que sa fenêtre (pendingReservationWhere, packages/domain/src/stock-reservation.ts). La commande porte déjà ces quatre informations pour d’autres raisons.

Les événements de Stripe peuvent libérer la pièce plus tôt, par des transitions que le paiement gère déjà. Quand le paiement est encaissé, la pièce sort du stock. Quand la session expire, la commande passe en CANCELED. Quand un paiement différé échoue, elle passe en FAILED. Dans tous les autres cas, c’est le temps qui libère la pièce.

La règle, c’est une seule condition de requête. Un test la rejoue sur une vraie base, avec deux acheteuses pour une seule pièce.

pendingReservationWherepackages/domain/src/stock-reservation.ts · lignes 25–51
/**
 * Les commandes du site qui tiennent encore leurs pièces : impayées, et ouvertes depuis moins
 * longtemps que leur session de paiement (et le délai de reprise des événements Stripe, quand une
 * session est partie). Une commande que l'atelier a annulée avant son paiement n'en tient plus :
 * payée quand même, elle ne prend rien au stock (`settleCanceledOrder`). Une pièce réservée n'est pas
 * libre pour le paiement du site, son panier et sa page de commande (`withFreeStock`), ni pour les
 * gestes de l'ERP qui servent une commande déjà payée (changement de variante, rupture servie). La
 * vente au magasin (vente hors site, devis accepté au comptoir), elle, la prend sur le stock brut :
 * le client est là, la pièce en main ; le paiement en ligne qui la tenait se ferme ensuite
 * (`releaseSoldReservations`). Les soldes AFFICHÉS de la fiche et le « Disponible » de
 * la console restent le stock brut : la caisse dit au client que la pièce est en cours de paiement
 * (`StockShortage.isInPayment`).
 */
export function pendingReservationWhere(nowMs: number): Prisma.OrderWhereInput {
	return {
		channel: SaleChannel.WEB,
		paymentStatus: PaymentStatus.PENDING,
		fulfillmentStatus: { not: FulfillmentStatus.CANCELED },
		OR: [
			{ createdAt: { gt: new Date(nowMs - CHECKOUT_RESERVATION_WINDOW_MS) } },
			{
				stripeSessionId: { not: null },
				createdAt: { gt: new Date(nowMs - CHECKOUT_PAYABLE_RESERVATION_WINDOW_MS) },
			},
		],
	};
}

L’implémentation

Deux fenêtres de temps

Les deux durées sont calculées à partir des règles de Stripe (packages/domain/src/checkout-session.ts).

  • Une commande sans session Stripe retient ses pièces le temps d’une session, plus une heure de marge (CHECKOUT_RESERVATION_WINDOW_MS).
  • Une commande qui a ouvert une session les retient aussi pendant les trois jours où Stripe peut encore relivrer l’événement de paiement (CHECKOUT_PAYABLE_RESERVATION_WINDOW_MS). Du coup, si le webhook d’une session payée se perd, la pièce ne part pas chez quelqu’un d’autre.
Les deux fenêtres pendant lesquelles une commande en attente retient ses piècesAucune session Stripe n’a été ouverte : durée d’une session 31 min + marge 1 h = 1 h 31 min, pièce libérée. Une session Stripe a été ouverte : session Stripe 31 min + relivraison Stripe 3 j + marge 1 h = 3 j 1 h 31 min, pièce libérée. Un événement Stripe reçu libère la pièce plus tôt. Quand la commande est payée, la pièce sort du stock. Quand la session expire ou que le paiement est refusé, la commande se ferme.Aucune session Stripe n’a été ouverte0commande crééedurée d’une session31 minmarge1 h1 h 31 minpièce libéréeUne session Stripe a été ouverte0commande crééesession Stripe31 min31 minla session expirerelivraison Stripe3 j3 j 31 minfin des relivraisonsmarge1 h3 j 1 h 31 minpièce libéréeUn événement Stripe reçu libère la pièce plus tôt. Quand la commande est payée, la piècesort du stock. Quand la session expire ou que le paiement est refusé, la commande se ferme.
Durées lues dans packages/domain/src/checkout-session.ts à chaque build de cette documentation. Les segments sont à l’échelle entre eux, sauf la relivraison, coupée. Une commande où tout se fabrique à la commande ne retient rien, et sa session dure 23 h 59 min.

Dans le doute, il vaut mieux retenir la pièce trop longtemps que pas assez. Au pire, on perd une vente. Une pièce libérée trop tôt, elle, fait payer deux clients. Quand une commande reste en attente après la fin de sa session, l’équipe est prévenue (STALE_PENDING_TRACKED_SESSION_MAX_AGE_MS). La consigne, c’est d’aller voir la session chez Stripe avant de toucher à quoi que ce soit, parce que le client a peut-être payé.

Une session qui dure selon ce qu’elle retient

La session dure trente et une minutes dès qu’une ligne a un stock suivi, et vingt-quatre heures moins une minute quand tout est fabriqué à la commande (checkoutSessionTtlSeconds). La minute de marge au-dessus du minimum de Stripe ne suffisait pas toujours. Entre les nouvelles tentatives du SDK et le décalage d’horloge, elle partait vite, et le client tombait sur « paiement indisponible ». Du coup, quand Stripe refuse seulement à cause de l’heure, on recrée la session une fois, avec une échéance recalculée et une autre clé d’idempotence (createCheckoutSessionWithFreshExpiry).

La même règle partout

Avant d’accepter une commande, le site verrouille les déclinaisons suivies avec FOR UPDATE, par ordre croissant d’identifiant pour éviter les interblocages. Ensuite il enlève ce que les autres commandes retiennent (reservedElsewhereByVariant), puis il compare le reste au stock (findTrackedStockShortage). Le panier fait la même soustraction avant d’afficher ce qui reste, pour ne pas promettre une pièce que le paiement refusera. Dans l’ERP, le changement de déclinaison passe par la même règle. La vente au magasin, elle, passe devant : elle prend la pièce sur le stock brut, puis elle ferme les sessions Stripe qui la retenaient (releaseSoldReservations). Les codes promo à usage limité aussi : une session payée dont l’événement arrive des heures plus tard garde son code jusque-là (promotion-redemptions.ts).

Ne pas se bloquer soi-même

Une cliente qui revient de Stripe pour corriger son adresse e-mail ne doit pas être bloquée par sa propre réservation. Du coup, la commande en attente de son navigateur (gardée dans le panier scellé) ne compte pas contre elle, ni, quand elle est connectée à son compte, celles passées avec la même adresse. Dès qu’elle ouvre une nouvelle session, ses sessions précédentes sur les mêmes pièces sont fermées (supersedeEarlierSessions). Une adresse saisie par un invité ne prouve rien : elle ne lève aucune réservation et ne ferme la session de personne, sans quoi un inconnu qui connaît l’adresse d’une cliente fermerait sa page de paiement (CheckoutGuard#isEmailProven).

L’affichage reste le même

La fiche et le « Disponible » de l’ERP affichent toujours le stock brut. Si le stock suffit mais qu’un paiement en cours retient la pièce, le tunnel de commande le dit tel quel (StockShortage.isInPayment). Il ne parle pas de rupture.

Les résultats

Maintenant, la seconde acheteuse est refusée avant de payer. Avant, elle était débitée puis remboursée. apps/site/test/db/tracked-stock-reservation.db.test.ts rejoue la situation sur une vraie base. Une pièce unique ne donne qu’une seule commande. Une commande créée pendant l’attente du verrou est bien vue à la relecture. La pièce revient quand la session expire ou quand la fenêtre est passée. Le client qui recommence ne se bloque pas lui-même, et la commande d’un autre navigateur retient toujours la pièce.

Il n’y a rien à nettoyer. Il n’y a pas de colonne de réservation, pas de tâche d’expiration et pas de chemin de libération à maintenir. Une commande abandonnée arrête de retenir quoi que ce soit, même si plus aucun code n’y touche.

Un test vérifie aussi l’ordre des verrous : apps/erp/test/variant-lock-order.regression.test.ts relit le tunnel, le comptage en lot et la vente hors site.

Et si une pièce manque quand même au moment de l’encaissement, ça se voit. L’ERP encaisse, passe la ligne en rupture et lève l’alerte webhook.stock (webhook-session.service.ts).

Les limites

  • À chaque lecture, on recalcule les réservations en agrégeant les commandes en attente. Au volume d’un magasin, ça fait quelques lignes. Pour une grande boutique, il faudrait un index dédié ou un compteur.
  • La fenêtre de trois jours peut retenir une pièce pour rien si l’événement d’expiration se perd. Dans ce cas, la pièce reste bloquée jusqu’à la fin de la fenêtre, ou jusqu’à ce que l’équipe ferme la session. C’est à ça que sert l’alerte de la veille.
  • Un invité qui reprend son paiement depuis un autre appareil est bloqué par sa propre réservation jusqu’à ce que la première session expire : seul le compte prouve que deux commandes viennent de la même personne.
  • Un paiement laissé en suspens retient ses pièces. Une même connexion en retient au plus CHECKOUT_MAX_RESERVED_PIECES_PER_IP, en plus du plafond de commandes en attente : trois paniers pleins jamais payés gelaient sinon tout le stock du site.

Sur cette page