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
unwrapdu 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-settingscharge 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
4
Get API Credentials
Inscrivez-vous sur Dodo Payments, puis récupérez vos identifiants depuis le dashboard :
- Clé API : créez une clé dans Dashboard → Developer → API Keys.
- Clé webhook : ajoutez un endpoint dans Dashboard → Developer → Webhooks, puis copiez son secret de signature. L’URL de l’endpoint doit être publique et utiliser HTTPS. Pour recevoir des événements sur votre machine, consultez Tester les webhooks en local.
5
Configure Environment Variables
Copiez le fichier d’exemple pour créer un fichier Définissez les valeurs correspondant à vos identifiants Dodo Payments :Les quatre variables sont obligatoires.
.env dans le répertoire racine :.env
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.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
Swagger UI répertorie les endpoints
/api/checkout/, /api/webhook/ et /api/customer-portal/, prêts à être testés.http://localhost:8000, sert la page des tarifs.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 deapp/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 :
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 dansapp/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 atteindrelocalhost. Pour le développement local, utilisez un outil tel que ngrok afin d’exposer votre serveur local :
/api/webhook/, comme point de terminaison dans votre tableau de bord Dodo Payments :
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 deDockerfile. 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
Résolution des problèmes
Import errors or missing modules
Import errors or missing modules
Assurez-vous que votre environnement virtuel est activé et que les dépendances sont installées :
Server fails to start with Directory 'app/static' does not exist
Server fails to start with Directory 'app/static' does not exist
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.Checkout session creation fails
Checkout session creation fails
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_ENVIRONMENTdans.envest incorrecte. Une clé du mode test fonctionne uniquement avectest_mode.
400. Consultez les journaux FastAPI pour obtenir des messages d’erreur détaillés.Webhooks not receiving events
Webhooks not receiving events
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.Webhook signature verification fails
Webhook signature verification fails
- Assurez-vous que
DODO_PAYMENTS_WEBHOOK_KEYdans.envcorrespond 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-timestampetwebhook-signatureàclient.webhooks.unwrap(). La signature Standard Webhooks couvreid.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 :- Posez vos questions dans la communauté Discord.
- Signalez les problèmes et suivez les mises à jour dans le dépôt GitHub.
- Contactez l’équipe d’assistance par e-mail.