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

POST /subscriptions (il metodo subscriptions.create dell’SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliabile creare gli abbonamenti tramite 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 richiede almeno il codice paese ISO di due lettere. customer accetta {"customer_id": ...} per associare un cliente esistente oppure {"email": ..., "name": ...} per crearne uno nuovo. product_price è espresso nella denominazione più bassa della valuta.

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Monitora gli eventi personalizzati per la fatturazione basata sull’utilizzo:

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

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

Paginazione

Paginazione automatica

Scorri automaticamente 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 avere 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 del client HTTP

Personalizza il client httpx sottostante:

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 migliorare le prestazioni asincrone:

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 abilitare il logging a livello di debug:

export DODO_PAYMENTS_LOG=debug

Integrazione con i 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 assistenza e connettiti con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

Supporto

Hai bisogno di aiuto con l’SDK Python?

Discord: Unisciti al nostro server della community per ricevere assistenza in tempo reale
Email: Contattaci all’indirizzo support@dodopayments.com
GitHub: Apri una segnalazione nel repository

Contributi

Accogliamo con piacere i contributi! Consulta le linee guida per i 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’utilizzo

​Acquisizione degli eventi di utilizzo

​Elencare e recuperare gli eventi

​Paginazione

​Paginazione automatica

​Paginazione asincrona

​Paginazione manuale

​Configurazione del client HTTP

​Async con aiohttp

​Logging

​Integrazione con i 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’utilizzo

Acquisizione degli eventi di utilizzo

Elencare e recuperare gli eventi

Paginazione

Paginazione automatica

Paginazione asincrona

Paginazione manuale

Configurazione del client HTTP

Async con aiohttp

Logging

Integrazione con i framework

FastAPI

Django

Risorse

Supporto

Contributi