HostPay Python SDK

A small, typed client for the HostPay payments API — wallets, deposits, transfers, payouts, escrow, transaction queries, user/wallet lifecycle management, and webhook verification. Ships both a sync (HostPay) and an async (AsyncHostPay) client.

Install

pip install hostpay

Requires Python 3.8+ and httpx.

Quickstart

from hostpay import HostPay

client = HostPay(api_key="ak-...", secret_key="sk-...")
# Test Mode? use your test keys — same code, no real money moves.

# 1. Create a user and their wallet
user = client.users.create(
    app_user_id="user_123",
    name="Alice",
    phone_number="+23279000000",
    email="alice@example.com",
)
wallet = client.wallets.create(user.id)

# 2. Deposit via mobile money
deposit = client.deposits.mobile_money(wallet_id=wallet.id, amount=100)

# 3. Check the balance (attribute or dict access)
bal = client.wallets.balance(wallet.id)
print(bal.balance, bal["currency"])

# 4. Transfer, pay out, escrow
client.transfers.create(sender_wallet_id=wallet.id, recipient_identifier="bob", amount=20)
client.payouts.mobile_money(wallet_id=wallet.id, amount=5, phone_number="+23279000000")
hold = client.escrow.hold(wallet_id=wallet.id, amount=10)
client.escrow.release(hold.id, recipient_wallet_id="...")

Async

AsyncHostPay exposes the exact same surface — every method awaited, built on httpx.AsyncClient. Use it from FastAPI, aiohttp, or any asyncio app:

from hostpay import AsyncHostPay

async with AsyncHostPay(api_key="ak-...", secret_key="sk-...") as client:
    user = await client.users.create(
        app_user_id="user_123", name="Alice", phone_number="+23279000000"
    )
    wallet = await client.wallets.create(user.id)
    await client.deposits.mobile_money(wallet_id=wallet.id, amount=100)

Outside a context manager, call await client.aclose() when done. Webhook verification (client.webhooks.construct_event) is pure crypto with no I/O, so it stays a plain synchronous call on both clients.

Authentication

Pass your api-key and secret-key once at construction; they're sent on every request. base_url defaults to production — point it at your staging host for testing.

Idempotency

Money-moving calls accept idempotency_key — reuse the same key to safely retry without double-charging:

client.payouts.mobile_money(
    wallet_id=w, amount=5, phone_number="+232...", idempotency_key="order-42-payout"
)

Fees, subscriptions, sync & test helpers

client.fees — summary(), configuration(), estimate_deposit(), estimate_withdrawal(), estimate_transfer(), estimate_card_metadata()
client.webhooks.subscriptions — create(), list(), update(), delete(), rotate_secret(); the create/rotate response includes the signing secret once
client.transactions.sync(reference_id) — instant post-payment reconciliation
client.testing.simulate_monime_webhook(transaction_id, status=...) — complete or fail a pending Test Mode deposit (test keys only)
HostPay(..., app_info="YourApp/1.0") — identify your platform; appended to the User-Agent

All of these exist on AsyncHostPay too.

Verifying webhooks

Pass the raw request body and headers straight from your web framework:

from hostpay import HostPay, SignatureVerificationError

client = HostPay(api_key="ak-...", secret_key="sk-...")

# e.g. in Flask
@app.post("/webhooks/hostpay")
def hook():
    try:
        event = client.webhooks.construct_event(
            payload=request.get_data(),          # raw bytes, not request.json
            headers=request.headers,
            secret=WEBHOOK_SIGNING_SECRET,
        )
    except SignatureVerificationError:
        return "", 400
    if event.event == "deposit.completed":
        ...
    return "", 200

Signatures are HMAC-SHA256 over "<timestamp>.<body>"; deliveries older than tolerance seconds (default 300) are rejected.

Errors

All errors derive from HostPayError and carry .status_code and .detail: AuthenticationError (401/403), InvalidRequestError (400/404/422), RateLimitError (429), APIError (5xx), APIConnectionError, SignatureVerificationError.

Sandbox testing

In Test Mode, a user's phone number drives deterministic outcomes (see the Testing guide): +23299000001 completes, +23299000002 fails, +23299000009 stays pending. The same fail number works for payout recipients.

Typed responses

Core methods are annotated with TypedDict models (hostpay.models): users.* return UserRead, wallets.create/get return WalletRead, transfers/ payouts return TransactionResponse, and escrow.* returns EscrowResponse. A type checker (mypy/Pyright) will autocomplete and check keyed access — user["id"], wallet["balance"]. Ad-hoc responses (wallet balance, the deposit envelope) stay loosely typed.

At runtime every response is a HostPayObject (a dict), so both resp["field"] and resp.field work regardless of typing. The model fields mirror the committed ../openapi.json, the source of truth for both SDKs — regenerate the spec with python wallet-system/scripts/dump_openapi.py.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hostpay-0.4.0.tar.gz (14.0 kB view details)

Uploaded Jul 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hostpay-0.4.0-py3-none-any.whl (16.0 kB view details)

Uploaded Jul 4, 2026 Python 3

File details

Details for the file hostpay-0.4.0.tar.gz.

File metadata

Download URL: hostpay-0.4.0.tar.gz
Upload date: Jul 4, 2026
Size: 14.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for hostpay-0.4.0.tar.gz
Algorithm	Hash digest
SHA256	`ccc622879833654b07ffdb8c17b2cc9fd019f41a289ca407cd59990f24fcfe49`
MD5	`d7f9d7ab0662b7619608b2189be60375`
BLAKE2b-256	`f28f7f1967f0e93f78613a704f6f93e1c3637ace88e032562f431e636638908d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hostpay-0.4.0.tar.gz:

Publisher: publish-python.yml on HOST-SL/hostpay-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hostpay-0.4.0.tar.gz
- Subject digest: ccc622879833654b07ffdb8c17b2cc9fd019f41a289ca407cd59990f24fcfe49
- Sigstore transparency entry: 2073198492
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: HOST-SL/hostpay-sdk@1d60f3c50a2f87385beed698c24339ba0fd37143
- Branch / Tag: refs/tags/python-v0.4.0
- Owner: https://github.com/HOST-SL
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@1d60f3c50a2f87385beed698c24339ba0fd37143
- Trigger Event: push