Python SDK

The official Seev SDK for Python. Works with Django, Flask, FastAPI, and any Python environment.

This SDK is currently a work in progress. The API surface below reflects the planned interface and may change before the stable release. Follow the changelog for updates.

The Seev Python SDK (seev-python) wraps the Seev REST API with a clean, Pythonic interface. It supports both synchronous and async usage and works in any Python 3.8+ environment — Django, Flask, FastAPI, Celery workers, scripts, and more.

Installation

pip install seev-python
# or
poetry add seev-python

Initialise

Call seev.init() once at startup — in your app factory, settings.py, or top-level module — before making any API calls.

import seev

seev.init(
    public_key="pk_your_public_key",
    private_key="sk_your_secret_key",
)

Never expose your private_key in client-side code or commit it to version control. Use environment variables.

Create a charge

seev.charge() creates a checkout session and returns an object containing the URL to redirect your customer to.

charge = seev.charge(
    type="checkout",
    recipient={
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phone": "+233501234567",
    },
    amount=10000,  # smallest currency unit — 10000 = GHS 100.00
    currency="GHS",
    channels=["card", "mobile_money"],
    redirect_url="https://myapp.com/callback",
)

print(charge.id)           # checkout session ID
print(charge.checkout_url) # redirect your customer here

Charge from items

Pass items instead of amount to have Seev calculate the total:

charge = seev.charge(
    type="checkout",
    recipient={"name": "John Doe", "email": "john@example.com"},
    items=[
        {"name": "Product A", "price": 5000, "quantity": 2},
        {"name": "Product B", "price": 3000, "quantity": 1},
    ],
    currency="GHS",
    redirect_url="https://myapp.com/callback",
)

Charge object

Attribute	Type	Description
`charge.id`	`str`	Checkout session ID
`charge.checkout_url`	`str`	URL to redirect the customer to
`charge.status`	`str`	Initial session status
`charge.amount`	`int`	Resolved charge amount
`charge.currency`	`str`	Charge currency
`charge.get_response()`	`dict`	Full API response
`charge.get_raw(key)`	`Any`	Access any field from the raw response

Handle the callback

seev.callback() verifies the session after the customer returns from the checkout page.

# Django / Flask example
def callback(request):
    session_id = request.GET.get("session_id")  # or request.args.get for Flask

    session = seev.callback(session_id)

    if session.is_successful():
        print(f"Payment successful — session: {session.id}")
        return JsonResponse({"status": "success"})
    else:
        return JsonResponse({"status": session.status})

Callback object

Attribute / Method	Type	Description
`session.id`	`str`	Session ID
`session.status`	`str`	Payment status
`session.reference`	`str`	Transaction reference
`session.is_successful()`	`bool`	`True` if payment completed
`session.get_session()`	`dict`	Full session object

Handle webhooks

seev.webhook() parses incoming Seev webhook events. Always return 200 quickly and process asynchronously.

# FastAPI example
from fastapi import Request

@app.post("/webhooks/seev")
async def handle_webhook(request: Request):
    body = await request.json()

    event = seev.webhook(body)

    if event.is_type("checkout.completed"):
        data = event.get_data()
        print(f"Payment completed: {data['checkoutId']} {data['amount']} {data['currency']}")

    elif event.is_type("checkout.failed"):
        data = event.get_data()
        print(f"Payment failed: {data['checkoutId']} — {data.get('reason')}")

    elif event.is_type("refund.issued"):
        print(f"Refund issued: {event.get_data()}")

    else:
        print(f"Unhandled event: {event.type}")

    return {"received": True}

Webhook object

Attribute / Method	Description
`event.type`	Event type string, e.g. `"checkout.completed"`
`event.is_type(type)`	`True` if the event matches the given type
`event.get_data()`	Event payload as `dict`
`event.user`	Associated user (if passed as second arg to `webhook()`)
`event.get_raw_event()`	Full raw event object

Common webhook events:

Event	Description
`checkout.completed`	Payment succeeded
`checkout.failed`	Payment failed
`checkout.pending`	Payment is pending confirmation
`refund.issued`	A refund was issued
`invoice.created`	Invoice was created
`invoice.paid`	Invoice was paid

Fetch a transaction

seev.transaction() retrieves details about a specific transaction. Use this server-side to confirm payment status.

txn = seev.transaction("txn_abc123xyz")

print(f"Status: {txn.status} — Amount: {txn.amount} {txn.currency}")

Transaction object

Attribute	Type	Description
`txn.id`	`str`	Transaction ID
`txn.status`	`str`	`"completed"`, `"pending"`, `"failed"`
`txn.amount`	`int`	Transaction amount
`txn.currency`	`str`	Transaction currency
`txn.reference`	`str`	Optional reference

Async support

All SDK methods are available as coroutines when using await:

import seev

charge = await seev.charge(
    type="checkout",
    recipient={"name": "Jane Doe", "email": "jane@example.com"},
    amount=10000,
    currency="GHS",
    redirect_url="https://myapp.com/callback",
)

Error handling

from seev.exceptions import SeevError

try:
    charge = seev.charge(
        type="checkout",
        recipient={"name": "Jane Doe", "email": "jane@example.com"},
        amount=10000,
        currency="GHS",
        redirect_url="https://myapp.com/callback",
    )
except SeevError as e:
    print(f"SDK error [{e.code}]: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Common errors:

Error	Cause
`"Seev SDK not initialised. Call init() first."`	`init()` was not called before making a request
`"Failed to create checkout session: ..."`	Bad request data or invalid API keys
`"Failed to verify checkout session: session not found or invalid"`	Expired or invalid session ID
`"Invalid webhook payload: missing event type"`	Malformed webhook body
`"Network error: ..."`	Connectivity issue or unreachable endpoint

Full integration example

# Django views.py
import seev
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
import json

seev.init(
    public_key="pk_test_123",
    private_key="sk_test_456",
)


def create_checkout(request):
    charge = seev.charge(
        type="checkout",
        recipient={"name": "Jane Doe", "email": "jane@example.com"},
        items=[
            {"name": "Widget", "price": 2500, "quantity": 1},
        ],
        currency="GHS",
        redirect_url="https://myapp.com/callback",
    )
    return JsonResponse({"checkout_url": charge.checkout_url})


def handle_callback(request):
    session_id = request.GET.get("session_id")
    result = seev.callback(session_id)

    if result.is_successful():
        return JsonResponse({"status": "success", "session_id": result.id})
    return JsonResponse({"status": result.status})


@csrf_exempt
def handle_webhook(request):
    body = json.loads(request.body)
    event = seev.webhook(body)

    if event.is_type("checkout.completed"):
        print(f"Payment completed: {event.get_data()}")

    return JsonResponse({"received": True})


def get_transaction(request, txn_id):
    txn = seev.transaction(txn_id)
    return JsonResponse({
        "id": txn.id,
        "status": txn.status,
        "amount": txn.amount,
        "currency": txn.currency,
    })