FastAPI Boilerplate

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

Clone the Repository

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

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

Install Dependencies

pip install -r requirements.txt

Ou com uv:

uv pip install -r requirements.txt

Get API Credentials

Cadastre-se em Dodo Payments e obtenha suas credenciais no painel:

Chave da API: Painel → Desenvolvedor → Chaves da API
Chave do Webhook: Painel → Desenvolvedor → Webhooks

Certifique-se de estar no Modo de Teste enquanto desenvolve!

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.

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:

Endpoint	Método	Descrição
`/checkout`	POST	Criar uma nova sessão de checkout
`/webhook`	POST	Lidar com webhooks do Dodo Payments
`/customer-portal`	POST	Gerar 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.checkout_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.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

O boilerplate demonstra o manuseio de eventos comuns de webhook:

Evento	Descrição
`payment.succeeded`	Pagamento concluído com sucesso
`payment.failed`	Tentativa de pagamento falhou
`subscription.active`	Assinatura agora está ativa
`subscription.cancelled`	Assinatura foi cancelada
`refund.succeeded`	Reembolso 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

Import errors or missing modules

Certifique-se de que seu ambiente virtual esteja ativado e as dependências instaladas:

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

Checkout session creation fails

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

Webhooks not receiving events

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.

Webhook signature verification fails

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?

Junte-se à nossa comunidade no Discord para perguntas e discussões
Verifique o repositório do GitHub para problemas e atualizações
Entre em contato com nossa equipe de suporte para assistência

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Visão Geral

Recursos

Pré-requisitos

Início Rápido

Estrutura do Projeto

Endpoints da API

Exemplos de Código

Criando uma Sessão de Checkout

Manipulando Webhooks

Integração do Portal do Cliente

Eventos de Webhook

Testando Webhooks Localmente

Implantação

Docker

Considerações de Produção

Solução de Problemas

Saiba Mais

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

Suporte

GitHub Repository

​Visão Geral

​Recursos

​Pré-requisitos

​Início Rápido

​Estrutura do Projeto

​Endpoints da API

​Exemplos de Código

​Criando uma Sessão de Checkout

​Manipulando Webhooks

​Integração do Portal do Cliente

​Eventos de Webhook

​Testando Webhooks Localmente

​Implantação

​Docker

​Considerações de Produção

​Solução de Problemas

​Saiba Mais

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Suporte

Visão Geral

Recursos

Pré-requisitos

Início Rápido

Estrutura do Projeto

Endpoints da API

Exemplos de Código

Criando uma Sessão de Checkout

Manipulando Webhooks

Integração do Portal do Cliente

Eventos de Webhook

Testando Webhooks Localmente

Implantação

Docker

Considerações de Produção

Solução de Problemas

Saiba Mais

Suporte