Plantilla de FastAPI - Dodo Payments Documentation

GitHub Repository

Completa el boilerplate de FastAPI + Dodo Payments

Descripción general

La plantilla de FastAPI proporciona un punto de partida listo para producción para integrar Dodo Payments con tu backend de Python. Esta plantilla incluye manejo de sesiones de pago, verificación de webhooks, integración de portal de clientes y patrones de API asíncronos para ayudarte a comenzar a aceptar pagos rápidamente.

Este boilerplate utiliza FastAPI con patrones async/await, Pydantic para la validación y el dodopayments SDK de Python para una integración fluida con la API.

Características

Configuración rápida - Comienza en menos de 5 minutos
Soporte asíncrono - Construido con los patrones nativos async/await de FastAPI
Sesiones de pago - Flujo de pago preconfigurado utilizando el SDK de Python
Manejo de webhooks - Punto final de webhook seguro con verificación de firma
Portal de clientes - Creación fácil de sesiones del portal de clientes
Seguridad de tipos - Validación completa de Pydantic y sugerencias de tipo
Configuración del entorno - Configuración de variables de entorno lista para usar

Requisitos previos

Antes de comenzar, asegúrate de tener:

Python 3.9+ (recomendado: Python 3.11+)
pip o uv para la gestión de paquetes
Cuenta de Dodo Payments (para acceder a las claves de API y Webhook desde el panel)

Inicio rápido

Clone the Repository

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

Create Virtual Environment

Configura un entorno de Python aislado:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

O usando uv para una gestión de dependencias más rápida:

uv venv
source .venv/bin/activate

Install Dependencies

pip install -r requirements.txt

O con uv:

uv pip install -r requirements.txt

Get API Credentials

Regístrate en Dodo Payments y obtén tus credenciales desde el panel:

Clave de API: Panel → Desarrollador → Claves de API
Clave de Webhook: Panel → Desarrollador → Webhooks

¡Asegúrate de estar en Modo de Prueba mientras desarrollas!

Configure Environment Variables

Crea un archivo .env en el directorio raíz:

cp .env.example .env

Actualiza los valores con tus credenciales de 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

Nunca subas tu archivo .env al control de versiones. Ya está incluido en .gitignore.

Run the Development Server

uvicorn main:app --reload

Abre http://localhost:8000/docs para ver la documentación interactiva de la API!

Deberías ver la interfaz Swagger UI de FastAPI con todos los endpoints disponibles listos para probar.

Estructura del Proyecto

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

Puntos finales de la API

La plantilla incluye los siguientes puntos finales preconfigurados:

Endpoint	Método	Descripción
`/checkout`	POST	Crear una nueva sesión de pago
`/webhook`	POST	Procesar webhooks de Dodo Payments
`/customer-portal`	POST	Generar URL del portal del cliente

Ejemplos de Código

Creando una Sesión de Pago

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

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

Integración del Portal de Clientes

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.customer_portal.create(
            customer_id=request.customer_id,
        )
        return {"portal_url": session.link}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

Eventos de Webhook

La plantilla demuestra el manejo de eventos comunes de webhook:

Evento	Descripción
`payment.succeeded`	Pago completado con éxito
`payment.failed`	Intento de pago fallido
`subscription.active`	La suscripción está activa ahora
`subscription.cancelled`	La suscripción fue cancelada
`refund.succeeded`	Reembolso procesado con éxito

Agrega tu lógica de negocio dentro del manejador de webhook para:

Actualizar permisos de usuario en tu base de datos
Enviar correos electrónicos de confirmación
Proveer acceso a productos digitales
Rastrear análisis y métricas

Pruebas de Webhooks Localmente

Para el desarrollo local, utiliza herramientas como ngrok para exponer tu servidor local:

ngrok http 8000

Actualiza la URL del webhook en tu Panel de Dodo Payments:

https://your-ngrok-url.ngrok.io/webhook

Despliegue

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

Construir y ejecutar:

docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

Consideraciones de Producción

Antes de desplegar en producción:

Cambia DODO_PAYMENTS_ENVIRONMENT a live_mode
Usa claves de API de producción del panel
Actualiza la URL del webhook a tu dominio de producción
Habilita HTTPS para todos los endpoints

Solución de Problemas

Import errors or missing modules

Asegúrate de que tu entorno virtual esté activado y que las dependencias estén instaladas:

source venv/bin/activate
pip install -r requirements.txt

Checkout session creation fails

Causas comunes:

ID de producto inválido: verifica que exista en tu panel de Dodo
Clave de API o configuración de entorno incorrecta en .env
Revisa los registros de FastAPI para obtener mensajes de error detallados

Webhooks not receiving events

Para pruebas locales, usa ngrok para exponer tu servidor:

ngrok http 8000

Actualiza la URL del webhook en tu panel de Dodo a la URL de ngrok. Asegúrate de actualizar tu archivo .env con la clave correcta de verificación del webhook.

Webhook signature verification fails

Asegúrate de que DODO_PAYMENTS_WEBHOOK_KEY esté configurado correctamente en tu .env
Verifica que estés usando el cuerpo de solicitud sin procesar para la verificación de la firma
Comprueba que estés leyendo correctamente el encabezado webhook-signature

Aprende Más

Python SDK

Documentación completa del SDK de Python con soporte async

Webhooks Documentation

Aprende sobre todos los eventos de webhook y las mejores prácticas

Checkout Sessions

Profundiza en la configuración de sesiones de pago

API Reference

Documentación completa de la API de Dodo Payments

Soporte

¿Necesitas ayuda con la plantilla?

Únete a nuestra comunidad de Discord para preguntas y discusiones
Revisa el repositorio de GitHub para problemas y actualizaciones
Contacta a nuestro equipo de soporte para asistencia

GitHub Repository

​Descripción general

​Características

​Requisitos previos

​Inicio rápido

​Estructura del Proyecto

​Puntos finales de la API

​Ejemplos de Código

​Creando una Sesión de Pago

​Manejo de Webhooks

​Integración del Portal de Clientes

​Eventos de Webhook

​Pruebas de Webhooks Localmente

​Despliegue

​Docker

​Consideraciones de Producción

​Solución de Problemas

​Aprende Más

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Soporte

Descripción general

Características

Requisitos previos

Inicio rápido

Estructura del Proyecto

Puntos finales de la API

Ejemplos de Código

Creando una Sesión de Pago

Manejo de Webhooks

Integración del Portal de Clientes

Eventos de Webhook

Pruebas de Webhooks Localmente

Despliegue

Docker

Consideraciones de Producción

Solución de Problemas

Aprende Más

Soporte