> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay.plexos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Official Python SDK for Plexos Pay

## Installation

```bash theme={null}
pip install plexos-pay
```

Requires **Python 3.10+**, **httpx**, and **pydantic v2**.

## Usage

### Sync

```python theme={null}
from plexos_pay import PlexosPay

client = PlexosPay(api_key="sk_test_...")

# Create a payment
payment = client.payments.create({
    "amount": 10000,
    "operator": "CVMOVEL",
    "operatorPhone": "+2389001234",
})
print(payment.id, payment.status)

# Create a checkout session
session = client.checkout.create({
    "items": [
        {"name": "T-Shirt", "quantity": 2, "unitPrice": 15000},
    ],
    "returnUrl": "https://myshop.com/thanks",
})
print(session.url)
```

### Async

```python theme={null}
from plexos_pay import PlexosPayAsync

async def main():
    async with PlexosPayAsync(api_key="sk_test_...") as client:
        payment = await client.payments.create({
            "amount": 10000,
            "operator": "CVMOVEL",
            "operatorPhone": "+2389001234",
        })
```

### Pydantic Models

You can pass dicts or typed Pydantic models:

```python theme={null}
from plexos_pay.models import CreatePaymentParams

payment = client.payments.create(CreatePaymentParams(
    amount=10000,
    operator="CVMOVEL",
    operator_phone="+2389001234",
))
```

## Configuration

```python theme={null}
client = PlexosPay(
    api_key="sk_test_...",       # or PLEXOS_PAY_SECRET_KEY env var
    base_url="https://...",      # or PLEXOS_PAY_BASE_URL env var
    timeout=30.0,                # seconds (default: 30)
    max_retries=3,               # default: 3
)
```

## Webhook Verification

```python theme={null}
from plexos_pay import verify_webhook_signature

event = verify_webhook_signature(
    body=raw_body,
    signature=headers["x-plexos-signature"],
    timestamp=headers["x-plexos-timestamp"],
    secret="whsec_...",
)
```

## Error Handling

```python theme={null}
from plexos_pay import NotFoundError, RateLimitError

try:
    client.payments.get("pi_nonexistent")
except NotFoundError as err:
    print(err.status_code, err.code)  # 404, "NOT_FOUND"
except RateLimitError:
    print("Too many requests")
```

## Resources

| Resource       | Methods                                      |
| -------------- | -------------------------------------------- |
| `payments`     | `create`, `get`, `list`, `confirm`, `cancel` |
| `customers`    | `create`, `get`, `list`, `update`            |
| `products`     | `create`, `get`, `list`, `update`, `delete`  |
| `checkout`     | `create`, `get`, `list`, `expire`            |
| `refunds`      | `create`, `get`, `list`                      |
| `webhooks`     | `create`, `get`, `list`, `update`, `delete`  |
| `balance`      | `get`                                        |
| `settlements`  | `get`, `list`, `process`                     |
| `transactions` | `list`                                       |
| `analytics`    | `revenue`                                    |
| `audit_logs`   | `list`                                       |

<Card title="GitHub" icon="github" href="https://github.com/plexos-pay/sdk-python">
  View source code and report issues
</Card>