Pular para o conteúdo principal

Repositório do GitHub

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 usa FastAPI com padrões async/await, Pydantic para validação e o dodopayments SDK Python para integração de API sem problemas.

​
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 o Repositório

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

Criar Ambiente Virtual

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

Instalar Dependências

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

Obter Credenciais da API

Inscreva-se em Dodo Payments e obtenha suas credenciais no painel:
Certifique-se de que você está em Modo de Teste enquanto desenvolve!
5

Configurar Variáveis de Ambiente

Crie um .env arquivo 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 .env arquivo no controle de versão. Ele já está incluído em .gitignore.
6

Executar o Servidor de Desenvolvimento

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

​
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
/webhookPOSTManipular 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:
  • Mude DODO_PAYMENTS_ENVIRONMENT para live_mode
  • Use chaves da API de produção do painel
  • Atualize a URL do webhook para seu domínio de produção
  • Habilite HTTPS para todos os endpoints

​
Solução de Problemas

Certifique-se de que seu ambiente virtual está ativado e as dependências estão instaladas:
source venv/bin/activate
pip install -r requirements.txt
Causas comuns:
  • ID do produto inválido - verifique se ele existe no seu painel Dodo
  • Chave da API errada ou configuração de ambiente 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 em seu painel Dodo para a URL do ngrok. Certifique-se de atualizar seu .env arquivo com a chave de verificação de webhook correta.
  • Certifique-se de que DODO_PAYMENTS_WEBHOOK_KEY está corretamente definido em seu .env
  • Verifique se você está usando o corpo da solicitação bruta para verificação de assinatura
  • Verifique se você está lendo o cabeçalho webhook-signature corretamente

​
Saiba Mais

SDK Python

Documentação completa do SDK Python com suporte assíncrono

Documentação de Webhooks

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

Sessões de Checkout

Aprofunde-se na configuração da sessão de checkout

Referência da API

Documentação completa da API Dodo Payments

​
Suporte

Precisa de ajuda com o boilerplate?