# Python SDK

The official Python SDK for PaymentKit.

## Installation

```bash
pip install payment-kit
```

## Quick Start

```python
from payment_kit import PaymentKit

client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)

# Create a customer
customer = client.customers.create_customer(
    account_id="acc_prod_abc123",
    email="customer@example.com",
)

# Create a subscription
from datetime import datetime

subscription = client.subscriptions.create_subscription(
    account_id="acc_prod_abc123",
    customer_id=customer.id,
    period_start=datetime.now(),
    items=[{"price_id": "prc_prod_xyz789", "quantity": 1}],
)

# List invoices
invoices = client.invoices.list_invoices(
    account_id="acc_prod_abc123",
    limit=10,
)
```

## Environments

| Environment | Base URL                         |
| ----------- | -------------------------------- |
| Production  | `https://app.paymentkit.com`     |
| Staging     | `https://staging.paymentkit.com` |

```python
# Production
client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)

# Staging
client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://staging.paymentkit.com",
)
```

## Async Client

The SDK provides an async client for non-blocking API calls:

```python
import asyncio
from payment_kit import AsyncPaymentKit

client = AsyncPaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)

async def main():
    customer = await client.customers.create_customer(
        account_id="acc_prod_abc123",
        email="customer@example.com",
    )
    print(customer.id)

asyncio.run(main())
```

## Error Handling

```python
from payment_kit.core.api_error import ApiError

try:
    customer = client.customers.create_customer(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)
```

## Configuration

### Timeouts

Default timeout is 60 seconds. Override at client or request level:

```python
# Client-level timeout
client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
    timeout=30.0,
)

# Request-level timeout
customer = client.customers.create_customer(
    ...,
    request_options={"timeout_in_seconds": 10}
)
```

### Retries

The SDK automatically retries requests with exponential backoff for:

* 408 (Request Timeout)
* 409 (Conflict)
* 429 (Too Many Requests)
* 5XX (Server Errors)

```python
# Configure max retries per request (default is 2)
customer = client.customers.create_customer(
    ...,
    request_options={"max_retries": 3}
)
```

## Resources

* [PyPI Package](https://pypi.org/project/payment-kit/)
* [GitHub Repository](https://github.com/payment-kit/payment-kit-python)
* [Full SDK Reference](https://github.com/payment-kit/payment-kit-python/blob/main/reference.md)