Paiements

Un port, pas un SDK

Le coeur du module est une interface, PaymentGateway. Toutes les opérations dont l'app a besoin pour encaisser y sont déclarées: créer un client, capturer une carte sans débit, créer une intention de paiement, ouvrir un checkout hébergé, prélever hors session, vérifier un webhook. Les routes, les crons et les pages publiques dépendent de cette interface, jamais de stripe.* en dur. Ajouter un provider, c'est écrire une classe qui implémente le port et l'enregistrer, sans toucher au reste.

Stripe Connect par workspace

Chaque workspace connecte son propre compte Stripe. La plateforme tient une seule clé secrète et agit au nom du compte connecté en passant son identifiant (acct_...) sur chaque appel Stripe. Le secret du compte connecté n'est jamais stocké: Connect Standard s'appuie sur l'auth de la plateforme plus l'en-tête de compte. Un workspace sans compte connecté retombe sur le compte plateforme (comportement mono-tenant hérité), mais un nouveau workspace doit connecter Stripe avant d'encaisser.

• Compte résolu depuis workspace_stripe_accounts, mis en cache 60 secondes
• Le drapeau connected dit si le workspace a branché son propre compte ou retombe sur la plateforme
• La clé publiable du compte connecté sert aux pages publiques qui montent Stripe Elements

Ce que le gateway sait faire

Le port couvre le cycle de vie complet d'un encaissement. Chaque opération renvoie un type normalisé, agnostique du PSP, pour que l'appelant n'écrive jamais de logique propre à Stripe.

• Client PSP: récupéré ou recréé si l'identifiant stocké est mort
• Capture de carte (SetupIntent): enregistre un moyen de paiement sans débit
• Paiement on-session (PaymentIntent): le client paie sur la page, avec 3DS géré
• Checkout hébergé: le PSP héberge la page pour un paiement ponctuel, renvoie vers succès ou annulation
• Prélèvement hors session: débite une carte enregistrée sans le client, avec clé d'idempotence contre la double charge
• Vérification de webhook: contrôle la signature et renvoie un événement normalisé

Où l'argent entre

La couche Paiements n'a pas d'écran propre. Elle est consommée par les surfaces qui vendent. Un paiement de facture ouvre une page de checkout brandée qui monte Stripe Elements et garde le client sur ton domaine. Un checkout produit crée une commande, applique livraison et coupons, encaisse via Connect. Un abonnement à une Collection facture l'end-user par-dessus. Un acompte de réservation passe par le même chemin. Sur les flux plateforme, une commission (application fee) peut être prélevée sur chaque session.

Un seul PSP écrit aujourd'hui

Le design est provider-agnostique, mais soyons honnêtes: seul Stripe est réellement implémenté derrière le port. PayPal, Mollie et Adyen sont des identifiants prévus, pas des gateways écrits. Un provider choisi mais non implémenté échoue franchement, il ne retombe jamais en silence sur Stripe: encaisser via le mauvais PSP serait pire que ne pas encaisser. Et tant que Stripe n'est pas connecté au niveau du workspace, toute cette couche reste inerte.