Felloh Python SDK

Official Python SDK for the Felloh payment API.

Installation

pip install felloh

Quick Start

import asyncio
from felloh import FellohClient
from felloh.types import FellohConfig

client = FellohClient(FellohConfig(
    public_key="your_public_key",
    private_key="your_private_key",
))

async def main():
    # List bookings
    bookings = await client.bookings.list({"organisation": "org-id"})
    print(bookings["data"])

    # Create a booking
    booking = await client.bookings.create({
        "organisation": "org-id",
        "booking_reference": "REF-001",
        "customer_name": "Jane Smith",
        "email": "jane@example.com",
    })
    print(booking["data"]["id"])

    await client.close()

asyncio.run(main())

Context Manager

async with FellohClient(FellohConfig(
    public_key="your_public_key",
    private_key="your_private_key",
)) as client:
    bookings = await client.bookings.list({"organisation": "org-id"})

Pagination

Iterate through all results automatically:

from felloh import to_array

# Async iteration
async for booking in client.bookings.list_all({"organisation": "org-id"}):
    print(booking["id"])

# Or collect all into a list
all_bookings = await to_array(client.bookings.list_all({"organisation": "org-id"}))

Resources

Error Handling

from felloh import (
    FellohError,
    FellohAuthenticationError,
    FellohNotFoundError,
    FellohValidationError,
    FellohRateLimitError,
    FellohServerError,
    FellohNetworkError,
)

try:
    await client.bookings.get("nonexistent-id")
except FellohNotFoundError as e:
    print(f"Not found: {e}")
except FellohAuthenticationError:
    print("Invalid credentials")
except FellohError as e:
    print(f"API error {e.status_code}: {e}")

Webhook Verification

from felloh import verify_webhook_signature, assert_webhook_signature

# Returns True/False
is_valid = verify_webhook_signature(
    payload=request_body,
    signature=request.headers["X-Signature"],
    secret="your_webhook_secret",
)

# Or raise FellohWebhookSignatureError
assert_webhook_signature(
    payload=request_body,
    signature=request.headers["X-Signature"],
    secret="your_webhook_secret",
)

Configuration

FellohConfig(
    public_key="pk_...",
    private_key="sk_...",
    base_url="https://api.felloh.com",       # default
    timeout=30.0,                              # seconds, default
    max_retries=2,                             # default
    token_refresh_buffer=60,                   # seconds before expiry, default
    logger=lambda entry: print(entry),         # optional request logger
)

Development

pip install -e ".[dev]"
pytest                              # unit + resource tests
pytest -m integration               # integration tests (requires env vars)

Integration tests require:

• FELLOH_PUBLIC_KEY
• FELLOH_PRIVATE_KEY
• FELLOH_ORGANISATION_ID

License

MIT