Metadata-Version: 2.4
Name: devport
Version: 1.0.0
Summary: Python SDK for the Ilambit DevPort API — BharatPe payment verification & history
Project-URL: Homepage, https://devport.ilambit.in
Project-URL: Documentation, https://devport.ilambit.in/docs
Author-email: Ilambit <dev@ilambit.in>
License-Expression: LicenseRef-Proprietary
Keywords: api,bharatpe,devport,payment,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary 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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# devport

Python SDK for the [Ilambit DevPort API](https://devport.ilambit.in) — Unified API gateway for Indian businesses.

## Installation

```bash
pip install devport
```

## Quick Start

1. Sign up at [devport.ilambit.in/signup](https://devport.ilambit.in/signup)
2. Generate an API key from your [dashboard](https://devport.ilambit.in/dashboard)
3. Configure your service credentials (BharatPe / Paytm) in the dashboard
4. Install this SDK and start calling APIs

> ⚠️ **Security:** Never expose your API key in client-side code. Always call the gateway from your backend server.

## Available Services

| Service | Endpoint | Description |
|---------|----------|-------------|
| **BharatPe** | `GET /api/v1/bharatpe/status/:txnId` | Verify a UPI payment by Bank Reference Number (UTR) |
| **BharatPe** | `GET /api/v1/bharatpe/transactions?days=N` | List recent payment transactions (1–7 days) |
| **Paytm** | `GET /api/v1/paytm/status/:orderId` | Verify a Paytm payment by Order ID |

## Usage

### BharatPe — Verify a payment

```python
from devport import bharatpe

result = bharatpe.payment_status(
    api_key="ilm_live_your_api_key_here",
    transaction_id="432112345678",
)

if result.verified:
    print(f"✅ Payment verified! Amount: ₹{result.transaction.amount}")
    print(f"   Payer: {result.transaction.payer_name}")
    print(f"   Status: {result.transaction.status}")
elif result.found:
    print(f"⏳ Transaction found but status is: {result.transaction.status}")
else:
    print("❌ Transaction not found.")
```

### BharatPe — Payment history

```python
from devport import bharatpe

history = bharatpe.payment_history(
    api_key="ilm_live_your_api_key_here",
    days=3,  # 1–7 days
)

print(f"Found {history.total} transactions in the last {history.lookback_days} days:")
for txn in history.transactions:
    print(f"  {txn.bank_reference_no}: ₹{txn.amount} — {txn.status}")
```

### Paytm — Verify an order

```python
from devport import paytm

result = paytm.order_status(
    api_key="ilm_live_your_api_key_here",
    order_id="ORDER_12345",
)

if result.verified:
    print(f"✅ Payment verified! Amount: ₹{result.transaction.txn_amount}")
    print(f"   Txn ID: {result.transaction.txn_id}")
    print(f"   Mode: {result.transaction.payment_mode}")
elif result.found:
    print(f"⏳ Order found but status is: {result.transaction.status}")
else:
    print("❌ Order not found on Paytm.")
```

### Using the client class (avoid repeating your API key)

```python
from devport import DevPort

client = DevPort(api_key="ilm_live_your_api_key_here")

# BharatPe
result = client.bharatpe.payment_status(transaction_id="432112345678")
history = client.bharatpe.payment_history(days=3)

# Paytm
order = client.paytm.order_status(order_id="ORDER_12345")
```

## Error Handling

All errors are mapped to specific exceptions. Switch on the `error.code` field, not HTTP status codes.

```python
from devport import bharatpe
from devport import (
    DevPortError,                # Base — catches all API errors
    AuthenticationError,         # Invalid/revoked/expired API key (401)
    RateLimitError,              # Too many requests (429) — has .retry_after
    CreditError,                 # No credits / subscription expired (402)
    ServiceNotConfiguredError,   # Service credentials not set in dashboard
    UpstreamError,               # Upstream service failure
    ValidationError,             # Invalid service / service disabled
    NetworkError,                # Can't reach the server
)

try:
    result = bharatpe.payment_status(
        api_key="ilm_live_...",
        transaction_id="432112345678",
    )
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError as e:
    print(f"Auth failed: {e.code} — {e.message}")
except CreditError:
    print("No credits remaining. Purchase a package.")
except ServiceNotConfiguredError:
    print("Configure your credentials in Dashboard → Service Config.")
except DevPortError as e:
    print(f"API error: {e}")
except NetworkError:
    print("Cannot reach DevPort API. Check your connection.")
```

### Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `INVALID_API_KEY` | 401 | API key is missing, malformed, or not found |
| `API_KEY_REVOKED` | 401 | API key has been revoked from the dashboard |
| `API_KEY_EXPIRED` | 401 | API key has passed its expiration date |
| `CLIENT_SUSPENDED` | 401 | Your account has been suspended |
| `IP_NOT_WHITELISTED` | 401 | Request IP not in the key's whitelist |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests — retry after the cooldown |
| `CREDITS_EXHAUSTED` | 402 | No remaining credits on any active subscription |
| `NO_ACTIVE_SUBSCRIPTION` | 402 | No active subscription found — purchase a package |
| `SUBSCRIPTION_EXPIRED` | 402 | All subscriptions have expired |
| `INVALID_SERVICE` | 404 | Service name not found in the registry |
| `SERVICE_DISABLED` | 503 | Service is temporarily disabled by admin |
| `BHARATPE_NOT_CONFIGURED` | 422 | BharatPe credentials not saved in dashboard |
| `PAYTM_NOT_CONFIGURED` | 422 | Paytm Merchant ID not saved in dashboard |
| `UPSTREAM_ERROR` | 502 | Upstream service returned an error |

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `api_key` | *(required)* | Your DevPort API key (`ilm_live_...`) |
| `timeout` | `30.0` | Request timeout in seconds |

## Response Types

All functions return typed dataclasses:

### BharatPe

- **`PaymentStatusResult`** — `.verified`, `.found`, `.message`, `.transaction`, `.meta`
- **`PaymentHistoryResult`** — `.transactions`, `.total`, `.lookback_days`, `.meta`
- **`BharatPeTransaction`** — `.transaction_id`, `.bank_reference_no`, `.amount`, `.status`, `.mode`, `.payer_vpa`, `.payer_name`, `.transaction_date`, `.extra`

### Paytm

- **`PaytmOrderStatusResult`** — `.verified`, `.found`, `.message`, `.transaction`, `.meta`
- **`PaytmTransaction`** — `.txn_id`, `.bank_txn_id`, `.order_id`, `.txn_amount`, `.status`, `.txn_type`, `.gateway_name`, `.resp_code`, `.resp_msg`, `.payment_mode`, `.txn_date`, `.extra`

### Common

- **`ResponseMeta`** — `.requests_remaining`, `.latency_ms`, `.timestamp`

## Credits & Billing

- Each successful API call deducts **1 credit** from your active subscription
- Buy credit packs from the [dashboard](https://devport.ilambit.in/dashboard) — no monthly subscriptions
- Track remaining credits via `result.meta.requests_remaining`

## Support

- 📧 Email: [ilambit.dev@gmail.com](mailto:ilambit.dev@gmail.com)
- 💬 WhatsApp: [+91 9514719019](https://wa.me/919514719019)
- 📚 Full docs: [devport.ilambit.in/docs](https://devport.ilambit.in/docs)

## Requirements

- Python 3.9+
- [httpx](https://www.python-httpx.org/) (installed automatically)

---

> © 2026 [Ilambit DevPort](https://devport.ilambit.in/). All rights reserved. Built by [Ilambit Technologies](https://www.ilambit.in/)
