> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modèle FastAPI

> Commencez rapidement avec notre modèle FastAPI pour intégrer Dodo Payments dans vos applications backend Python

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/fastapi-boilerplate">
  Boilerplate complet FastAPI + Dodo Payments
</Card>

## Aperçu

Le modèle FastAPI fournit un point de départ prêt pour la production pour intégrer Dodo Payments avec votre backend Python. Ce modèle inclut la gestion des sessions de paiement, la vérification des webhooks, l'intégration du portail client et des modèles d'API asynchrones pour vous aider à commencer à accepter des paiements rapidement.

<Info>
  Ce boilerplate utilise FastAPI avec les patterns async/await, Pydantic pour la validation, et le SDK Python `dodopayments` pour une intégration API fluide.
</Info>

### Caractéristiques

* **Configuration rapide** - Commencez en moins de 5 minutes
* **Support asynchrone** - Construit avec les modèles natifs async/await de FastAPI
* **Sessions de paiement** - Flux de paiement préconfiguré utilisant le SDK Python
* **Gestion des webhooks** - Point de terminaison webhook sécurisé avec vérification de signature
* **Portail client** - Création facile de sessions de portail client
* **Sécurité des types** - Validation complète Pydantic et indications de type
* **Configuration de l'environnement** - Configuration des variables d'environnement prête à l'emploi

## Prérequis

Avant de commencer, assurez-vous d'avoir :

* **Python 3.9+** (recommandé : Python 3.11+)
* **pip** ou **uv** pour la gestion des paquets
* **Compte Dodo Payments** (pour accéder aux clés API et Webhook depuis le tableau de bord)

## Démarrage rapide

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/fastapi-boilerplate.git
    cd fastapi-boilerplate
    ```
  </Step>

  <Step title="Create Virtual Environment">
    Configurez un environnement Python isolé :

    ```bash theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```

    Ou en utilisant uv pour une gestion des dépendances plus rapide :

    ```bash theme={null}
    uv venv
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```

    Ou avec uv :

    ```bash theme={null}
    uv pip install -r requirements.txt
    ```
  </Step>

  <Step title="Get API Credentials">
    Inscrivez-vous sur [Dodo Payments](https://dodopayments.com/) et récupérez vos identifiants depuis le tableau de bord :

    * **Clé API :** [Tableau de bord → Développeur → Clés API](https://app.dodopayments.com/developer/api-keys)
    * **Clé Webhook :** [Tableau de bord → Développeur → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Assurez-vous d'être en **mode test** pendant le développement !
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Créez un fichier `.env` à la racine :

    ```bash theme={null}
    cp .env.example .env
    ```

    Mettez à jour les valeurs avec vos identifiants Dodo Payments :

    ```bash .env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Ne validez jamais votre fichier `.env` dans le contrôle de version. Il est déjà inclus dans `.gitignore`.
    </Warning>
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    uvicorn main:app --reload
    ```

    Ouvrez [http://localhost:8000/docs](http://localhost:8000/docs) pour voir la documentation API interactive !

    <Check>
      Vous devriez voir l'interface Swagger UI de FastAPI avec tous les points de terminaison disponibles prêts à être testés.
    </Check>
  </Step>
</Steps>

## Structure du projet

```text theme={null}
fastapi-boilerplate/
├── main.py                 # FastAPI application entry point
├── routers/
│   ├── checkout.py         # Checkout session endpoints
│   ├── webhook.py          # Webhook handler endpoint
│   └── customer_portal.py  # Customer portal endpoints
├── config.py               # Environment configuration
├── requirements.txt        # Python dependencies
├── .env.example            # Environment template
└── README.md
```

## Points de terminaison API

Le modèle inclut les points de terminaison préconfigurés suivants :

| Endpoint           | Method | Description                            |
| ------------------ | ------ | -------------------------------------- |
| `/checkout`        | POST   | Créez une nouvelle session de paiement |
| `/webhook`         | POST   | Gérez les webhooks Dodo Payments       |
| `/customer-portal` | POST   | Générez l'URL du portail client        |

## Exemples de code

### Création d'une session de paiement

```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int = 1
    customer_email: str | None = None
    customer_name: str | None = None

@router.post("/checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            customer={
                "email": request.customer_email,
                "name": request.customer_name
            } if request.customer_email else None,
            return_url="http://localhost:8000/success"
        )
        return {"checkout_url": session.checkout_url, "session_id": session.session_id}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))
```

### Gestion des webhooks

```python theme={null}
from fastapi import APIRouter, Request, HTTPException
import hmac
import hashlib
from config import settings

router = APIRouter()

def verify_webhook_signature(payload: bytes, signature: str) -> bool:
    expected = hmac.new(
        settings.DODO_PAYMENTS_WEBHOOK_KEY.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@router.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("webhook-signature", "")
    
    if not verify_webhook_signature(payload, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")
    
    event = await request.json()
    event_type = event.get("type")
    
    match event_type:
        case "payment.succeeded":
            # Handle successful payment
            payment_id = event["data"]["payment_id"]
            print(f"Payment succeeded: {payment_id}")
            
        case "subscription.active":
            # Handle subscription activation
            subscription_id = event["data"]["subscription_id"]
            print(f"Subscription activated: {subscription_id}")
            
        case "refund.succeeded":
            # Handle refund
            refund_id = event["data"]["refund_id"]
            print(f"Refund processed: {refund_id}")
    
    return {"status": "received"}
```

### Intégration du portail client

```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class PortalRequest(BaseModel):
    customer_id: str

@router.post("/customer-portal")
async def create_portal_session(request: PortalRequest):
    try:
        session = await dodo.customers.customer_portal.create(
            customer_id=request.customer_id,
        )
        return {"portal_url": session.link}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))
```

## Événements de webhook

Le modèle démontre la gestion des événements de webhook courants :

| Event                    | Description                       |
| ------------------------ | --------------------------------- |
| `payment.succeeded`      | Paiement effectué avec succès     |
| `payment.failed`         | La tentative de paiement a échoué |
| `subscription.active`    | L'abonnement est maintenant actif |
| `subscription.cancelled` | L'abonnement a été annulé         |
| `refund.succeeded`       | Remboursement traité avec succès  |

Ajoutez votre logique métier à l'intérieur du gestionnaire de webhook pour :

* Mettre à jour les autorisations des utilisateurs dans votre base de données
* Envoyer des e-mails de confirmation
* Fournir l'accès à des produits numériques
* Suivre les analyses et les métriques

## Tester les webhooks localement

Pour le développement local, utilisez des outils comme [ngrok](https://ngrok.com/) pour exposer votre serveur local :

```bash theme={null}
ngrok http 8000
```

Mettez à jour l'URL du webhook dans votre [tableau de bord Dodo Payments](https://app.dodopayments.com/developer/webhooks) :

```
https://your-ngrok-url.ngrok.io/webhook
```

## Déploiement

### Docker

```dockerfile theme={null}
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

Construire et exécuter :

```bash theme={null}
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo
```

### Considérations de production

<Warning>
  Avant de déployer en production :

  * Passez `DODO_PAYMENTS_ENVIRONMENT` à `live_mode`
  * Utilisez les clés API de production depuis le tableau de bord
  * Mettez à jour l'URL du webhook avec votre domaine de production
  * Activez HTTPS pour tous les points de terminaison
</Warning>

## Dépannage

<AccordionGroup>
  <Accordion title="Import errors or missing modules">
    Assurez-vous que votre environnement virtuel est activé et que les dépendances sont installées :

    ```bash theme={null}
    source venv/bin/activate
    pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="Checkout session creation fails">
    **Causes courantes :**

    * ID produit invalide — vérifiez qu'il existe dans votre tableau de bord Dodo
    * Mauvaise clé API ou mauvais paramètre d'environnement dans `.env`
    * Consultez les journaux FastAPI pour des messages d'erreur détaillés
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Pour les tests locaux, utilisez [ngrok](https://ngrok.com) pour exposer votre serveur :

    ```bash theme={null}
    ngrok http 8000
    ```

    Mettez à jour l'URL du webhook dans votre [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) avec l'URL ngrok. Assurez-vous de mettre à jour votre fichier `.env` avec la clé de vérification du webhook correcte.
  </Accordion>

  <Accordion title="Webhook signature verification fails">
    * Assurez-vous que `DODO_PAYMENTS_WEBHOOK_KEY` est correctement défini dans votre `.env`
    * Vérifiez que vous utilisez le corps brut de la requête pour la vérification de la signature
    * Vérifiez que vous lisez correctement l'en-tête `webhook-signature`
  </Accordion>
</AccordionGroup>

## En savoir plus

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/developer-resources/sdks/python">
    Documentation complète du SDK Python avec prise en charge async
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Découvrez tous les événements webhook et les bonnes pratiques
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Approfondissement de la configuration des sessions de paiement
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Documentation complète de l'API Dodo Payments
  </Card>
</CardGroup>

## Support

Besoin d'aide avec le modèle ?

* Rejoignez notre [communauté Discord](https://discord.gg/bYqAp4ayYh) pour des questions et des discussions
* Consultez le [dépôt GitHub](https://github.com/dodopayments/fastapi-boilerplate) pour les problèmes et les mises à jour
* Contactez notre [équipe de support](mailto:support@dodopayments.com) pour obtenir de l'aide