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

# 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 adjuntar un cliente existente o {"email": ..., "name": ...} para crear uno nuevo. product_price está en la denominación más baja de la moneda.

Facturación Basada en Uso

Ingestar Eventos de Uso

Rastrear eventos personalizados para la facturación basada en 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 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",
    limit=20
)

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

Paginación

Paginación Automática

Iterar automáticamente a través de 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 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

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

Asíncrono con aiohttp

Usar aiohttp para un rendimiento asíncrono mejorado:

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 Log

Habilitar el registro de log configurando la variable de entorno:

export DODO_PAYMENTS_LOG=info

O para el registro de log a nivel de depuración:

export DODO_PAYMENTS_LOG=debug

Integración con Framework

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

Ver el código fuente y contribuir

API Reference

Documentación completa de la API

Discord Community

Obtener ayuda y conectarse con desarrolladores

Report Issues

Reportar errores o solicitar características

Soporte

¿Necesitas ayuda con el SDK de Python?

Discord: Únete a nuestro servidor de la comunidad para soporte en tiempo real
Correo electrónico: Contáctanos en support@dodopayments.com
GitHub: Abre un problema en el repositorio

Contribuir

¡Damos la bienvenida a las contribuciones! Consulta la guía de contribuciones 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 Uso

​Ingestar Eventos de Uso

​Listar y Recuperar Eventos

​Paginación

​Paginación Automática

​Paginación Asíncrona

​Paginación Manual

​Configuración del Cliente HTTP

​Asíncrono con aiohttp

​Registro de Log

​Integración con Framework

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

Ingestar Eventos de Uso

Listar y Recuperar Eventos

Paginación

Paginación Automática

Paginación Asíncrona

Paginación Manual

Configuración del Cliente HTTP

Asíncrono con aiohttp

Registro de Log

Integración con Framework

FastAPI

Django

Recursos

Soporte

Contribuir