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": "pdt_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:

POST /subscriptions (o método subscriptions.create do SDK) está obsoleto. Ele ainda funciona para integrações existentes, mas novas integrações devem criar assinaturas por meio de uma Checkout Session.

# 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 exige, no mínimo, o código de país ISO de duas letras. customer aceita {"customer_id": ...} para associar um customer existente ou {"email": ..., "name": ...} para criar um novo. product_price está na menor denominação da moeda.

Faturamento baseado em uso

Ingerir eventos de uso

Rastreie 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",
    page_size=20
)

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

Paginação

Paginação automática

Itere automaticamente por todos os itens:

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 ter mais controle sobre a 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

Personalize 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 obter desempenho assíncrono aprimorado:

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 definindo a variável de ambiente:

export DODO_PAYMENTS_LOG=info

Ou para logging no nível de debug:

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

Visualize o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Relate bugs ou solicite recursos

Suporte

Precisa de ajuda com o Python SDK?

Discord: participe do nosso servidor da comunidade para obter suporte em tempo real
Email: entre em contato conosco pelo endereço support@dodopayments.com
GitHub: abra uma issue no repositório

Contribuição

Aceitamos contribuições! Consulte 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

​Faturamento baseado em uso

​Ingerir 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

​Contribuição

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

Faturamento baseado em uso

Ingerir 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

Contribuição