Python - Dodo Payments Documentation

Il SDK Python offre un’interfaccia Pythonica per l’API Dodo Payments, fornendo sia client sincroni che asincroni con definizioni di tipo per richieste e risposte. Supporta Python 3.9+ e include una copertura di test completa.

Installazione

Installa il SDK usando pip:

pip install dodopayments

Per prestazioni asincrone migliorate con aiohttp:

pip install dodopayments[aiohttp]

L’SDK richiede Python 3.9 o versioni successive. Consigliamo di utilizzare l’ultima versione stabile di Python per offrire la migliore esperienza e gli aggiornamenti di sicurezza.

Avvio Veloce

Client Sincrono

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)

Client Asincrono

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())

Conserva sempre in modo sicuro le chiavi API usando le variabili d’ambiente. Non inserirle mai nel controllo versione.

Caratteristiche Principali

Pythonic Interface

Codice Python pulito e idiomatico che segue le linee guida di PEP 8 e le convenzioni Python

Async/Await

Supporto completo per le operazioni asincrone con asyncio e integrazione opzionale con aiohttp

Type Hints

Hint di tipo completi per un migliore supporto IDE e controllo dei tipi con mypy

Auto-Pagination

Paginazione automatica per le risposte di elenco con semplice iterazione

Configurazione

Variabili d’Ambiente

Configura utilizzando variabili d’ambiente:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

Timeout

Configura i timeout delle richieste globalmente o per richiesta:

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

Riprova

Configura il comportamento di riprova automatica:

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

Operazioni Comuni

Crea una Sessione di Checkout

Genera una sessione di 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}")

Gestisci Clienti

Crea e recupera informazioni sui clienti:

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

Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti:

# 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 richiede almeno il codice ISO del paese a due lettere. customer accetta {"customer_id": ...} per allegare un cliente esistente o {"email": ..., "name": ...} per crearne uno nuovo. product_price è nella denominazione più bassa della valuta.

Fatturazione Basata sull’Uso

Ingestione degli Eventi di Utilizzo

Traccia eventi personalizzati per la fatturazione basata sull’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"
            }
        }
    ]
)

Elencare e Recuperare Eventi

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

Paginazione

Auto-Paginazione

Iterare automaticamente attraverso tutti gli elementi:

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)

Paginazione Asincrona

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())

Paginazione Manuale

Per un maggiore controllo sulla paginazione:

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

Configurazione Client HTTP

Personalizza il client sottostante httpx:

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 per prestazioni asincrone migliorate:

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

Abilita il logging impostando la variabile d’ambiente:

export DODO_PAYMENTS_LOG=info

Oppure per il logging a livello di debug:

export DODO_PAYMENTS_LOG=debug

Integrazione 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)

Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Documentazione completa dell’API

Discord Community

Ottieni aiuto e connettiti con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

Supporto

Hai bisogno di aiuto con il Python SDK?

Discord: Unisciti al nostro server della community per supporto in tempo reale
Email: Contattaci a support@dodopayments.com
GitHub: Apri un problema nel repository

Contributi

Accogliamo con favore i contributi! Controlla le linee guida sui contributi per iniziare.

​Installazione

​Avvio Veloce

​Client Sincrono

​Client Asincrono

​Caratteristiche Principali

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

​Configurazione

​Variabili d’Ambiente

​Timeout

​Riprova

​Operazioni Comuni

​Crea una Sessione di Checkout

​Gestisci Clienti

​Gestisci Abbonamenti

​Fatturazione Basata sull’Uso

​Ingestione degli Eventi di Utilizzo

​Elencare e Recuperare Eventi

​Paginazione

​Auto-Paginazione

​Paginazione Asincrona

​Paginazione Manuale

​Configurazione Client HTTP

​Async con aiohttp

​Logging

​Integrazione con Framework

​FastAPI

​Django

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contributi

Installazione

Avvio Veloce

Client Sincrono

Client Asincrono

Caratteristiche Principali

Configurazione

Variabili d’Ambiente

Timeout

Riprova

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci Clienti

Gestisci Abbonamenti

Fatturazione Basata sull’Uso

Ingestione degli Eventi di Utilizzo

Elencare e Recuperare Eventi

Paginazione

Auto-Paginazione

Paginazione Asincrona

Paginazione Manuale

Configurazione Client HTTP

Async con aiohttp

Logging

Integrazione con Framework

FastAPI

Django

Risorse

Supporto

Contributi