Reference

SDK reference: Python

Harbour Connect for Python: the client, the services, webhooks and errors.

Harbour Connect for Python uses only the standard library (urllib, hmac, json), supports Python 3.9 and newer, and is typed. The contract is the PHP SDK's: integer kobo, an idempotency key on every create, at most two safe retries, typed errors, and the same webhook check, tested against the same shared vectors.

Install

Terminal
pip install harbour-connect
Terminal
# until the package is on PyPI
pip install "harbour-connect @ git+https://github.com/Nordaxiz-Technology-Limited/nordaxiz-harbour-connect.git#subdirectory=python"

The source is in the python/ folder of the Harbour Connect repository, MIT licensed.

The client

Python
import os
from harbour_connect import Harbour

harbour = Harbour(
    os.environ["HARBOUR_SECRET_KEY"],
    webhook_secret=os.environ.get("HARBOUR_WEBHOOK_SECRET"),   # for harbour.webhooks
    api_base="https://api.harbour.africa",                     # HTTPS, except localhost
    timeout=30,                                                # seconds, 1 to 300
    max_retries=2,                                             # 0 to 2
    webhook_tolerance=300,                                     # seconds either side
)

harbour.mode           # "live" | "test", from the key
harbour.is_test_mode
harbour.masked_key     # hb_sk_live_****abcd, for logs and support tickets

Every argument is keyword-only, so a misspelt option is a TypeError at the call site. The key is kept behind a closure: repr(), vars() and logging show only the masked form, and the client refuses to be pickled. A public key (hb_pk_) is refused, with a pointer to harbour.js.

Services

Python
# charges
harbour.charges.create(amount_kobo=..., customer=..., reference=None, description=None,
                       return_url=None, provider=None, metadata=None, idempotency_key=None)
harbour.charges.verify("HB-88413")
harbour.charges.find_by_merchant_reference("order-1043")     # or None

# refunds: each one waits for an Owner's approval
harbour.refunds.create(reference="HB-88413", amount_kobo=2_500_000, reason="Two metres short")
harbour.refunds.retrieve("rf_…")

# payment links
harbour.payment_links.create(amount_kobo=1_500_000, description="Aso-ebi, 12 yards", expires_in_days=7)
harbour.payment_links.retrieve("pl_…")

# the ledger
page = harbour.transactions.list(status="succeeded", from_date=date(2026, 9, 1), limit=50)
page.data, page.next_cursor, page.has_more, page.next_page()
for txn in harbour.transactions.all(provider="paystack"):    # every page, lazily
    ...
harbour.transactions.retrieve("HB-88413")

Results are the API's own objects (API reference): dicts that also read as attributes, so checkout.checkout_url == checkout["checkout_url"]. Amounts must be an int of kobo; a float is refused before anything is sent. Money.to_kobo("120,000.50") converts a naira string. The client is synchronous: in async code, call it through asyncio.to_thread or run_in_threadpool.

Webhooks

Verify against the raw body. construct_event takes the body as bytes or str and either the header value or the request headers (Django, Flask and Starlette headers all work):

Python Django
from django.http import HttpResponse, HttpResponseBadRequest
from django.views.decorators.csrf import csrf_exempt
from harbour_connect import Event, SignatureVerificationError

@csrf_exempt                      # the signature check is the protection here
def harbour_webhook(request):
    try:
        event = harbour.webhooks.construct_event(request.body, request.headers)
    except SignatureVerificationError:
        return HttpResponseBadRequest()
    if event.type == Event.CHARGE_SUCCEEDED:
        fulfil(event.transaction())   # de-duplicate on event.id
    return HttpResponse(status=200)
Python FastAPI
@app.post("/webhooks/harbour")
async def harbour_webhook(request: Request):
    raw = await request.body()        # never request.json() before verifying
    try:
        event = harbour.webhooks.construct_event(raw, request.headers)
    except SignatureVerificationError:
        raise HTTPException(status_code=400)
    return {"received": True}

A Flask app is in the repository's python/examples. A failed check raises SignatureVerificationError with kind set to malformed, mismatch or tolerance; answer 400. See Webhooks for retries and de-duplication.

Errors and retries

Python
from harbour_connect import HarbourError, ValidationError, RateLimitError, ApiConnectionError

try:
    harbour.charges.create(amount_kobo=12_000_000, customer="funke@example.ng")
except ValidationError as e:
    print(e.fields)               # {"amount_kobo": "…"}
except RateLimitError as e:
    print(e.retry_after)          # seconds
except ApiConnectionError:
    pass                          # no answer: safe to retry with the same idempotency_key
except HarbourError as e:
    print(e.status, e.code, e.message)

Every error extends HarbourError with status and code: AuthenticationError (401), PermissionError (403, Harbour's own, not the built-in), NotFoundError (404), IdempotencyConflictError (409), ValidationError (422), RateLimitError (429), ApiConnectionError (no answer) and InvalidArgumentError (caught before sending, also a ValueError). Network errors, 429 and 5xx are retried at most twice with jittered backoff, only for GETs and creates that carry an idempotency key, which every create does. Redirects are never followed with your key attached.

Versioning

  • The package is harbour-connect (import harbour_connect), version 0.1.0. Below 1.0.0 a minor version may break things: pin with harbour-connect~=0.1.0 and read the changelog before moving.
  • The version travels as User-Agent: harbour-connect-python/<version>.
  • Every call goes to the API's /v1, whichever SDK version you run.