Metadata-Version: 2.4
Name: orcuspay
Version: 1.0.0
Summary: Official Python SDK for the OrcusPay API
Author-email: OrcusHQ <support@orcus.com.bd>
License: MIT
Project-URL: Homepage, https://orcuspay.com
Project-URL: Documentation, https://docs.orcuspay.com/sdks/python
Project-URL: Repository, https://github.com/OrcusHQ/orcuspay-python
Keywords: orcuspay,payment,checkout,bkash,nagad,bangladesh
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# OrcusPay Python SDK

Official Python client for the [OrcusPay API](https://docs.orcuspay.com).

## Install

```bash
pip install orcuspay
```

## Quick Start

```python
from orcuspay import OrcusPay

client = OrcusPay(
    access_key="ak_test_xxxxx",
    secret_key="sk_test_xxxxx",
)

# Create a checkout session
session = client.create_checkout_session({
    "success_url": "https://yoursite.com/success?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yoursite.com/cancel",
    "line_items": [
        {
            "quantity": 1,
            "price_data": {
                "unit_amount": 50000,  # 500.00 BDT in paisa
                "product_data": {"name": "Premium Plan"},
            },
        }
    ],
    "currency": "BDT",
    "customer": {
        "name": "Test Customer",
        "email": "customer@example.com",
        "phone": "01700000000",
    },
})

# Redirect customer to session["url"]
print(session["url"])
```

## Retrieve a Checkout Session

```python
session = client.get_checkout_session("pay_abc123")
print(session["payment_status"])  # SUCCEEDED | PENDING | FAILED
```

## List Payments

```python
payments = client.list_payments(limit=10, status="SUCCEEDED")

for payment in payments["payments"]:
    print(payment["id"], payment["amount"])
```

## Create a Payment Link

```python
link = client.create_payment_link({
    "title": "Donation",
    "amount": 500,
    "is_reusable": True,
    "success_url": "https://yoursite.com/thanks",
})

print(link["url"])
```

## Error Handling

```python
from orcuspay import OrcusPay, OrcusPayError

try:
    payment = client.get_payment("invalid_id")
except OrcusPayError as e:
    print(e.code)     # "not_found"
    print(e.message)  # "Payment not found" (str(e))
    print(e.status)   # 404
```

## Available Methods

- `create_checkout_session(params)` — Create a hosted checkout page
- `get_checkout_session(id)` — Retrieve a checkout session
- `list_payments(limit?, cursor?, status?)` — List payments with pagination
- `get_payment(id)` — Retrieve a single payment
- `list_payment_links(limit?, cursor?)` — List payment links
- `create_payment_link(params)` — Create a payment link
- `get_payment_link(id)` — Retrieve a payment link
- `status()` — Check API status

## Custom API URL

For self-hosted OrcusPay instances:

```python
client = OrcusPay(
    access_key="ak_prod_xxxxx",
    secret_key="sk_prod_xxxxx",
    api_url="https://your-instance.com/api/v1",
)
```

## Requirements

- Python 3.9+
- `requests` library

## License

MIT
