# 💳 Module de Paiement Stripe - Web Sentinel

Ce module gère l'intégration complète avec Stripe pour les abonnements Web Sentinel.

## 📁 Structure

```
web_sentinel/payment/
├── __init__.py           # Module d'initialisation
├── config.py             # Configuration des plans et clés API
├── stripe_service.py     # Service de gestion Stripe
└── api_routes.py         # Endpoints API Flask
```

## 🎯 Fonctionnalités

### ✅ Implémenté

- ✅ Création de sessions Checkout
- ✅ Portail client pour gestion d'abonnement
- ✅ Récupération des détails de session
- ✅ Récupération des détails d'abonnement
- ✅ Annulation d'abonnement
- ✅ Réception et validation des webhooks
- ✅ Support des paiements mensuels et annuels
- ✅ Support des plans PRO et ENTERPRISE

### 🚧 À implémenter

- 🔲 Génération automatique des licences
- 🔲 Envoi d'emails de confirmation
- 🔲 Stockage en base de données
- 🔲 Intégration avec le système de licences existant
- 🔲 Gestion des échecs de paiement
- 🔲 Métriques et analytics

## 🔧 Configuration

### Variables d'environnement requises

```env
STRIPE_SECRET_KEY=sk_test_...        # Clé secrète Stripe
STRIPE_PUBLISHABLE_KEY=pk_test_...   # Clé publique Stripe
STRIPE_WEBHOOK_SECRET=whsec_...      # Secret webhook
BASE_URL=http://localhost:8000       # URL de base de l'app
```

### Plans configurés

| Plan | Mensuel | Annuel | SAST Limit |
|------|---------|--------|------------|
| PRO | 9.99€ | 99€ | 100 fichiers/mois |
| ENTERPRISE | 49€ | 490€ | 500 fichiers/mois |

## 📡 API Endpoints

### GET `/api/v1/payment/config`

Retourne la configuration publique de Stripe.

**Response:**
```json
{
  "success": true,
  "data": {
    "publishable_key": "pk_test_...",
    "configured": true,
    "plans": {
      "pro": {
        "name": "PRO",
        "tier": "pro",
        "features": [...],
        "sast_limit": 100
      }
    }
  }
}
```

### POST `/api/v1/payment/create-checkout-session`

Crée une nouvelle session Checkout.

**Request:**
```json
{
  "lookup_key": "web_sentinel_pro_monthly",
  "customer_email": "user@example.com",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {
    "user_id": "123"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "session_id": "cs_test_...",
    "url": "https://checkout.stripe.com/...",
    "customer_email": "user@example.com",
    "plan": "pro"
  }
}
```

### POST `/api/v1/payment/create-portal-session`

Crée une session de portail client.

**Request:**
```json
{
  "customer_id": "cus_...",
  "return_url": "https://example.com/account"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "url": "https://billing.stripe.com/..."
  }
}
```

### GET `/api/v1/payment/session/<session_id>`

Récupère les détails d'une session Checkout.

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "cs_test_...",
    "customer_id": "cus_...",
    "customer_email": "user@example.com",
    "subscription_id": "sub_...",
    "payment_status": "paid",
    "status": "complete"
  }
}
```

### GET `/api/v1/payment/subscription/<subscription_id>`

Récupère les détails d'un abonnement.

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "sub_...",
    "customer_id": "cus_...",
    "status": "active",
    "current_period_start": "2025-10-24T...",
    "current_period_end": "2025-11-24T...",
    "cancel_at_period_end": false
  }
}
```

### POST `/api/v1/payment/subscription/<subscription_id>/cancel`

Annule un abonnement.

**Request:**
```json
{
  "at_period_end": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "sub_...",
    "status": "active",
    "cancel_at_period_end": true
  }
}
```

### POST `/api/v1/payment/webhook`

Reçoit les webhooks Stripe.

**Événements gérés:**
- `checkout.session.completed` - Nouveau paiement
- `customer.subscription.updated` - Abonnement mis à jour
- `customer.subscription.deleted` - Abonnement annulé
- `invoice.payment_succeeded` - Renouvellement réussi
- `invoice.payment_failed` - Échec de paiement

## 🔌 Utilisation

### Dans votre application Flask

```python
from flask import Flask
from web_sentinel.payment.api_routes import payment_bp

app = Flask(__name__)
app.register_blueprint(payment_bp)
```

### Créer une session de paiement

```python
from web_sentinel.payment import StripeService

service = StripeService()
session = service.create_checkout_session(
    lookup_key='web_sentinel_pro_monthly',
    customer_email='user@example.com',
    success_url='https://example.com/success',
    cancel_url='https://example.com/cancel'
)

# Rediriger l'utilisateur vers session['url']
```

### Gérer un webhook

```python
from web_sentinel.payment import StripeService

service = StripeService()

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.data
    sig_header = request.headers.get('Stripe-Signature')
    
    try:
        event = service.verify_webhook_signature(payload, sig_header)
        
        if event['type'] == 'checkout.session.completed':
            session = event['data']['object']
            # Créer la licence
            # Envoyer l'email
            # ...
            
        return jsonify({'success': True}), 200
    except Exception as e:
        return jsonify({'error': str(e)}), 400
```

## 🧪 Tests

### Tester avec le script fourni

```powershell
python scripts/test_stripe_integration.py
```

### Tester avec curl

```powershell
# Configuration
curl http://localhost:5000/api/v1/payment/config

# Créer une session
curl -X POST http://localhost:5000/api/v1/payment/create-checkout-session \
  -H "Content-Type: application/json" \
  -d '{"lookup_key":"web_sentinel_pro_monthly","customer_email":"test@example.com"}'
```

### Cartes de test Stripe

| Carte | Résultat |
|-------|----------|
| 4242 4242 4242 4242 | Succès |
| 4000 0000 0000 0002 | Échec (carte déclinée) |
| 4000 0027 6000 3184 | Requiert 3D Secure |

## 🔐 Sécurité

### Validation des webhooks

Tous les webhooks sont automatiquement validés avec la signature Stripe :

```python
event = stripe.Webhook.construct_event(
    payload, sig_header, STRIPE_WEBHOOK_SECRET
)
```

### Clés API

- Ne **jamais** commiter les clés dans Git
- Utiliser des clés **test** en développement
- Utiliser des clés **live** en production uniquement
- Définir les clés dans les variables d'environnement

## 📊 Monitoring

### Logs

Tous les événements importants sont loggés :

```python
logger.info(f"Session Checkout créée: {session.id}")
logger.error(f"Erreur Stripe: {e}")
```

### Dashboard Stripe

Surveillez dans le Dashboard Stripe :
- **Developers** → **Events** : Tous les événements
- **Developers** → **Webhooks** : État des webhooks
- **Payments** : Liste des paiements
- **Subscriptions** : Liste des abonnements

## 🚀 Déploiement

### Configuration en production

1. Passer aux clés **live**
2. Configurer HTTPS (obligatoire pour webhooks)
3. Créer l'endpoint webhook dans le Dashboard
4. Tester les webhooks en production
5. Activer le monitoring

### Variables d'environnement production

```env
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
BASE_URL=https://web-sentinel.taaazzz-prog.fr
```

## 📚 Ressources

- [Documentation Stripe](https://stripe.com/docs)
- [API Reference](https://stripe.com/docs/api)
- [Webhooks Guide](https://stripe.com/docs/webhooks)
- [Testing Guide](https://stripe.com/docs/testing)

## 🆘 Support

En cas de problème :
1. Vérifiez les logs : `web_sentinel.log`
2. Consultez le Dashboard Stripe : **Developers** → **Events**
3. Testez avec Stripe CLI : `stripe listen`
4. Consultez la documentation : `docs/stripe/STRIPE_SETUP_GUIDE.md`

---

**Développé avec ❤️ pour Web Sentinel**