securepay-api

A Python library for seamlessly integrating the SecurePay 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

pip install securepay-api

Quick Start

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

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

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

API Coverage

Development

# 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