Modèle FastAPI

GitHub Repository

Boilerplate 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 boilerplate utilise FastAPI avec les patterns async/await, Pydantic pour la validation, et le SDK Python dodopayments 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

Clone the Repository

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

Create Virtual Environment

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

Install Dependencies

pip install -r requirements.txt

Ou avec uv :

uv pip install -r requirements.txt

Get API Credentials

Inscrivez-vous sur Dodo Payments et récupérez vos identifiants depuis le tableau de bord :

Clé API : Tableau de bord → Développeur → Clés API
Clé Webhook : Tableau de bord → Développeur → Webhooks

Assurez-vous d’être en mode test pendant le développement !

Configure Environment Variables

Créez un fichier .env à la 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 validez jamais votre fichier .env dans le contrôle de version. Il est déjà inclus dans .gitignore.

Run the Development Server

uvicorn main:app --reload

Ouvrez http://localhost:8000/docs pour voir la documentation API interactive !

Vous devriez voir l’interface Swagger UI 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 :

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

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 :

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 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 :

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

Dépannage

Import errors or missing modules

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

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

Webhooks not receiving events

Pour les tests locaux, utilisez ngrok pour exposer votre serveur :

ngrok http 8000

Mettez à jour l’URL du webhook dans votre Dodo dashboard avec l’URL ngrok. Assurez-vous de mettre à jour votre fichier .env avec la clé de vérification du webhook correcte.

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

En savoir plus

Python SDK

Documentation complète du SDK Python avec prise en charge async

Webhooks Documentation

Découvrez tous les événements webhook et les bonnes pratiques

Checkout Sessions

Approfondissement de la configuration des sessions de paiement

API Reference

Documentation complète de l’API Dodo Payments

Support

Besoin d’aide avec le modèle ?

Rejoignez notre communauté Discord pour des questions et des discussions
Consultez le dépôt GitHub pour les problèmes et les mises à jour
Contactez notre équipe de support pour obtenir de l’aide

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Aperçu

Caractéristiques

Prérequis

Démarrage rapide

Structure du projet

Points de terminaison API

Exemples de code

Création d’une session de paiement

Gestion des webhooks

Intégration du portail client

Événements de webhook

Tester les webhooks localement

Déploiement

Docker

Considérations de production

Dépannage

En savoir plus

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

Support

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

​Aperçu

​Caractéristiques

​Prérequis

​Démarrage rapide

​Structure du projet

​Points de terminaison API

​Exemples de code

​Création d’une session de paiement

​Gestion des webhooks

​Intégration du portail client

​Événements de webhook

​Tester les webhooks localement

​Déploiement

​Docker

​Considérations de production

​Dépannage

​En savoir plus

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Support

Aperçu

Caractéristiques

Prérequis

Démarrage rapide

Structure du projet

Points de terminaison API

Exemples de code

Création d’une session de paiement

Gestion des webhooks

Intégration du portail client

Événements de webhook

Tester les webhooks localement

Déploiement

Docker

Considérations de production

Dépannage

En savoir plus

Support