v1.0.1 : payer par carte à la caisse

Je m’appelle Badii Boutar, et je construis The Merchant Engine seul. La v1.0.1 est sortie, et un client peut maintenant payer par carte à la caisse. Stripe est le premier prestataire de carte. Jusqu’à cette version, on ne pouvait payer qu’à la livraison, par virement bancaire manuel ou avec une carte-cadeau, et je l’ai écrit dans chaque comparaison. Cette phrase est maintenant fausse dans mes propres articles, donc je les ai corrigés.

Une précision : la documentation est en anglais pour l’instant, donc les liens vers les docs mènent à des pages en anglais.

Ce qui change pour le client

Stripe apparaît à la caisse comme un moyen de paiement, et le propriétaire de la boutique choisit son affichage, moyen de paiement par moyen de paiement :

• Intégré. Le formulaire de carte est dans la page de caisse, avec le Payment Element de Stripe.
• Hébergé. Le client est envoyé vers une page Stripe Checkout, puis revient après avoir payé.

Le paiement à la livraison fonctionne comme avant, tout comme le virement bancaire et les cartes-cadeaux. Plusieurs moyens de paiement peuvent être actifs en même temps, chacun avec ses propres clés.

Une réponse, quatre actions

Passer une commande (POST /v1/orders) renvoie maintenant un paymentAction à côté de la commande. Il dit à la vitrine quoi faire ensuite, et type prend l’une de ces quatre valeurs :

• none : rien à faire. Le paiement à la livraison et le virement manuel répondent ça.
• redirect : envoyer le client vers une page de paiement hébergée, à l’adresse url.
• form_post : envoyer fields en POST vers url.
• embedded : afficher le formulaire du prestataire dans la page, avec clientToken et publicConfig.

La vitrine a un seul gestionnaire pour les quatre. Un nouveau prestataire n’exige aucun changement dans la vitrine, sauf s’il est embedded. C’était le but de cette conception : la vitrine ne doit pas savoir ce qu’est Stripe.

La commande existe avant que le client paie

Si un paiement par carte échoue, ou si le client ferme l’onglet, la commande reste en attente. Deux endpoints permettent de reprendre :

• POST /v1/orders/{id}/payment lance un nouveau paiement pour une commande impayée. Il répond 409 quand la commande ne peut plus être payée.
• POST /v1/orders/{id}/payment/confirm demande au prestataire l’état réel du paiement quand le client revient.

Les deux exigent un X-Idempotency-Key, comme pour passer une commande. J’ai expliqué pourquoi dans idempotent checkout in NestJS, un article en anglais. Le webhook du prestataire reste la source de vérité pour l’état « payé ». L’appel de confirmation sert seulement à ce que la page vue par le client se mette à jour plus vite.

Les clés se saisissent dans l’admin

L’opérateur saisit les clés Stripe dans le formulaire du moyen de paiement, dans l’admin. Les champs secrets sont chiffrés au repos avec AES-256-GCM, à partir d’une clé fournie par PAYMENT_CONFIG_ENCRYPTION_KEY. Les anciennes clés restent lisibles grâce à PAYMENT_CONFIG_ENCRYPTION_KEYS_PREVIOUS, ce qui permet de faire une rotation sans se verrouiller dehors.

Si cette clé n’est pas définie, l’application démarre quand même. Enregistrer un secret répond alors PAYMENT_CONFIG_ENCRYPTION_UNAVAILABLE, donc vous le découvrez dans le formulaire et pas à la première commande.

STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET et STRIPE_PUBLISHABLE_KEY fonctionnent toujours en solution de repli, et les clés saisies dans l’admin l’emportent quand les deux existent.

Ce qu’il ne fait toujours pas

• Stripe est le seul prestataire de carte. Si vous en avez besoin d’un autre le jour du lancement, cette boutique n’est pas encore la bonne. La marche à suivre pour ajouter un prestataire est écrite, et l’interface PaymentProvider est l’endroit où il se branche.
• Je suis seul. Je le teste, je le corrige et je réponds aux issues. Pesez-le avant d’y mettre l’activité d’un client.
• Essayez d’abord le mode test de Stripe. Payez avec une carte de test, faites échouer un paiement, puis revenez à la commande, avant d’activer le tout pour de vrai. Checkout and orders décrit le déroulement.

La version ajoute aussi des codes d’erreur stables pour quelques conflits : CATEGORY_SLUG_TAKEN, CATEGORY_HAS_PRODUCTS, REVIEW_ALREADY_PUBLISHED et QUESTION_ALREADY_PUBLISHED.

Ce que je ferais

Passez une commande sur la démo de la vitrine, puis regardez le formulaire du moyen de paiement dans la démo de l’admin. Pour le lancer chez vous, suivez le guide d’installation, saisissez des clés de test Stripe dans l’admin et payez avec une carte de test.

Le code est sur GitHub, sous licence MIT. Si le paiement par carte casse chez vous, ouvrez une issue. Si vous avez besoin d’un prestataire que je n’ai pas construit, dites-moi lequel dans la discussion sur les retours.