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"
)
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hostpay-0.3.1.tar.gz.
File metadata
- Download URL: hostpay-0.3.1.tar.gz
- Upload date:
- Size: 12.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f68019887a3e8deece36f77c6d22eeb08d3338b7c824d37020d464b8779d2218
|
|
| MD5 |
3f3c39dca38765e43a724e6e7d9ff42b
|
|
| BLAKE2b-256 |
021edef2e5bcf500ec43caef5f2fcd940eab6c3fa1b09ded292e6db5980521e8
|
Provenance
The following attestation bundles were made for hostpay-0.3.1.tar.gz:
Publisher:
publish-python.yml on HOST-SL/hostpay-sdk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hostpay-0.3.1.tar.gz -
Subject digest:
f68019887a3e8deece36f77c6d22eeb08d3338b7c824d37020d464b8779d2218 - Sigstore transparency entry: 2073055277
- Sigstore integration time:
-
Permalink:
HOST-SL/hostpay-sdk@eb4ffd51910dbb59250450317a9370d17ba7b48d -
Branch / Tag:
refs/tags/python-v0.3.1 - Owner: https://github.com/HOST-SL
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-python.yml@eb4ffd51910dbb59250450317a9370d17ba7b48d -
Trigger Event:
push
-
Statement type:
File details
Details for the file hostpay-0.3.1-py3-none-any.whl.
File metadata
- Download URL: hostpay-0.3.1-py3-none-any.whl
- Upload date:
- Size: 13.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e03ac26b60ae65cb088a6c9c39b6f475aee5293d40fcb723ac39a38f0dd8ad04
|
|
| MD5 |
5d2949b9e7d345fb518ebe983c5bef38
|
|
| BLAKE2b-256 |
cd0006c54eb97f1d166d752a9eb49a0f0c1e009487e8dd9d3abd3bcf3f65df81
|
Provenance
The following attestation bundles were made for hostpay-0.3.1-py3-none-any.whl:
Publisher:
publish-python.yml on HOST-SL/hostpay-sdk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hostpay-0.3.1-py3-none-any.whl -
Subject digest:
e03ac26b60ae65cb088a6c9c39b6f475aee5293d40fcb723ac39a38f0dd8ad04 - Sigstore transparency entry: 2073055336
- Sigstore integration time:
-
Permalink:
HOST-SL/hostpay-sdk@eb4ffd51910dbb59250450317a9370d17ba7b48d -
Branch / Tag:
refs/tags/python-v0.3.1 - Owner: https://github.com/HOST-SL
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-python.yml@eb4ffd51910dbb59250450317a9370d17ba7b48d -
Trigger Event:
push
-
Statement type:
