Python - Dodo Payments Documentation

O SDK Python oferece uma interface Pythonic para a API de Pagamentos Dodo, fornecendo tanto clientes síncronos quanto assíncronos com definições de tipo para requisições e respostas. Ele suporta Python 3.9+ e inclui uma cobertura de testes abrangente.

Instalação

Instale o SDK usando pip:

pip install dodopayments

Para desempenho assíncrono aprimorado com aiohttp:

pip install dodopayments[aiohttp]

O SDK requer Python 3.9 ou superior. Recomendamos usar a versão estável mais recente do Python para melhor experiência e atualizações de segurança.

Início Rápido

Cliente Síncrono

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

checkout_session_response = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1
        }
    ],
)
print(checkout_session_response.session_id)

Cliente Assíncrono

import os
import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

async def main() -> None:
    checkout_session_response = await client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": "product_id",
                "quantity": 1,
            }
        ],
    )
    print(checkout_session_response.session_id)

asyncio.run(main())

Armazene sempre suas chaves de API de forma segura usando variáveis de ambiente. Nunca as inclua no controle de versão.

Recursos Principais

Pythonic Interface

Código Python limpo e idiomático que segue as diretrizes do PEP 8 e as convenções do Python

Async/Await

Suporte total para operações assíncronas com asyncio e integração opcional com aiohttp

Type Hints

Anotações de tipo completas para melhor suporte das IDEs e verificação de tipos com mypy

Auto-Pagination

Paginação automática para respostas de listas com iteração simples

Configuração

Variáveis de Ambiente

Configure usando variáveis de ambiente:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

Timeouts

Configure timeouts de requisição globalmente ou por requisição:

import httpx
from dodopayments import DodoPayments

# Configure default for all requests (default is 1 minute)
client = DodoPayments(
    timeout=20.0,  # 20 seconds
)

# More granular control
client = DodoPayments(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request
client.with_options(timeout=5.0).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)

Retentativas

Configure o comportamento de retentativa automática:

from dodopayments import DodoPayments

# Configure default for all requests (default is 2)
client = DodoPayments(
    max_retries=0,  # disable retries
)

# Override per-request
client.with_options(max_retries=5).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)

Operações Comuns

Criar uma Sessão de Checkout

Gere uma sessão de checkout:

session = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "prod_123",
            "quantity": 1
        }
    ],
    return_url="https://yourdomain.com/return"
)

print(f"Checkout URL: {session.checkout_url}")

Gerenciar Clientes

Crie e recupere informações de clientes:

# Create a customer
customer = client.customers.create(
    email="customer@example.com",
    name="John Doe",
    metadata={
        "user_id": "12345"
    }
)

# Retrieve customer
customer = client.customers.retrieve("cus_123")
print(f"Customer: {customer.name} ({customer.email})")

Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes:

# Create a subscription
subscription = client.subscriptions.create(
    billing={
        "country": "US",
        "city": "San Francisco",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "cus_123"},  # or {"email": "...", "name": "..."} for a new customer
    product_id="pdt_456",
    quantity=1,
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge_response = client.subscriptions.charge(
    subscription_id=subscription.subscription_id,
    product_price=2500,
)

# Retrieve usage history (for metered subscriptions)
usage_history = client.subscriptions.retrieve_usage_history(
    subscription_id=subscription.subscription_id,
    start_date="2024-01-01T00:00:00Z",
)

billing requer pelo menos o código de país ISO de duas letras. customer aceita {"customer_id": ...} para anexar um cliente existente ou {"email": ..., "name": ...} para criar um novo. product_price está na menor denominação de moeda.

Billing baseado em uso

Capturar eventos de uso

Acompanhe eventos personalizados para faturamento baseado em uso:

response = client.usage_events.ingest(
    events=[
        {
            "event_id": "api_call_12345",
            "customer_id": "cus_abc123",
            "event_name": "api_request",
            "timestamp": "2024-01-15T10:30:00Z",
            "metadata": {
                "endpoint": "/api/v1/users",
                "method": "GET",
                "tokens_used": "150"
            }
        }
    ]
)

Listar e recuperar eventos

# Get a specific event
event = client.usage_events.retrieve("api_call_12345")

# List events with filtering
events = client.usage_events.list(
    customer_id="cus_abc123",
    event_name="api_request",
    limit=20
)

for event in events.data:
    print(f"Event: {event.event_id} at {event.timestamp}")

Paginação

Paginação automática

Iterar por todos os itens automaticamente:

from dodopayments import DodoPayments

client = DodoPayments()
all_payments = []

# Automatically fetches more pages as needed
for payment in client.payments.list():
    all_payments.append(payment)
print(all_payments)

Paginação assíncrona

import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments()

async def main() -> None:
    all_payments = []
    # Iterate through items across all pages
    async for payment in client.payments.list():
        all_payments.append(payment)
    print(all_payments)

asyncio.run(main())

Paginação manual

Para mais controle sobre paginação:

# Access items from current page
first_page = client.payments.list()
for payment in first_page.items:
    print(payment.brand_id)

# Check for more pages
if first_page.has_next_page():
    next_page = first_page.get_next_page()
    print(f"Fetched {len(next_page.items)} more items")

Configuração do cliente HTTP

Customize o cliente httpx subjacente:

import httpx
from dodopayments import DodoPayments, DefaultHttpxClient

client = DodoPayments(
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Assíncrono com aiohttp

Use aiohttp para melhorar o desempenho assíncrono:

import asyncio
from dodopayments import DefaultAioHttpClient
from dodopayments import AsyncDodoPayments

async def main() -> None:
    async with AsyncDodoPayments(
        bearer_token="My Bearer Token",
        http_client=DefaultAioHttpClient(),
    ) as client:
        checkout_session_response = await client.checkout_sessions.create(
            product_cart=[
                {
                    "product_id": "product_id",
                    "quantity": 1,
                }
            ],
        )
        print(checkout_session_response.session_id)

asyncio.run(main())

Logging

Ative o logging configurando a variável de ambiente:

export DODO_PAYMENTS_LOG=info

Ou para logging em nível de depuração:

export DODO_PAYMENTS_LOG=debug

Integração com frameworks

FastAPI

from fastapi import FastAPI, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
import os

app = FastAPI()
dodo = AsyncDodoPayments(bearer_token=os.getenv("DODO_API_KEY"))

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int

@app.post("/create-checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            return_url="https://yourdomain.com/return"
        )
        return {"checkout_url": session.checkout_url}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

Django

from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt
from dodopayments import DodoPayments
import os
import json

client = DodoPayments(bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"))

@csrf_exempt
@require_POST
def create_checkout(request):
    try:
        data = json.loads(request.body)
        session = client.checkout_sessions.create(
            product_cart=[{
                "product_id": data.get("product_id"),
                "quantity": data.get("quantity", 1)
            }],
            return_url="https://yourdomain.com/return"
        )
        return JsonResponse({
            "status": "success",
            "checkout_url": session.checkout_url,
            "session_id": session.session_id
        })
    except Exception as e:
        return JsonResponse({
            "status": "error",
            "message": str(e)
        }, status=400)

Recursos

GitHub Repository

Veja o código fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Relatar bugs ou solicitar recursos

Suporte

Precisa de ajuda com o SDK Python?

Discord: Entre em nosso servidor da comunidade para suporte em tempo real
Email: Entre em contato pelo suporte@dodopayments.com
GitHub: Abra um problema no repositório

Contribuindo

Nós recebemos contribuições! Confira as diretrizes de contribuição para começar.

​Instalação

​Início Rápido

​Cliente Síncrono

​Cliente Assíncrono

​Recursos Principais

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

​Configuração

​Variáveis de Ambiente

​Timeouts

​Retentativas

​Operações Comuns

​Criar uma Sessão de Checkout

​Gerenciar Clientes

​Gerenciar Assinaturas

​Billing baseado em uso

​Capturar eventos de uso

​Listar e recuperar eventos

​Paginação

​Paginação automática

​Paginação assíncrona

​Paginação manual

​Configuração do cliente HTTP

​Assíncrono com aiohttp

​Logging

​Integração com frameworks

​FastAPI

​Django

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Suporte

​Contribuindo

Instalação

Início Rápido

Cliente Síncrono

Cliente Assíncrono

Recursos Principais

Configuração

Variáveis de Ambiente

Timeouts

Retentativas

Operações Comuns

Criar uma Sessão de Checkout

Gerenciar Clientes

Gerenciar Assinaturas

Billing baseado em uso

Capturar eventos de uso

Listar e recuperar eventos

Paginação

Paginação automática

Paginação assíncrona

Paginação manual

Configuração do cliente HTTP

Assíncrono com aiohttp

Logging

Integração com frameworks

FastAPI

Django

Recursos

Suporte

Contribuindo