Metadata-Version: 2.5
Name: ourpay-sdk
Version: 1.0.0a19
Summary: OurPay SDK — A billing platform for the intelligence era
Project-URL: homepage, https://docs.ourpay.dev/integrate/sdk/python
Project-URL: documentation, https://docs.ourpay.dev/integrate/sdk/python
Author-email: OurPay <contact@ourpay.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: adaptix==3.0.0b12
Requires-Dist: httpx>=0.28.1
Requires-Dist: typing-extensions>=4.13.0
Description-Content-Type: text/markdown

# OurPay Python SDK

The official Python client for the [OurPay API](https://docs.ourpay.dev/api-reference).

## Installation

The SDK requires Python 3.11 or later.

The SDK is currently available as a preview wheel from the OurPay documentation site. To install it with `uv`:

```bash
uv add "ourpay-sdk @ https://docs.ourpay.dev/downloads/ourpay_sdk-1.0.0a19-py3-none-any.whl"
```

or, with `pip`:

```bash
pip install "ourpay-sdk @ https://docs.ourpay.dev/downloads/ourpay_sdk-1.0.0a19-py3-none-any.whl"
```

## Quick Start

Create an [organization access token](https://docs.ourpay.dev/integrate/oat) and use the client for
the current API version:

```python
from ourpay.v2026_10 import OurPay

ourpay = OurPay("ourpay_oat_xxx")

customer_state = ourpay.customers.get_state_external("customer_external_id")
print(customer_state)
```

### Async Client

Use `OurPayAsync` in asynchronous applications:

```python
import asyncio

from ourpay.v2026_10 import OurPayAsync


async def main() -> None:
    ourpay = OurPayAsync("ourpay_oat_xxx")
    customer_state = await ourpay.customers.get_state_external("customer_external_id")
    print(customer_state)


asyncio.run(main())
```

## Context Managers

Both clients support context managers to close their HTTP connections automatically when the
block exits.

For synchronous applications, use `OurPay` with `with`:

```python
from ourpay.v2026_10 import OurPay

with OurPay("ourpay_oat_xxx") as ourpay:
    customer_state = ourpay.customers.get_state_external("customer_external_id")
    print(customer_state)
```

For asynchronous applications, use `OurPayAsync` with `async with`:

```python
import asyncio

from ourpay.v2026_10 import OurPayAsync


async def main() -> None:
    async with OurPayAsync("ourpay_oat_xxx") as ourpay:
        customer_state = await ourpay.customers.get_state_external(
            "customer_external_id"
        )
        print(customer_state)


asyncio.run(main())
```

The client uses the production environment by default. To use the sandbox, pass
`environment="sandbox"` when creating the client. Sandbox and production access tokens are
separate.

Keep organization access tokens on the server and never expose them in browser or client-side
code.

## Request Timeouts

Set the default timeout for all requests when creating the client. Timeout values are expressed
in seconds:

```python
ourpay = OurPay("ourpay_oat_xxx", timeout=30)
```

Override the timeout for an individual request with `request_timeout`:

```python
customer_state = ourpay.customers.get_state_external(
    "customer_external_id",
    request_timeout=60,
)
```

Pass an `httpx.Timeout` instance to configure connect, read, write, and pool timeouts separately.

## Deserializing Data

Use `deserialize` to convert arbitrary data into a generated SDK model or union type:

```python
from ourpay import deserialize
from ourpay.v2026_10.outputs import Customer

customer = deserialize(data, Customer)
```

## Webhooks

Use `validate_event` to verify that a webhook was sent by OurPay and parse it into a typed payload
for the selected API version. Pass the raw request body, the request headers, and your webhook
signing secret:

```python
import os

from fastapi import FastAPI, HTTPException, Request

from ourpay.v2026_10.webhooks import (
    OurPayWebhookError,
    OurPayWebhookVerificationError,
    validate_event,
)

app = FastAPI()
webhook_secret = os.environ["OURPAY_WEBHOOK_SECRET"]


@app.post("/webhooks/ourpay")
async def ourpay_webhook(request: Request) -> dict[str, bool]:
    try:
        event = validate_event(
            await request.body(),
            dict(request.headers),
            webhook_secret,
        )
    except OurPayWebhookVerificationError as exc:
        raise HTTPException(
            status_code=403, detail="Invalid webhook signature"
        ) from exc
    except OurPayWebhookError as exc:
        raise HTTPException(status_code=400, detail="Invalid webhook payload") from exc

    if event.type == "order.created":
        print(event.data.id)

    return {"received": True}
```

The signature is checked before the body is parsed. `validate_event` raises
`OurPayWebhookVerificationError` for invalid signatures and `OurPayWebhookUnknownTypeError` when the
event is not supported by the selected API version. Both inherit from `OurPayWebhookError`.
