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
pip install harbour-connect
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
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
# 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):
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)
@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
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(importharbour_connect), version 0.1.0. Below 1.0.0 a minor version may break things: pin withharbour-connect~=0.1.0and 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.