Pular para o conteúdo principal

GitHub Repository

Boilerplate completo FastAPI + Dodo Payments

​
Visão Geral

O boilerplate FastAPI fornece um ponto de partida pronto para produção para integrar Dodo Payments com seu backend Python. Este template inclui gerenciamento de sessão de checkout, verificação de webhook, integração de portal do cliente e padrões de API assíncronos para ajudá-lo a começar a aceitar pagamentos rapidamente.
Este boilerplate utiliza FastAPI com padrões async/await, Pydantic para validação e o SDK Python dodopayments para integração perfeita com a API.

​
Recursos

  • Configuração Rápida - Comece em menos de 5 minutos
  • Suporte Assíncrono - Construído com os padrões nativos async/await do FastAPI
  • Sessões de Checkout - Fluxo de checkout pré-configurado usando o SDK Python
  • Gerenciamento de Webhook - Endpoint de webhook seguro com verificação de assinatura
  • Portal do Cliente - Criação fácil de sessão do portal do cliente
  • Segurança de Tipo - Validação completa do Pydantic e dicas de tipo
  • Configuração de Ambiente - Configuração de variáveis de ambiente pronta para uso

​
Pré-requisitos

Antes de começar, certifique-se de que você tem:
  • Python 3.9+ (recomendado: Python 3.11+)
  • pip ou uv para gerenciamento de pacotes
  • Conta Dodo Payments (para acessar as chaves da API e Webhook no painel)

​
Início Rápido

1

Clone the Repository

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

Create Virtual Environment

Configure um ambiente Python isolado:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
Ou usando uv para gerenciamento de dependências mais rápido:
uv venv
source .venv/bin/activate
3

Install Dependencies

pip install -r requirements.txt
Ou com uv:
uv pip install -r requirements.txt
4

Get API Credentials

Cadastre-se em Dodo Payments e obtenha suas credenciais no painel:
Certifique-se de estar no Modo de Teste enquanto desenvolve!
5

Configure Environment Variables

Crie um arquivo .env no diretório raiz:
cp .env.example .env
Atualize os valores com suas credenciais do 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 comite seu arquivo .env no controle de versão. Ele já está incluído em .gitignore.
6

Run the Development Server

uvicorn main:app --reload
Abra http://localhost:8000/docs para ver a documentação interativa da API!
Você deve ver a interface Swagger UI do FastAPI com todos os endpoints disponíveis prontos para testar.

​
Estrutura do Projeto

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

​
Endpoints da API

O boilerplate inclui os seguintes endpoints pré-configurados:
EndpointMétodoDescrição
/checkoutPOSTCriar uma nova sessão de checkout
/webhookPOSTLidar com webhooks do Dodo Payments
/customer-portalPOSTGerar URL do portal do cliente

​
Exemplos de Código

​
Criando uma Sessão de 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))

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

​
Integração do Portal do Cliente

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

​
Eventos de Webhook

O boilerplate demonstra o manuseio de eventos comuns de webhook:
EventoDescrição
payment.succeededPagamento concluído com sucesso
payment.failedTentativa de pagamento falhou
subscription.activeAssinatura agora está ativa
subscription.cancelledAssinatura foi cancelada
refund.succeededReembolso processado com sucesso
Adicione sua lógica de negócios dentro do manipulador de webhook para:
  • Atualizar permissões de usuário em seu banco de dados
  • Enviar e-mails de confirmação
  • Prover acesso a produtos digitais
  • Rastrear análises e métricas

​
Testando Webhooks Localmente

Para desenvolvimento local, use ferramentas como ngrok para expor seu servidor local: 
ngrok http 8000
Atualize a URL do webhook em seu Painel do Dodo Payments: 
https://your-ngrok-url.ngrok.io/webhook

​
Implantação

​
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"]
Construa e execute: 
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

​
Considerações de Produção

Antes de implantar em produção:
  • Altere DODO_PAYMENTS_ENVIRONMENT para live_mode
  • Use chaves de API de produção do painel
  • Atualize a URL do webhook para o seu domínio de produção
  • Ative HTTPS para todos os endpoints

​
Solução de Problemas

Certifique-se de que seu ambiente virtual esteja ativado e as dependências instaladas:
source venv/bin/activate
pip install -r requirements.txt
Causas comuns:
  • ID do produto inválido – verifique se existe no seu painel da Dodo
  • Chave de API ou configuração de ambiente incorreta em .env
  • Verifique os logs do FastAPI para mensagens de erro detalhadas
Para testes locais, use ngrok para expor seu servidor:
ngrok http 8000
Atualize a URL do webhook no seu painel da Dodo para a URL do ngrok. Certifique-se de atualizar seu arquivo .env com a chave de verificação correta do webhook.
  • Garanta que DODO_PAYMENTS_WEBHOOK_KEY esteja configurado corretamente em seu .env
  • Verifique se você está usando o corpo bruto da requisição para verificação de assinatura
  • Confira se você está lendo corretamente o cabeçalho webhook-signature

​
Saiba Mais

Python SDK

Documentação completa do SDK Python com suporte async

Webhooks Documentation

Saiba sobre todos os eventos de webhook e melhores práticas

Checkout Sessions

Mergulhe na configuração da sessão de checkout

API Reference

Documentação completa da API da Dodo Payments

​
Suporte

Precisa de ajuda com o boilerplate?