Passer au contenu principal

Dépôt GitHub

Modèle complet FastAPI + Dodo Payments

​
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.
Ce modèle utilise FastAPI avec des modèles async/await, Pydantic pour la validation, et le dodopayments SDK Python pour une intégration API fluide.

​
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

1

Cloner le dépôt

git clone https://github.com/dodopayments/fastapi-boilerplate.git
cd fastapi-boilerplate
2

Créer un environnement virtuel

Configurez un environnement Python isolé :
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 :
uv venv
source .venv/bin/activate
3

Installer les dépendances

pip install -r requirements.txt
Ou avec uv :
uv pip install -r requirements.txt
4

Obtenir les identifiants API

Inscrivez-vous sur Dodo Payments et obtenez vos identifiants depuis le tableau de bord :
Assurez-vous d’être en mode test pendant le développement !
5

Configurer les variables d'environnement

Créez un .env fichier dans le répertoire racine :
cp .env.example .env
Mettez à jour les valeurs avec vos identifiants Dodo Payments :
.env
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
Ne jamais commettre votre .env fichier dans le contrôle de version. Il est déjà inclus dans .gitignore.
6

Exécuter le serveur de développement

uvicorn main:app --reload
Ouvrez http://localhost:8000/docs pour voir la documentation API interactive !
Vous devriez voir l’interface Swagger de FastAPI avec tous les points de terminaison disponibles prêts à être testés.

​
Structure du projet

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 :
Point de terminaisonMéthodeDescription
/checkoutPOSTCréer une nouvelle session de paiement
/webhookPOSTGérer les webhooks Dodo Payments
/customer-portalPOSTGénérer l’URL du portail client

​
Exemples de code

​
Création d’une session de paiement

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.url, "session_id": session.session_id}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

​
Gestion des webhooks

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

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.create_customer_portal(
            customer_id=request.customer_id
        )
        return {"portal_url": session.url}
    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 :
ÉvénementDescription
payment.succeededPaiement complété avec succès
payment.failedÉchec de la tentative de paiement
subscription.activeL’abonnement est maintenant actif
subscription.cancelledL’abonnement a été annulé
refund.succeededRemboursement 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 pour exposer votre serveur local : 
ngrok http 8000
Mettez à jour l’URL du webhook dans votre tableau de bord Dodo Payments : 
https://your-ngrok-url.ngrok.io/webhook

​
Déploiement

​
Docker

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 : 
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

​
Considérations de production

Avant de déployer en production :
  • Changez DODO_PAYMENTS_ENVIRONMENT en live_mode
  • Utilisez les clés API de production depuis le tableau de bord
  • Mettez à jour l’URL du webhook vers votre domaine de production
  • Activez HTTPS pour tous les points de terminaison

​
Dépannage

Assurez-vous que votre environnement virtuel est activé et que les dépendances sont installées :
source venv/bin/activate
pip install -r requirements.txt
Causes courantes :
  • ID de produit invalide - vérifiez qu’il existe dans votre tableau de bord Dodo
  • Mauvaise clé API ou paramètre d’environnement dans .env
  • Vérifiez les journaux FastAPI pour des messages d’erreur détaillés
Pour les tests locaux, utilisez ngrok pour exposer votre serveur :
ngrok http 8000
Mettez à jour l’URL du webhook dans votre tableau de bord Dodo vers l’URL ngrok. Assurez-vous de mettre à jour votre .env fichier avec la clé de vérification de webhook correcte.
  • Assurez-vous que DODO_PAYMENTS_WEBHOOK_KEY est correctement défini dans votre .env
  • Vérifiez que vous utilisez le corps de la requête brut pour la vérification de la signature
  • Vérifiez que vous lisez correctement l’en-tête webhook-signature

​
En savoir plus

SDK Python

Documentation complète du SDK Python avec support asynchrone

Documentation des Webhooks

Découvrez tous les événements de webhook et les meilleures pratiques

Sessions de paiement

Plongée approfondie dans la configuration des sessions de paiement

Référence API

Documentation complète de l’API Dodo Payments

​
Support

Besoin d’aide avec le modèle ?