Metadata-Version: 2.4
Name: thawani
Version: 1.1.5
Summary: Thawani Python Client
Author-email: Murad Lansa <mail@muradlansa.com>
License: MIT
Project-URL: Homepage, https://github.com/muradlansa/thawani-python
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# Thawani Python Client

Python SDK for integrating with the **Thawani Checkout API**.

This package is used by ERPNext/Payments integrations and can also be used directly in standalone Python services.

## Requirements

- Python `>=3.6`
- `requests`

## Installation

### From PyPI

```bash
pip install thawani
```

### From local source (editable)

```bash
pip install -e /path/to/thawani-python
```

## Quick Start

> Get your API keys from your Thawani merchant dashboard.

```python
import thawani

client = thawani.Client(
    secret_key="<SECRET_KEY>",
    publishable_key="<PUBLISHABLE_KEY>",
    use_sandbox=True,   # False for production
)
```

Backward-compatible initialization is still supported:

```python
client = thawani.Client(data={
    "secret_key": "<SECRET_KEY>",
    "publishable_key": "<PUBLISHABLE_KEY>",
    "use_sandbox": 1,
})
```

## Common Checkout Flow

Create a checkout session and get a payment URL:

```python
payload = {
    "client_reference_id": "CUST-0001",
    "mode": "payment",
    "products": [
        {"name": "Online Payment", "quantity": 1, "unit_amount": "1000"}
    ],
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
}

resp = client.checkout.create(data=payload)
payment_url = client.generate_payment_link(resp)
print(payment_url)
```

Fetch a session status:

```python
session = client.checkout.fetch("SESSION_ID")
print(session)
```

Fetch by reference id:

```python
session = client.checkout.fetch_session_by_client_id("CLIENT_REFERENCE_ID")
print(session)
```

## Available Resources

The client exposes these resource handlers:

- `checkout`
- `customer`
- `payment_intent`
- `payment_method`
- `payment`
- `refund`
- `invoice`
- `order`
- `payment_link`
- `subscription`
- `registration_link`
- `card`
- `token`
- `transfer`
- `virtual_account`
- `fund_account`
- `addon`
- `plan`
- `settlement`
- `item`
- `qrcode`
- `utility`

Each resource typically supports one or more of:
`create`, `fetch`, `all`, `edit`, `delete`.

## Error Handling

All API failures raise SDK exceptions:

- `BadRequestError`
- `GatewayError`
- `ServerError`

Example:

```python
from thawani.errors import BadRequestError, GatewayError, ServerError

try:
    client.checkout.fetch("invalid-session")
except BadRequestError as e:
    print("Request failed:", e)
except GatewayError as e:
    print("Gateway error:", e)
except ServerError as e:
    print("Server error:", e)
```

## Sandbox and Production

- Sandbox API base: `https://uatcheckout.thawani.om/api/v1`
- Production API base: `https://checkout.thawani.om/api/v1`

`use_sandbox=True` switches the client to sandbox URLs.

## Development

Run tests:

```bash
pytest
```

Format/lint according to your local project standards before publishing.

## Documentation

Detailed resource docs are in [documents/](/opt/bench/erpnext/thawani-python/documents):

- [Checkout-related examples](./documents/paymentVerfication.md)
- [Customers](./documents/customer.md)
- [Payments](./documents/payment.md)
- [Refunds](./documents/refund.md)
- [Invoice](./documents/invoice.md)
- [Subscriptions](./documents/subscription.md)

## Contributing

Issues and pull requests are welcome:

- [Issues](https://github.com/muradlansa/thawani-python/issues)
- [Pull Requests](https://github.com/muradlansa/thawani-python/pulls)
