Skip to content

Architecture Stripe - Design Technique

Date de création : 11 novembre 2025
Statut : 🔵 Design technique
Propriétaire : Équipe Dev
Dernière mise à jour : 15 décembre 2025

📖 Guide d'Utilisation

Ce document décrit : - Architecture globale : Comment tout s'imbrique - Flux de paiement : Comment les paiements fonctionnent - Flux d'authentification : Comment l'authentification fonctionne - Sécurité : Comment les données sont protégées - Stockage : Où les données sont stockées

✅ État actuel (implémentation as-is)

L'intégration Stripe actuellement en place dans Firebase est basée sur une Firebase Extension (et non sur des Cloud Functions “maison” déclarées dans ce repo) :

  • Extension Firebase : invertase/firestore-stripe-payments (Firestore Stripe Payments)
  • Fonctions déployées par l'extension (exemples) :
  • ext-firestore-stripe-payments-createCustomer
  • ext-firestore-stripe-payments-createCheckoutSession
  • ext-firestore-stripe-payments-handleWebhookEvents
  • ext-firestore-stripe-payments-createPortalLink
  • ext-firestore-stripe-payments-onUserDeleted
  • ext-firestore-stripe-payments-onCustomerDataDeleted
  • Secrets Stripe : stockés dans Google Cloud Secret Manager (gérés par l'extension), notamment :
  • STRIPE_API_KEY
  • STRIPE_WEBHOOK_SECRET
  • Collections Firestore utilisées par l'extension :
  • customers/{uid}/checkout_sessions/{sessionId}
  • customers/{uid}/subscriptions/{subscriptionId}
  • products (paramétrage extension)
  • customers (paramétrage extension)

Note (environnements) : - DEV/TEST : la PWA de test https://yinshi-test.yinshi.app/ pointe vers yin-shi-dev (extension installée côté DEV/TEST). - PROD : la migration/alignement de la prod vers cette extension (et/ou son paramétrage équivalent) n'est pas encore faite.

Pour les choix d'environnements (test/prod) : - décision : docs/06_decisions/ADR-001-environnements-firebase-stripe-pwa-first.md - plan de mise en place : docs/05_chantiers_actifs/stripe/OPTIONS_ENVIRONNEMENTS_TEST_PROD.md

🏗️ Architecture Globale

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT (Flutter App)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  Auth Screen │  │ Payment      │  │ Settings     │       │
│  │              │  │ Screen       │  │ Screen       │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                            ↕ HTTPS
┌─────────────────────────────────────────────────────────────┐
│                    FIREBASE (Backend)                        │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Firebase Auth                                       │   │
│  │  - Email/Password                                    │   │
│  │  - Google OAuth                                      │   │
│  │  - Apple OAuth                                       │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Firestore Database                                  │   │
│  │  - app_users (profils)                               │   │
│  │  - customers (infos Stripe)                          │   │
│  │  - audit_logs (traçabilité)                          │   │
│  │  - webhook_logs (webhooks)                           │   │
│  │  - invoices (factures)                               │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Cloud Functions                                     │   │
│  │  - handleStripeWebhook (validation webhooks)         │   │
│  │  - createCheckoutSession (créer session)             │   │
│  │  - handlePaymentSuccess (paiement réussi)            │   │
│  │  - handlePaymentFailure (paiement échoué)            │   │
│  │  - deleteUserData (suppression compte)               │   │
│  │  - exportUserData (export données)                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕ HTTPS
┌─────────────────────────────────────────────────────────────┐
│                    STRIPE (Payment Provider)                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Stripe API                                          │   │
│  │  - Checkout Sessions                                 │   │
│  │  - Customers                                         │   │
│  │  - Subscriptions                                     │   │
│  │  - Invoices                                          │   │
│  │  - Webhooks                                          │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

🔄 Flux de Paiement

1. Initiation du Paiement

User clicks "Subscribe"
    ↓
App calls Cloud Function: createCheckoutSession
    ↓
Cloud Function:
  - Vérifier authentification
  - Créer session Stripe
  - Stocker session_id dans Firestore
    ↓
Stripe retourne URL de checkout
    ↓
App ouvre URL dans navigateur
    ↓
User remplit les infos de paiement
    ↓
User clique "Pay"

Code Flutter : 

Future<void> startCheckout(BuildContext context, PaymentPlanModel product) async {
  final checkout = FirebaseFirestore.instance
      .collection('customers')
      .doc(FirebaseAuth.instance.currentUser!.uid)
      .collection('checkout_sessions')
      .doc();

  await checkout.set({
    'price': product.stripePriceId,
    'success_url': 'https://yinshi.com/success',
    'cancel_url': 'https://yinshi.com/cancel',
  });

  checkout.snapshots().listen((snapshot) {
    final data = snapshot.data();
    if (data?.containsKey('url') ?? false) {
      launchUrl(Uri.parse(data!['url']));
    }
  });
}

Note : dans le code actuel, les URLs utilisées sont : - success_url: https://yinshi.app/web - cancel_url: https://yinshi.app/web/#/premium-plans

Note (DEV/TEST PWA-first) : l'URL Web de test prévue est https://yinshi-test.yinshi.app/ (voir ADR-001). Les URLs de retour Stripe (success/cancel) doivent pointer vers l'environnement correspondant.

2. Traitement du Paiement

Stripe processes payment
    ↓
Payment successful
    ↓
Stripe sends webhook: payment_intent.succeeded
    ↓
Cloud Function: handleStripeWebhook
  - Vérifier signature HMAC-SHA256
  - Vérifier timestamp
  - Logger le webhook
  - Créer facture
  - Mettre à jour rôle utilisateur
  - Envoyer email de confirmation
    ↓
Firestore updated:
  - customers.subscriptionStatus = "active"
  - app_users.role = "paid"
  - invoices créée
  - audit_logs créé
    ↓
User reçoit email de confirmation

Code Cloud Function : 

exports.handleStripeWebhook = functions.https.onRequest((req, res) => {
  const signature = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.rawBody,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  // Log webhook
  admin.firestore().collection('webhook_logs').add({
    timestamp: admin.firestore.FieldValue.serverTimestamp(),
    event_id: event.id,
    type: event.type,
    status: 'received'
  });

  // Handle payment success
  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    const customerId = paymentIntent.customer;

    // Update user role
    admin.firestore().collection('customers').doc(customerId).update({
      subscriptionStatus: 'active',
      updatedAt: admin.firestore.FieldValue.serverTimestamp()
    });
  }

  res.status(200).json({received: true});
});

3. Gestion des Erreurs

Payment fails
    ↓
Stripe sends webhook: payment_intent.payment_failed
    ↓
Cloud Function: handlePaymentFailure
  - Logger l'erreur
  - Mettre à jour statut
  - Envoyer email d'alerte
  - Planifier retry automatique
    ↓
Stripe retry automatiquement (3 fois)
    ↓
Si succès : Webhook payment_intent.succeeded
Si échec : Webhook invoice.payment_failed
    ↓
Cloud Function: handleInvoicePaymentFailed
  - Annuler l'abonnement
  - Mettre à jour rôle utilisateur
  - Envoyer email d'alerte

🔐 Flux d'Authentification

1. Inscription

User enters email + password
    ↓
App calls Firebase Auth: createUserWithEmailAndPassword
    ↓
Firebase Auth:
  - Valider email format
  - Hacher le mot de passe
  - Créer compte
  - Envoyer email de vérification
    ↓
Cloud Function: onCreate (trigger)
  - Créer profil utilisateur dans Firestore
  - Ajouter rôle "trial"
  - Ajouter date d'essai (30 jours)
  - Créer audit log
    ↓
User reçoit email de vérification
    ↓
User clique sur lien
    ↓
Email vérifié

Code Flutter : 

Future<void> signUp(String email, String password) async {
  try {
    await FirebaseAuth.instance.createUserWithEmailAndPassword(
      email: email,
      password: password,
    );

    // Cloud Function crée le profil automatiquement
  } catch (e) {
    throw Exception('Erreur inscription: $e');
  }
}

2. Connexion

User enters email + password
    ↓
App calls Firebase Auth: signInWithEmailAndPassword
    ↓
Firebase Auth:
  - Vérifier email existe
  - Vérifier mot de passe correct
  - Créer session
    ↓
Cloud Function: onSignIn (trigger)
  - Vérifier email vérifié
  - Vérifier statut d'essai
  - Créer audit log
    ↓
App récupère profil utilisateur
    ↓
App affiche écran principal

3. Suppression de Compte

User clicks "Delete account"
    ↓
App demande confirmation
    ↓
App calls Cloud Function: deleteUserData
    ↓
Cloud Function:
  - Vérifier authentification
  - Annuler abonnement Stripe
  - Supprimer données Firestore
  - Supprimer compte Firebase Auth
  - Créer audit log
    ↓
Firestore updated:
  - app_users supprimé
  - customers supprimé
  - audit_logs supprimé
    ↓
Firebase Auth: compte supprimé
    ↓
User reçoit email de confirmation

💾 Modèle de Données Firestore

Collection : app_users

/app_users/{uid}
├── uid : string (Firebase UID)
├── email : string
├── role : string (trial, paid, expired, admin)
├── trialEndDate : timestamp
├── createdAt : timestamp
├── updatedAt : timestamp
├── lastLoginDate : timestamp
├── lastLogoutDate : timestamp
├── language : string (fr, en, etc.)
├── consentement_accepte : boolean
├── date_consentement : timestamp
└── version_consentement : string

Collection : customers

/customers/{uid}
├── uid : string (Firebase UID)
├── stripeCustomerId : string
├── subscriptionStatus : string (active, canceled, etc.)
├── subscriptionId : string
├── priceId : string
├── currentPeriodStart : timestamp
├── currentPeriodEnd : timestamp
├── canceledAt : timestamp
└── updatedAt : timestamp

Collection : audit_logs

/audit_logs/{logId}
├── timestamp : timestamp
├── user_id : string
├── action : string (login, payment, role_change, etc.)
├── result : string (success, failure)
├── details : object
│   ├── amount : number (si paiement)
│   ├── currency : string (si paiement)
│   ├── error : string (si erreur)
│   └── ...
└── ip : string (optionnel)

Collection : webhook_logs

/webhook_logs/{logId}
├── timestamp : timestamp
├── event_id : string
├── type : string (payment_intent.succeeded, etc.)
├── status : string (received, processed, error)
├── details : object
└── error : string (si erreur)

Collection : invoices

/customers/{uid}/invoices/{invoiceId}
├── stripe_invoice_id : string
├── amount : number
├── currency : string
├── date : timestamp
├── status : string (draft, open, paid, void)
├── pdf_url : string
└── metadata : object

🔒 Sécurité - Firestore Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    // === app_users : Accès restreint au propre profil ===
    match /app_users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // === customers : Accès restreint au propre profil ===
    match /customers/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;

      // === invoices : Accès restreint au propre profil ===
      match /invoices/{invoiceId} {
        allow read: if request.auth != null && request.auth.uid == userId;
      }
    }

    // === audit_logs : Seuls admins peuvent lire ===
    match /audit_logs/{logId} {
      allow read: if isAdmin();
      allow write: if false;
    }

    // === webhook_logs : Seuls admins peuvent lire ===
    match /webhook_logs/{logId} {
      allow read: if isAdmin();
      allow write: if false;
    }

    // === Fonction utilitaire : vérifie si l'utilisateur est admin ===
    function isAdmin() {
      return request.auth != null
        && exists(/databases/$(database)/documents/app_users/$(request.auth.uid))
        && get(/databases/$(database)/documents/app_users/$(request.auth.uid)).data.role == "admin";
    }
  }
}

🌐 Cloud Functions

Note : les fonctions décrites ci-dessous représentent le design cible. Côté DEV/TEST (PWA-first), le flux Stripe est assuré via l'extension invertase/firestore-stripe-payments (fonctions préfixées ext-firestore-stripe-payments-*). Côté PROD, la migration/alignement vers cette extension (ou équivalent) reste à faire.

Function 1 : handleStripeWebhook

Trigger : HTTP POST
Endpoint : /webhooks/stripe
Sécurité : Validation HMAC-SHA256

Responsabilités : - Valider la signature du webhook - Logger le webhook - Traiter l'événement - Mettre à jour Firestore - Envoyer emails

Événements traités : - payment_intent.succeeded : Paiement réussi - payment_intent.payment_failed : Paiement échoué - invoice.payment_failed : Facture non payée - customer.subscription.deleted : Abonnement annulé

Function 2 : createCheckoutSession

Trigger : Firestore write
Path : /customers/{uid}/checkout_sessions/{sessionId}
Sécurité : Authentification Firebase

Responsabilités : - Vérifier authentification - Créer session Stripe - Stocker session_id - Générer URL de checkout

Function 3 : deleteUserData

Trigger : HTTP POST
Endpoint : /users/delete
Sécurité : Authentification Firebase

Responsabilités : - Vérifier authentification - Annuler abonnement Stripe - Supprimer données Firestore - Supprimer compte Firebase Auth - Créer audit log - Envoyer email de confirmation

Function 4 : exportUserData

Trigger : HTTP POST
Endpoint : /users/export
Sécurité : Authentification Firebase

Responsabilités : - Vérifier authentification - Récupérer toutes les données - Générer JSON/CSV - Chiffrer le fichier - Envoyer lien par email

📊 Flux de Données - Diagramme Complet

┌─────────────────────────────────────────────────────────────┐
│                     USER ACTIONS                             │
├─────────────────────────────────────────────────────────────┤
│  1. Sign up → Firebase Auth → Create profile                │
│  2. Login → Firebase Auth → Load profile                    │
│  3. Subscribe → Stripe Checkout → Payment                   │
│  4. Delete account → Cloud Function → Delete all data       │
│  5. Export data → Cloud Function → Download JSON            │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                   FIRESTORE DATABASE                         │
├─────────────────────────────────────────────────────────────┤
│  app_users → User profiles & roles                          │
│  customers → Stripe customer info                           │
│  audit_logs → All actions (admin only)                      │
│  webhook_logs → Stripe webhooks (admin only)                │
│  invoices → Factures                                        │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                  CLOUD FUNCTIONS                             │
├─────────────────────────────────────────────────────────────┤
│  handleStripeWebhook → Validate & process webhooks          │
│  createCheckoutSession → Create Stripe session              │
│  deleteUserData → Delete account & data                     │
│  exportUserData → Export data to JSON                       │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                    STRIPE API                                │
├─────────────────────────────────────────────────────────────┤
│  Customers → Store customer info                            │
│  Subscriptions → Manage subscriptions                       │
│  Invoices → Generate invoices                               │
│  Webhooks → Send events                                     │
└─────────────────────────────────────────────────────────────┘

🚀 Déploiement

Firebase Deployment

# Deploy Firestore Rules
firebase deploy --only firestore:rules

# Deploy Cloud Functions
firebase deploy --only functions

# Deploy everything
firebase deploy

Environment Variables

Note : ce bloc est un exemple “design cible”. Dans l'implémentation as-is basée sur l'extension invertase/firestore-stripe-payments, les secrets Stripe sont gérés via Secret Manager (ex : STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET) et ne sont pas attendus en clair dans le repo.

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
SENDGRID_API_KEY=SG...

📈 Monitoring & Logging

Firestore Logging

admin.firestore().collection('audit_logs').add({
  timestamp: admin.firestore.FieldValue.serverTimestamp(),
  user_id: userId,
  action: 'payment_success',
  result: 'success',
  details: {
    amount: 999,
    currency: 'EUR',
    subscription_id: 'sub_...'
  }
});

Cloud Functions Logging

console.log('Payment processed:', {
  userId: uid,
  amount: amount,
  timestamp: new Date()
});

Monitoring

  • Firebase Console : Voir les logs en temps réel
  • Stripe Dashboard : Voir les paiements
  • Firestore Console : Voir les données

🔄 Maintenance & Updates

Mises à Jour Régulières

  • Dépendances : Chaque mois
  • Sécurité : Immédiatement
  • Stripe API : Suivre les annonces
  • Firebase : Suivre les mises à jour

Backup & Recovery

  • Firestore : Backup automatique (Google)
  • Stripe : Données sauvegardées (Stripe)
  • Recovery : Plan de récupération défini

📞 Support & Troubleshooting

Problèmes Courants

Webhook non reçu : - Vérifier que Cloud Function est déployée - Vérifier que endpoint est accessible - Vérifier les logs Stripe

Paiement échoué : - Vérifier les logs Firestore - Vérifier les logs Stripe - Vérifier la configuration Stripe

Données manquantes : - Vérifier les Firestore Rules - Vérifier les audit logs - Vérifier les webhook logs

Document créé par Cascade - Architecture Stripe pour Yinshi