rubis/docs/tech/stripe-trial-with-card.md

# Migration billing : essai 14 j Pro avec CB à l'inscription

> Version : 0.1 · Dernière maj : 2026-05-18
> Référence d'arbitrage : `docs/tech/landing-optimisations.md` §3 + §6
> Statut : **À implémenter** — pas encore en code. Ce doc décrit l'archi cible + plan d'exécution.

Document de chantier pour passer le funnel signup d'**aucun engagement** (Free 2 factures par défaut, Pro via Checkout au moment où l'usage dépasse la limite) à **essai 14 jours Pro avec carte bancaire à l'inscription** (Stripe `trial_period_days`, prélèvement automatique au J+14, possibilité d'annuler en un clic).

**Pourquoi** : un essai sans CB convertit 2 à 3 fois moins qu'un essai avec CB demandée (cf. études Profitwell, ChartMogul). Le segment cœur de Rubis (TPE-PME françaises sans crédit manager) a besoin d'être confronté à la décision payante dès qu'il a senti la valeur — sinon il oublie.

---

## État actuel (avant migration)

### Flow signup courant

1. `POST /api/v1/auth/signup` — `NewAccountController.store` crée Organization vide + provision les plans par défaut + crée User.
2. Émet une `AuthSession` (Bearer + refresh cookie).
3. **Aucun appel Stripe** à l'inscription. `org.plan = 'free'`, `stripeCustomerId = null`, `stripeSubscriptionId = null`, `gracePeriodEndsAt = null` (nouvelles orgs).
4. User est redirigé vers `/onboarding/compte` → `/onboarding/entreprise` → `/onboarding/signature`.

### Upgrade Pro plus tard

1. User va sur `/parametres/abonnement`, clique « Passer Pro ».
2. SPA appelle `POST /api/v1/billing/checkout` → Stripe Checkout `mode: 'subscription'`.
3. User paye via Checkout, est ramené sur `/parametres/abonnement?checkout=success`.
4. Webhook `customer.subscription.created` → `org.plan = 'pro'`, `stripeSubscriptionId` posé.

### Limites du modèle actuel

- Le segment cœur ne paye jamais : 2 factures Free (cf. ADR-023) suffisent pour beaucoup, et la friction d'aller chercher Checkout dans les Settings est forte.
- Pas de tunnel forcé : on perd les indécis qui se disent « j'essaie plus tard » et ne reviennent pas.
- L'orga historique (3 mois grace illimitée) habituait les users à un comportement opposé.

---

## État cible

### Flow signup cible

1. `POST /api/v1/auth/signup` — Organization + User créés comme aujourd'hui.
2. **Nouveau** : `POST /api/v1/billing/start-trial` (auth, appelé juste après signup) → crée Stripe Customer + Checkout Session avec `subscription_data.trial_period_days: 14` + `payment_method_collection: 'always'`.
3. SPA redirige vers l'URL Stripe Checkout.
4. User remplit sa CB sur Checkout, est ramené sur `/onboarding/compte`. La subscription est créée en `status: 'trialing'`, `org.plan = 'pro'`, `subscriptionStatus = 'trialing'`.
5. Onboarding standard se poursuit (compte → entreprise → signature).
6. À J+14, Stripe prélève automatiquement et passe la subscription en `status: 'active'`.

### Fallback « pas de CB »

Bouton secondaire sur le Checkout-redirect screen (apps/web) :

> **Pas de CB ? Démarrer en Free (2 factures)**

→ skip le Checkout, l'org reste `free` avec `gracePeriodEndsAt: null`. Cap immédiat à 2 factures. Récupère les ultra-réticents sans casser le funnel principal.

### Email J+12 (recap avant prélèvement)

Déclenché par le webhook Stripe `customer.subscription.trial_will_end` (Stripe l'émet automatiquement 3 jours avant `trial_end` = J+11 dans notre cas — assez proche du J+12 proposé par le doc). Si on veut exactement J+12, basculer sur un scheduler interne (BullMQ / cron node-cron) qui lit `trial_end - 2 days`.

Contenu : récap usage des 12 premiers jours (factures relancées, € récupérés, rubis gagnés) + rappel date prélèvement + lien annulation 1-clic vers Customer Portal.

---

## Architecture cible

### Modifications DB

| Champ | Avant | Après | Notes |
|---|---|---|---|
| `organizations.plan` | `'free'\|'pro'\|'business'` | `'free'\|'pro'\|'business'` | Inchangé. `'pro'` couvre trial + paid. |
| `organizations.subscription_status` | `'active'\|'past_due'\|'canceled'\|...` | + `'trialing'` | Stripe l'émet déjà, on le persiste tel quel. |
| `organizations.trial_ends_at` | n'existe pas | `timestamp with timezone NULL` | Date de fin d'essai (= Stripe `subscription.trial_end`). Sert au teaser UI sans rappel Stripe à chaque page. |
| `organizations.grace_period_ends_at` | conservé | conservé | Pour les orgs historiques. Nouvelles orgs : `null`. |

Migration : ajouter `trial_ends_at` ; backfill à null pour les orgs existantes (elles ne sont pas en trial).

### Modifications API

| Endpoint | État | Action |
|---|---|---|
| `POST /api/v1/billing/start-trial` | Nouveau | Crée Customer + Checkout Session avec `trial_period_days: 14`, return URL. |
| `POST /api/v1/billing/checkout` | Existant | Conserver — pour les users qui sont passés Free (fallback) et veulent upgrader plus tard. **Sans trial dans ce cas** (déjà eu son essai). |
| `POST /api/v1/billing/webhook` | Existant | Étendre pour gérer `customer.subscription.trial_will_end` → trigger email J+12. |
| `services/billing.ts` `canCreateInvoices` | Existant | Bypass quota si `subscription_status === 'trialing'` (Pro illimité pendant l'essai). |

### Modifications Frontend (apps/web)

1. **Nouveau** : `src/routes/onboarding/billing.tsx` — étape entre `/signup` et `/onboarding/compte`.
   - Bouton primaire : « Démarrer l'essai 14 jours » → appelle `start-trial` → redirige vers Stripe Checkout.
   - Bouton secondaire : « Pas de carte ? Commencer en Free (2 factures) » → skip, redirige `/onboarding/compte`.
2. **Modifier** : `src/main.tsx` ou le guard `_app` → forcer le passage par `/onboarding/billing` tant que `org.stripeCustomerId` est null **et** que l'org ne s'est pas explicitement déclarée Free (cookie ou flag DB `org.skippedTrial`).
3. **Modifier** : `src/components/billing/PlanLimitBanner.tsx` → afficher un mini-rappel pendant le trialing (« Essai Pro · X jours restants »).
4. **Modifier** : copy signup (`src/routes/signup.tsx`) → préciser « Carte demandée à l'étape suivante, non prélevée avant J+14 ».
5. **Modifier** : landing `Hero.tsx` / `FinalCTA.tsx` — pouvoir réactiver le sous-texte CTA « CB demandée, non prélevée avant J+14 » (actuellement masqué — cf. cecbddc).

### Modifications Emails (apps/api)

1. **Nouveau template React Email** : `emails/trial_recap.tsx` — recap J+12.
2. **Nouveau template** : `emails/trial_ended_success.tsx` — confirme le passage en payant.
3. **Nouveau template** : `emails/trial_ended_failed.tsx` — paiement échoué, fallback Free + lien CB.

Contenu détaillé des trois emails en annexe ↓.

---

## Risques et mitigations

| Risque | Impact | Mitigation |
|---|---|---|
| Le Stripe Checkout est hosté → on perd le contrôle UX à l'étape la plus stressante du tunnel | Conversion -10 à -20 % vs Elements custom | Accepter en V1, on rebascule sur Payment Element custom en V2 si la conversion plafonne. Checkout est plus rapide à shipper et fiable côté compliance. |
| Webhook `trial_will_end` peut être manqué (réseau, redéploiement) | Email J+12 raté → user surpris par le prélèvement | Doubler avec un job cron quotidien (`trial-recap-cron`) qui scanne les orgs avec `subscription_status = 'trialing'` ET `trial_ends_at` dans 1-3 jours et envoie l'email idempotemment (table `email_log` avec dédoublonnage). |
| Org historique (3 mois grace) avec orgs récentes mêlées dans la table | Migration backfill incorrecte | Le champ `grace_period_ends_at` reste intouché. Le nouveau flow ne pose `trial_ends_at` que sur les orgs qui passent par `start-trial`. Pas de conflit. |
| Stripe locale FR + 3D Secure | Friction supplémentaire sur certaines cartes | Locale `fr` déjà passée au Checkout, 3DS géré nativement par Stripe. Tester en mode test avec cartes 3DS `4000 0027 6000 3184`. |
| User ferme Stripe Checkout sans valider → state incohérent | Compte créé sans CB ni redirect onboarding | Côté webhook `checkout.session.expired` → ne rien faire. Côté UI, gérer le cas `?checkout=cancel` sur `/onboarding/billing` : afficher le fallback Free + bouton « réessayer avec CB ». |
| Migration des orgs en grace period (ils ne devraient pas voir l'écran billing) | UX confuse pour les early users | Le guard `_app` ne force `/onboarding/billing` que si `org.gracePeriodEndsAt` est null. Les orgs historiques continuent leur vie sans changement. |

---

## Plan d'exécution

### PR 1 — Backend (1 j)

1. Migration `add_trial_ends_at_to_organizations.ts`.
2. Endpoint `POST /api/v1/billing/start-trial` dans `billing_controller.ts`.
3. Étendre le webhook handler :
   - `checkout.session.completed` → persister `trialEndsAt` depuis `subscription.trial_end`.
   - `customer.subscription.trial_will_end` → trigger email recap (nouveau service).
   - `customer.subscription.updated` (passage `trialing → active`) → email confirmation.
   - `customer.subscription.updated` (passage `trialing → past_due`) → email fallback.
4. Bypass `canCreateInvoices` quand `subscription_status === 'trialing'`.
5. Tests unitaires (`tests/unit/billing.spec.ts`).
6. Cron de redondance `trial-recap-cron` (BullMQ ou node-cron quotidien).

### PR 2 — Frontend tunnel (0,5 j)

1. Route `src/routes/onboarding/billing.tsx`.
2. Guard `_app` : forcer `/onboarding/billing` si trial pas encore offert.
3. Banner « Essai Pro · X jours restants » dans `PlanLimitBanner.tsx`.
4. Copy signup + landing (réactiver le sous-texte CTA « CB demandée, non prélevée avant J+14 »).

### PR 3 — Emails (0,5 j)

1. Template `emails/trial_recap.tsx`.
2. Template `emails/trial_ended_success.tsx`.
3. Template `emails/trial_ended_failed.tsx`.
4. Tester via Resend / mode dev.

### PR 4 — Tests end-to-end (0,5 j)

1. Tester en mode test Stripe :
   - Carte normale `4242 4242 4242 4242` → trial OK → prélèvement à J+14 OK.
   - Carte 3DS `4000 0027 6000 3184` → 3DS OK → trial OK.
   - Carte déclinée à J+14 `4000 0000 0000 0341` → email fallback Free OK.
2. Vérifier idempotence webhook (renvoyer 2× le même event).

Total : **2,5 j de dev**, alignés sur l'estimation initiale du doc landing-optimisations.md §6.

---

## Annexe — Contenu des emails transactionnels

### Email J+12 — Recap d'essai

**Sujet** : Plus que 2 jours d'essai — voilà ce que Rubis a déjà fait pour vous.

**Preheader** : X factures relancées, Y € récupérés, Z minutes libérées. Récap avant le prélèvement.

**Body** :

```
Bonjour {{prenom}},

12 jours que vous testez Rubis. Petit récap avant le prélèvement de
votre abonnement Pro dans 2 jours (le {{date_prelevement}}).

Ce que Rubis a fait pour vous depuis le {{date_signup}} :

  ◆ {{nb_factures_importees}} factures importées
  ◆ {{nb_relances_envoyees}} relances envoyées automatiquement
  ◆ {{euros_recuperes}} € encaissés
  ◆ {{nb_rubis_gagnes}} rubis ≈ {{heures_liberees}} de votre temps
    que vous n'avez pas passé à relancer

[ICI un bloc visuel avec les 4 chiffres, gros, rubis sur crème]

Si tout est OK, vous n'avez rien à faire — votre essai bascule en Pro
mensuel à {{prix_pro_ttc}} TTC le {{date_prelevement}}. Vous gardez
toutes vos données, tous vos plans de relance, toutes vos relances en
cours.

Si vous voulez annuler, c'est en un clic depuis vos paramètres :

  [Annuler mon essai →]

Vos relances en cours s'arrêteront le {{date_prelevement}} et vous
basculerez automatiquement sur le plan Free (2 factures actives).

Une question ? Répondez à ce mail, je le lis personnellement.

Belle journée,
Arthur — fondateur de Rubis
```

**Variables à interpoler** :

- `{{prenom}}` — `user.fullName.split(' ')[0]`
- `{{date_signup}}` — `org.createdAt` formaté FR
- `{{date_prelevement}}` — `org.trialEndsAt` formaté FR
- `{{prix_pro_ttc}}` — `19 €` ou `49 €` selon plan
- `{{nb_factures_importees}}` — count(invoices where org_id=… and created_at >= signup_date)
- `{{nb_relances_envoyees}}` — count(reminder_logs where status='sent' and org_id=…)
- `{{euros_recuperes}}` — sum(amount_cents) where status='paid' and paid_at >= signup_date
- `{{nb_rubis_gagnes}}` — org.rubisCount
- `{{heures_liberees}}` — formatRubisToHours(rubisCount)

### Email J+14 — Trial → active (succès)

**Sujet** : Bienvenue dans Rubis Pro — votre paiement est passé.

**Body** :

```
Bonjour {{prenom}},

Votre essai est terminé et le prélèvement de {{prix_pro_ttc}} a été
effectué avec succès. Vous êtes officiellement en Pro.

Pas de changement de votre côté — toutes vos factures, plans de
relance et automatisations continuent comme avant, sans aucune
interruption.

Trois choses utiles à connaître maintenant :

  ◆ Votre facture Stripe est disponible dans vos paramètres
    [Voir mes factures Rubis →]

  ◆ Vous pouvez changer de carte ou de cycle (annuel = 2 mois
    gratuits) en un clic
    [Gérer mon abonnement →]

  ◆ Vous pouvez annuler à tout moment depuis le même écran. Aucune
    question posée.

Merci de votre confiance.

Arthur — fondateur de Rubis
```

### Email J+14 — Trial → past_due (échec paiement)

**Sujet** : Votre essai Rubis a expiré — paiement à régulariser.

**Body** :

```
Bonjour {{prenom}},

Votre essai 14 jours est arrivé à son terme, mais le prélèvement de
{{prix_pro_ttc}} sur votre carte n'a pas pu aboutir
({{stripe_decline_code_humain}}).

Pas de panique : pendant 7 jours, votre compte reste en Pro et toutes
vos relances continuent comme avant. Il vous suffit de mettre à jour
votre carte pour rester sur Pro :

  [Mettre à jour ma carte →]

Au-delà de 7 jours sans paiement valide, votre compte bascule
automatiquement sur le plan Free (2 factures actives). Vos données
restent intactes, mais les relances au-delà de 2 factures simultanées
sont mises en pause.

Une question ? Répondez à ce mail, je vous réponds dans la journée.

Belle journée,
Arthur — fondateur de Rubis
```

---

## Décisions ouvertes

À documenter en ADR au moment de l'implémentation :

1. **Tunnel forcé vs onboarding optionnel** : l'écran `/onboarding/billing` doit-il être bloquant (pas d'accès au reste sans choix CB ou Free) ou skippable (« plus tard ») ? Recommandation : bloquant, sinon on perd le bénéfice principal du tunnel.
2. **Stripe Checkout vs Payment Element custom** : tradeoff UX vs time-to-ship. Recommandation V1 : Checkout (compliance gratuite, locale FR native). V2 si la conversion plafonne : Payment Element intégré.
3. **Email J+12 timing exact** : Stripe émet `trial_will_end` à J+11 par défaut. On peut soit accepter (1 jour d'écart sans importance), soit overrider via cron interne pour avoir J+12 pile. Recommandation : accepter le J+11 Stripe (moins de complexité), reformulater le copy "Plus que 3 jours" au lieu de "Plus que 2 jours" si besoin.
4. **Org historique en grace** : on les laisse purger naturellement leurs 3 mois, ou on les force à passer par l'écran trial dès leur prochain login ? Recommandation : laisser purger — moins de churn brutal.

---

*Document maintenu en parallèle de `docs/tech/landing-optimisations.md`. Implémentation à faire dans une session dédiée avec accès Stripe test mode + clé webhook signing secret de test.*