Metadata-Version: 2.4
Name: securepay-api
Version: 0.0.3
Summary: A Python library for seamlessly integrating the SecurePay payment platform API.
Project-URL: Homepage, https://github.com/seniorman-dev/SecurePay-Python-Library.git
Project-URL: Documentation, https://docs.getsecurepay.ai
Project-URL: Repository, https://github.com/seniorman-dev/SecurePay-Python-Library.git
Project-URL: Bug Tracker, https://github.com/seniorman-dev/SecurePay-Python-Library/issues
Author-email: Japhet Ebelechukwu <japhetebelechukwu@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,direct-debit,fintech,nigeria,payments,securepay
Classifier: Development Status :: 3 - Alpha
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: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.3.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# securepay-api

A Python library for seamlessly integrating the [SecurePay](https://getsecurepay.ai) payment platform API.

Gives Python developers a clean, typed, fully documented interface - no need to read raw API docs or wire up HTTP calls manually.

---

## Features

- ✅ Fully typed with **Pydantic v2** models — request validation + IDE autocomplete
- ✅ `httpx`-powered HTTP with automatic auth header injection on every request
- ✅ UUID-based `X-Request-ID` tracing per request
- ✅ Automatic retry with **exponential back-off** via `tenacity`
- ✅ Structured logging (staging only, auto-disabled in production)
- ✅ `SecurePayException` hierarchy for clean, specific error handling
- ✅ Context manager support (`with SecurePayApi(...) as client:`)
- ✅ Staging and production environment presets

---

## Installation

```bash
pip install securepay-api
```

---

## Quick Start

```python
from securepay import SecurePayApi, SecurePayConfig

client = SecurePayApi(
    api_key="SP-PK-xxxx",
    config=SecurePayConfig.staging(enable_logging=True),  # Development
    # config=SecurePayConfig.production(),               # Production
)
```

---

## Direct Debit — Full Example

```python
from datetime import date
from securepay import (
    SecurePayApi, SecurePayConfig,
    BankAccount, CreateMandateRequest, DebitFrequency,
    InitiateDebitRequest, MandateStatus, UpdateMandateRequest,
)

client = SecurePayApi(api_key="SP-PK-xxxx", config=SecurePayConfig.staging())

# POST — Create a mandate
mandate = client.direct_debit.create_mandate(
    CreateMandateRequest(
        customer_name="Ada Obi",
        customer_email="ada@example.com",
        customer_phone="+2348012345678",
        bank_account=BankAccount(
            account_number="0123456789",
            bank_code="058",
            account_name="Ada Obi",
        ),
        amount=5000.00,
        frequency=DebitFrequency.MONTHLY,
        start_date=date(2025, 8, 1),
    )
)
print(mandate.mandate_id)  # mnd_abc123

# GET — Fetch mandate
fetched = client.direct_debit.get_mandate(mandate.mandate_id)

# GET — List mandates
mandates = client.direct_debit.list_mandates(page=1, page_size=20)

# PUT — Update mandate
updated = client.direct_debit.update_mandate(
    mandate.mandate_id,
    UpdateMandateRequest(amount=7500.00),
)

# PATCH — Suspend mandate
client.direct_debit.patch_mandate_status(
    mandate.mandate_id,
    status=MandateStatus.SUSPENDED,
    reason="Customer requested pause.",
)

# POST — Initiate a collection
collection = client.direct_debit.initiate_collection(
    mandate.mandate_id,
    InitiateDebitRequest(amount=5000.00, narration="August subscription"),
)

# DELETE — Cancel mandate
client.direct_debit.cancel_mandate(mandate.mandate_id)
```

---

## Error Handling

```python
from securepay import (
    SecurePayException,
    SecurePayUnauthorizedError,
    SecurePayValidationError,
    SecurePayNotFoundError,
    SecurePayNetworkError,
)

try:
    mandate = client.direct_debit.get_mandate("mnd_xyz")
except SecurePayUnauthorizedError:
    print("Invalid API key")
except SecurePayNotFoundError:
    print("Mandate not found")
except SecurePayValidationError as e:
    print(f"Bad request: {e.message}")
except SecurePayNetworkError:
    print("No internet connection")
except SecurePayException as e:
    print(f"Unexpected error: {e}")
```

---

## Configuration

| Option | Type | Default | Description |
|---|---|---|---|
| `base_url` | `str` | Staging URL | API base URL |
| `timeout` | `float` | `30.0` | Request timeout in seconds |
| `max_retries` | `int` | `3` | Max retry attempts |
| `enable_logging` | `bool` | `False` | Log requests/responses |
| `enable_retry` | `bool` | `True` | Auto-retry on transient errors |

---

## API Coverage

| Section | Status |
|---|---|
| Direct Debit | ✅ |
| Transfers | ✅ |
| Checkout | ✅ |
| Key Management | ✅ |

---

## Development

```bash
# Clone and set up
git clone https://github.com/seniorman-dev/SecurePay-Python-Library.git
cd securepay_python
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .
```

---

## License

MIT
