Skip to main content

GitHub Repository

Code source du boilerplate FastAPI et Dodo Payments.

Aperçu

Le boilerplate FastAPI est un backend Python auquel Dodo Payments est déjà connecté. Il comprend des endpoints qui créent des sessions de checkout et des sessions Customer Portal, un endpoint webhook qui vérifie les signatures, ainsi qu’une page de tarification rendue à partir de templates Jinja2.
Ce boilerplate utilise FastAPI avec des gestionnaires de routes async, Pydantic pour la validation et la configuration, ainsi que le SDK Python dodopayments. Les gestionnaires appellent le client synchrone DodoPayments. Pour éviter de bloquer la boucle d’événements, utilisez AsyncDodoPayments et rendez ses appels await.

Caractéristiques

Le boilerplate comprend :
  • Configuration rapide : passez du clonage à un serveur opérationnel en environ cinq minutes.
  • Gestionnaires asynchrones : les gestionnaires de routes sont des fonctions FastAPI async def.
  • Sessions de checkout : un endpoint de checkout préconfiguré qui utilise le SDK Python.
  • Gestion des webhooks : un endpoint webhook qui vérifie chaque signature avec la méthode unwrap du SDK.
  • Customer Portal : un endpoint qui crée des sessions Customer Portal.
  • Sécurité des types : les modèles Pydantic valident les corps des requêtes, et le code utilise des annotations de type.
  • Configuration de l’environnement : pydantic-settings charge et valide la configuration depuis .env.

Prérequis

Avant de commencer, vous avez besoin de :
  • Python 3.9 ou version ultérieure, requis par le SDK dodopayments. Python 3.11 ou version ultérieure est recommandé.
  • pip ou uv pour la gestion des paquets.
  • Un compte Dodo Payments, afin de créer une clé API et un secret de signature webhook dans le dashboard.

Démarrage rapide

1

Clone the Repository

2

Create Virtual Environment

Configurez un environnement Python isolé :
Vous pouvez aussi utiliser uv pour une gestion plus rapide des dépendances :
3

Install Dependencies

Ou avec uv :
4

Get API Credentials

Inscrivez-vous sur Dodo Payments, puis récupérez vos identifiants depuis le dashboard :
Créez les deux éléments lorsque le bouton Live Mode dans la barre latérale est désactivé. Une clé de mode test fonctionne uniquement avec DODO_PAYMENTS_ENVIRONMENT=test_mode, et les paiements en mode test ne transfèrent pas d’argent réel.
5

Configure Environment Variables

Copiez le fichier d’exemple pour créer un fichier .env dans le répertoire racine :
Définissez les valeurs correspondant à vos identifiants Dodo Payments :
.env
Les quatre variables sont obligatoires. app/core/config.py les charge avec pydantic-settings, et l’application refuse de démarrer si l’une d’elles est absente ou vide. DODO_PAYMENTS_RETURN_URL correspond à l’endroit où le checkout redirige le client après le paiement.
Ne commitez pas votre fichier .env dans le contrôle de version. Le fichier .gitignore du dépôt l’exclut déjà.
6

Add Your Products

Remplacez les produits d’exemple dans app/lib/products.py par les vôtres. Définissez chaque product_id sur l’ID d’un produit présent sous Products dans votre dashboard. La page de tarification affiche ces produits.
7

Run the Development Server

Ouvrez http://localhost:8000/docs pour consulter la documentation interactive de l’API.
Swagger UI répertorie les endpoints /api/checkout/, /api/webhook/ et /api/customer-portal/, prêts à être testés.
L’URL racine, http://localhost:8000, sert la page des tarifs.
app/main.py appelle templates.TemplateResponse("index.html", {"request": request, ...}), une signature que Starlette 1.x n’accepte plus. La page des tarifs renvoie donc une erreur 500 lors d’une nouvelle installation. Pour corriger ce problème, remplacez l’appel par templates.TemplateResponse(request, "index.html", {"products": products}).

Structure du projet

Points de terminaison de l’API

app/main.py monte chaque routeur sous un préfixe /api : Chaque chemin se termine par une barre oblique. FastAPI répond à une requête adressée au chemin sans barre oblique par une redirection 307. Utilisez donc le chemin exact, en particulier dans votre URL de webhook.

Exemples de code

Ces exemples sont condensés à partir des fichiers de app/api/.

Créer une session de paiement

app/api/checkout.py crée une session de paiement et renvoie son checkout_url. Le corps de la requête accepte un product_id, un quantity facultatif et un objet customer facultatif contenant name et email :

Gérer les webhooks

app/api/webhook.py vérifie la signature avec la méthode unwrap du SDK, puis effectue un branchement selon le type d’événement :

Intégration du Customer Portal

app/api/portal.py crée une session Customer Portal pour un ID client et renvoie le lien du portail sous la forme url :
La page des tarifs dans app/templates/index.html envoie un ID client codé en dur (cus_001) à ce point de terminaison, ainsi qu’un nom et une adresse e-mail codés en dur au point de terminaison de paiement. Remplacez-les par les valeurs de l’utilisateur connecté.

Événements de webhook

Le gestionnaire dans app/api/webhook.py effectue un branchement pour les événements suivants : Pour gérer un autre événement, ajoutez une branche pour son type, par exemple refund.succeeded pour un remboursement traité avec succès. Pour connaître tous les types d’événements, consultez le Guide des événements de webhook. Ajoutez votre logique métier dans le gestionnaire de webhook pour :
  • Mettre à jour les autorisations des utilisateurs dans votre base de données
  • Envoyer des e-mails de confirmation
  • Provisionner l’accès aux produits numériques
  • Suivre les analytics et les métriques

Tester les webhooks en local

Dodo Payments ne peut pas atteindre localhost. Pour le développement local, utilisez un outil tel que ngrok afin d’exposer votre serveur local :
Ajoutez l’URL HTTPS ngrok, suivie de /api/webhook/, comme point de terminaison dans votre tableau de bord Dodo Payments :
Copiez le secret de signature du point de terminaison dans DODO_PAYMENTS_WEBHOOK_KEY dans .env, puis redémarrez le serveur. L’application ne lit .env qu’au démarrage.

Déploiement

Docker

Le dépôt ne contient pas de Dockerfile. Pour exécuter l’application dans un conteneur, ajoutez ce Dockerfile à la racine du dépôt :
COPY . . copie chaque fichier du contexte de build, y compris .env. Pour ne pas inclure vos clés dans l’image, ajoutez un fichier .dockerignore qui répertorie .env. Créez ensuite l’image et exécutez-la avec votre fichier d’environnement :

Considérations relatives à la production

Avant de déployer en production :
  • Remplacez DODO_PAYMENTS_ENVIRONMENT par live_mode.
  • Utilisez une clé API du mode live depuis le tableau de bord.
  • Ajoutez un point de terminaison de webhook pour votre domaine de production et définissez DODO_PAYMENTS_WEBHOOK_KEY sur son secret de signature.
  • Définissez DODO_PAYMENTS_RETURN_URL sur votre URL de production.
  • Activez HTTPS pour tous les points de terminaison.

Résolution des problèmes

Assurez-vous que votre environnement virtuel est activé et que les dépendances sont installées :
app/main.py sert les fichiers statiques depuis app/static, mais le dépôt ne contient pas ce répertoire. Créez-le avec mkdir app/static, puis redémarrez le serveur.
Vérifiez les causes courantes suivantes :
  • L’ID du produit n’existe pas dans votre tableau de bord Dodo Payments.
  • La clé API ou DODO_PAYMENTS_ENVIRONMENT dans .env est incorrecte. Une clé du mode test fonctionne uniquement avec test_mode.
Le point de terminaison renvoie l’erreur du SDK dans une réponse 400. Consultez les journaux FastAPI pour obtenir des messages d’erreur détaillés.
Pour les tests locaux, utilisez ngrok afin d’exposer votre serveur :
Dans votre tableau de bord Dodo, ajoutez un point de terminaison avec l’URL ngrok suivie de /api/webhook/, barre oblique finale comprise. Copiez le secret de signature de ce point de terminaison dans DODO_PAYMENTS_WEBHOOK_KEY dans votre fichier .env.
  • Assurez-vous que DODO_PAYMENTS_WEBHOOK_KEY dans .env correspond au secret de signature du point de terminaison.
  • Vérifiez la signature par rapport au corps brut de la requête, avant de l’analyser en JSON.
  • Transmettez les trois en-têtes webhook-id, webhook-timestamp et webhook-signature à client.webhooks.unwrap(). La signature Standard Webhooks couvre id.timestamp.body, et non le corps seul.

En savoir plus

Python SDK

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

Webhooks Documentation

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

Checkout Sessions

Approfondissez la configuration des sessions de paiement

API Reference

Documentation complète de l’API Dodo Payments

Assistance

Pour obtenir de l’aide sur le boilerplate :
Dernière modification le 26 septembre 2026