Vai al contenuto principale

GitHub Repository

Completa boilerplate FastAPI + Dodo Payments

​
Panoramica

Il boilerplate FastAPI fornisce un punto di partenza pronto per la produzione per integrare Dodo Payments con il tuo backend Python. Questo template include la gestione delle sessioni di checkout, la verifica dei webhook, l’integrazione del portale clienti e modelli API async per aiutarti ad accettare pagamenti rapidamente.
Questo boilerplate utilizza FastAPI con pattern async/await, Pydantic per la validazione e l’SDK Python dodopayments per un’integrazione API senza interruzioni.

​
Caratteristiche

  • Impostazione rapida - Inizia in meno di 5 minuti
  • Supporto Async - Costruito con i modelli nativi async/await di FastAPI
  • Sessioni di Checkout - Flusso di checkout preconfigurato utilizzando l’SDK Python
  • Gestione dei Webhook - Endpoint webhook sicuro con verifica della firma
  • Portale Clienti - Creazione facile delle sessioni del portale clienti
  • Sicurezza dei Tipi - Validazione completa di Pydantic e suggerimenti sui tipi
  • Configurazione dell’Ambiente - Impostazione delle variabili d’ambiente pronta all’uso

​
Requisiti

Prima di iniziare, assicurati di avere:
  • Python 3.9+ (consigliato: Python 3.11+)
  • pip o uv per la gestione dei pacchetti
  • Account Dodo Payments (per accedere alle chiavi API e Webhook dal dashboard)

​
Avvio Rapido

1

Clone the Repository

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

Create Virtual Environment

Configura un ambiente Python isolato:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
Oppure usa uv per una gestione delle dipendenze più veloce:
uv venv
source .venv/bin/activate
3

Install Dependencies

pip install -r requirements.txt
Oppure con uv:
uv pip install -r requirements.txt
4

Get API Credentials

Iscriviti a Dodo Payments e ottieni le tue credenziali dal pannello di controllo:
Assicurati di essere in Modalità Test durante lo sviluppo!
5

Configure Environment Variables

Crea un file .env nella directory principale:
cp .env.example .env
Aggiorna i valori con le tue credenziali 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
Non inserire mai il tuo file .env nel controllo del codice. È già incluso in .gitignore.
6

Run the Development Server

uvicorn main:app --reload
Apri http://localhost:8000/docs per vedere la documentazione API interattiva!
Dovresti vedere l’interfaccia Swagger di FastAPI con tutti gli endpoint disponibili pronti per essere testati.

​
Struttura del Progetto

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

​
Endpoint API

Il boilerplate include i seguenti endpoint preconfigurati:
EndpointMetodoDescrizione
/checkoutPOSTCrea una nuova sessione di checkout
/webhookPOSTGestisce i webhook di Dodo Payments
/customer-portalPOSTGenera URL per il portale clienti

​
Esempi di Codice

​
Creazione di una Sessione di Checkout

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

​
Gestione dei Webhook

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"}

​
Integrazione del Portale Clienti

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

​
Eventi Webhook

Il boilerplate dimostra la gestione di eventi webhook comuni:
EventoDescrizione
payment.succeededPagamento completato con successo
payment.failedTentativo di pagamento fallito
subscription.activeL’abbonamento è ora attivo
subscription.cancelledL’abbonamento è stato annullato
refund.succeededRimborso elaborato con successo
Aggiungi la tua logica aziendale all’interno del gestore webhook per:
  • Aggiornare i permessi degli utenti nel tuo database
  • Inviare email di conferma
  • Fornire accesso a prodotti digitali
  • Monitorare analisi e metriche

​
Testare i Webhook Localmente

Per lo sviluppo locale, utilizza strumenti come ngrok per esporre il tuo server locale: 
ngrok http 8000
Aggiorna l’URL del webhook nel tuo Dashboard Dodo Payments: 
https://your-ngrok-url.ngrok.io/webhook

​
Distribuzione

​
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"]
Costruisci ed esegui: 
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

​
Considerazioni per la Produzione

Prima di distribuire in produzione:
  • Passa da DODO_PAYMENTS_ENVIRONMENT a live_mode
  • Usa chiavi API di produzione dal dashboard
  • Aggiorna l’URL del webhook al tuo dominio di produzione
  • Abilita HTTPS per tutti gli endpoint

​
Risoluzione dei Problemi

Assicurati che il tuo ambiente virtuale sia attivato e che le dipendenze siano installate:
source venv/bin/activate
pip install -r requirements.txt
Cause comuni:
  • ID prodotto non valido - verifica che esista nel tuo pannello Dodo
  • Chiave API o impostazione ambiente errate in .env
  • Controlla i log di FastAPI per messaggi di errore dettagliati
Per i test locali, usa ngrok per esporre il tuo server:
ngrok http 8000
Aggiorna l’URL del webhook nel tuo pannello Dodo con l’URL di ngrok. Assicurati di aggiornare il tuo file .env con la chiave di verifica webhook corretta.
  • Assicurati che DODO_PAYMENTS_WEBHOOK_KEY sia impostato correttamente nel tuo .env
  • Verifica di utilizzare il corpo della richiesta grezzo per la verifica della firma
  • Controlla di leggere correttamente l’intestazione webhook-signature

​
Scopri di più

Python SDK

Documentazione completa dell’SDK Python con supporto async

Webhooks Documentation

Scopri tutti gli eventi webhook e le best practice

Checkout Sessions

Approfondimento sulla configurazione della sessione di checkout

API Reference

Documentazione completa delle API Dodo Payments

​
Supporto

Hai bisogno di aiuto con il boilerplate?