Python - Dodo Payments Documentation

Python SDK 提供了一个 Pythonic 接口来访问 Dodo Payments API，提供同步和异步客户端，并为请求和响应提供类型定义。它支持 Python 3.9+ 并包含全面的测试覆盖。

安装

使用 pip 安装 SDK：

pip install dodopayments

为了增强与 aiohttp 的异步性能：

pip install dodopayments[aiohttp]

SDK 需要 Python 3.9 或更高版本。我们建议使用最新的稳定版本的 Python，以获得最佳体验和安全更新。

快速开始

同步客户端

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)

异步客户端

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

始终使用环境变量安全地存储 API 密钥。切勿将它们提交到版本控制系统。

核心功能

Pythonic Interface

遵循 PEP 8 指南和 Python 约定的干净且符合习惯的 Python 代码

Async/Await

完整支持 asyncio 的异步操作，并可选地集成 aiohttp

Type Hints

提供完整的类型提示，以便更好的 IDE 支持和 mypy 类型检查

Auto-Pagination

自动分页处理列表响应，支持简单迭代

配置

环境变量

使用环境变量进行配置：

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

超时

全局或每个请求配置请求超时：

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

重试

配置自动重试行为：

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

常见操作

创建结账会话

生成结账会话：

session = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "prod_123",
            "quantity": 1
        }
    ],
    return_url="https://yourdomain.com/return"
)

print(f"Checkout URL: {session.url}")

管理客户

创建和检索客户信息：

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

处理订阅

创建和管理定期订阅：

# Create a subscription
subscription = client.subscriptions.create(
    customer_id="cus_123",
    product_id="prod_456",
    price_id="price_789"
)

# Retrieve usage history
usage_history = client.subscriptions.retrieve_usage_history(
    subscription.id,
    start_date="2024-01-01T00:00:00Z"
)

基于使用的计费

记录使用事件

跟踪基于使用的计费的自定义事件：

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

列出和检索事件

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

分页

自动分页

自动迭代所有项目：

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)

异步分页

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

手动分页

以获得对分页的更多控制：自定义底层 httpx 客户端：

HTTP 客户端配置

自定义底层 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"),
    ),
)

使用 aiohttp 的异步

使用 aiohttp 提升异步性能：

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

日志记录

通过设置环境变量启用日志记录：

export DODO_PAYMENTS_LOG=info

或用于调试级别的日志记录：

export DODO_PAYMENTS_LOG=debug

框架集成

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.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.url,
            "session_id": session.session_id
        })
    except Exception as e:
        return JsonResponse({
            "status": "error",
            "message": str(e)
        }, status=400)

资源

GitHub Repository

查看源代码并贡献

API Reference

完整的 API 文档

Discord Community

寻求帮助并与开发者交流

Report Issues

报告 Bug 或请求功能

支持

需要 Python SDK 的帮助吗？

Discord：加入我们的社区服务器获取实时支持
电子邮件：通过 support@dodopayments.com 联系我们
GitHub：在仓库上打开一个问题

贡献

我们欢迎贡献！查看贡献指南开始。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​安装

​快速开始

​同步客户端

​异步客户端

​核心功能

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

​配置

​环境变量

​超时

​重试

​常见操作

​创建结账会话

​管理客户

​处理订阅

​基于使用的计费

​记录使用事件

​列出和检索事件

​分页

​自动分页

​异步分页

​手动分页

​HTTP 客户端配置

​使用 aiohttp 的异步

​日志记录

​框架集成

​FastAPI

​Django

​资源

GitHub Repository

API Reference

Discord Community

Report Issues

​支持

​贡献

安装

快速开始

同步客户端

异步客户端

核心功能

配置

环境变量

超时

重试

常见操作

创建结账会话

管理客户

处理订阅

基于使用的计费

记录使用事件

列出和检索事件

分页

自动分页

异步分页

手动分页

HTTP 客户端配置

使用 aiohttp 的异步

日志记录

框架集成

FastAPI

Django

资源

支持

贡献