Python - Dodo Payments Documentation

El SDK de Python ofrece una interfaz Pythonic para la API de Dodo Payments, proporcionando tanto clientes síncronos como asíncronos con definiciones de tipo para solicitudes y respuestas. Soporta Python 3.9+ e incluye una cobertura de pruebas completa.

Instalación

Instala el SDK usando pip:

pip install dodopayments

Para un mejor rendimiento asíncrono con aiohttp:

pip install dodopayments[aiohttp]

El SDK requiere Python 3.9 o posterior. Recomendamos usar la versión estable más reciente de Python para obtener la mejor experiencia y las actualizaciones de seguridad.

Inicio 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 Así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())

Guarda siempre tus claves de API de forma segura utilizando variables de entorno. Nunca las incluyas en el control de versiones.

Características Principales

Pythonic Interface

Código Python limpio e idiomático que sigue las directrices de PEP 8 y las convenciones de Python

Async/Await

Compatibilidad total con operaciones asíncronas usando asyncio e integración opcional con aiohttp

Type Hints

Sugerencias de tipos completas para mejorar el soporte en IDE y la comprobación de tipos con mypy

Auto-Pagination

Paginación automática para respuestas de listas con iteración sencilla

Configuración

Variables de Entorno

Configura usando variables de entorno:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

Tiempos de Espera

Configura los tiempos de espera de las solicitudes a nivel global o por solicitud:

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,
        }
    ],
)

Reintentos

Configura el comportamiento de reintento automático:

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,
        }
    ],
)

Operaciones Comunes

Crear una Sesión de Pago

Genera una sesión de pago:

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

Gestionar Clientes

Crea y recupera información 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})")

Manejar Suscripciones

Crea y gestiona suscripciones recurrentes:

El método POST /subscriptions (el método subscriptions.create del SDK) está obsoleto. Sigue funcionando para las integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante una 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 requiere como mínimo el código de país ISO de dos letras. customer acepta {"customer_id": ...} para asociar un customer existente o {"email": ..., "name": ...} para crear uno nuevo. product_price está expresado en la denominación monetaria más baja.

Facturación basada en el uso

Ingerir eventos de uso

Registra eventos personalizados para la facturación basada en el 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"
            }
        }
    ]
)

Enumerar y 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}")

Paginación

Paginación automática

Itera automáticamente por todos los elementos:

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)

Paginación así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())

Paginación manual

Para tener más control sobre la paginación:

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

Configuración del cliente HTTP

Personaliza el cliente httpx subyacente:

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

Async con aiohttp

Usa aiohttp para mejorar el rendimiento así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())

Registro de eventos

Activa el registro de eventos configurando la variable de entorno:

export DODO_PAYMENTS_LOG=info

O para habilitar el registro de nivel de depuración:

export DODO_PAYMENTS_LOG=debug

Integración con 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

Consulta el código fuente y contribuye

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conecta con otros desarrolladores

Report Issues

Informa de errores o solicita funcionalidades

Soporte

¿Necesitas ayuda con el Python SDK?

Discord: Únete a nuestro servidor de la comunidad para obtener soporte en tiempo real
Email: Contáctanos en support@dodopayments.com
GitHub: Abre un issue en el repositorio

Contribuir

¡Damos la bienvenida a las contribuciones! Consulta las directrices para contribuir para comenzar.

​Instalación

​Inicio Rápido

​Cliente Síncrono

​Cliente Asíncrono

​Características Principales

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

​Configuración

​Variables de Entorno

​Tiempos de Espera

​Reintentos

​Operaciones Comunes

​Crear una Sesión de Pago

​Gestionar Clientes

​Manejar Suscripciones

​Facturación basada en el uso

​Ingerir eventos de uso

​Enumerar y recuperar eventos

​Paginación

​Paginación automática

​Paginación asíncrona

​Paginación manual

​Configuración del cliente HTTP

​Async con aiohttp

​Registro de eventos

​Integración con frameworks

​FastAPI

​Django

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuir

Instalación

Inicio Rápido

Cliente Síncrono

Cliente Asíncrono

Características Principales

Configuración

Variables de Entorno

Tiempos de Espera

Reintentos

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación basada en el uso

Ingerir eventos de uso

Enumerar y recuperar eventos

Paginación

Paginación automática

Paginación asíncrona

Paginación manual

Configuración del cliente HTTP

Async con aiohttp

Registro de eventos

Integración con frameworks

FastAPI

Django

Recursos

Soporte

Contribuir