Skip to main content
Official client libraries for the HOST Pay API. Both SDKs cover the full merchant API — users (including list/update/lifecycle), wallets, deposits, transfers, payouts, escrow, and transaction queries — plus webhook signature verification, typed responses, automatic retries, and idempotency support.

Python

hostpay on PyPI — Python 3.8+

TypeScript

@hostpay/sdk on npm — Node 18+, zero runtime dependencies
Source code for both lives at github.com/HOST-SL/hostpay-sdk.

​
Install

pip install hostpay

​
Initialize the client

Pass your credentials once — every call is authenticated automatically. Use Test Mode keys while integrating; the same code works in Live Mode. 
from hostpay import HostPay

client = HostPay(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
)
The SDKs use your secret-key, so they are server-side only. Never bundle them into browser or mobile code.

​
Async (Python)

The Python SDK also ships AsyncHostPay (v0.3.0+) — the same surface with every method awaited, for FastAPI, aiohttp, or any asyncio app. The TypeScript client is async by nature (every method returns a Promise).
Python
from hostpay import AsyncHostPay

async with AsyncHostPay(api_key="YOUR_API_KEY", secret_key="YOUR_SECRET_KEY") as client:
    user = await client.users.create(
        app_user_id="user_123", name="Alice", phone_number="+23279000000"
    )
    wallet = await client.wallets.create(user.id)

​
The money surface

# Users and wallets
user = client.users.create(
    app_user_id="user_1001",
    name="John Doe",
    phone_number="+23279123456",
    email="john@example.com",
)
wallet = client.wallets.create(user["id"])

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

# Balance, transfer, payout, escrow
balance = client.wallets.balance(wallet["id"])
client.transfers.create(
    sender_wallet_id=wallet["id"],
    recipient_identifier="johndoe",
    amount=25,
)
client.payouts.mobile_money(
    wallet_id=wallet["id"], amount=50, phone_number="+23279123456"
)
hold = client.escrow.hold(wallet_id=wallet["id"], amount=10)
client.escrow.release(hold["id"], recipient_wallet_id="RECIPIENT_WALLET_ID")

​
Idempotency

Money-moving calls accept an idempotency key. Reuse the same key to retry safely without double-charging: 
client.payouts.mobile_money(
    wallet_id=wallet_id,
    amount=50,
    phone_number="+23279123456",
    idempotency_key="order-42-payout",
)

​
Verifying webhooks

Both SDKs verify the X-HostPay-Signature header and reject replayed or tampered deliveries. Pass the raw request body, not a re-parsed object. See Webhook security for details. 
from fastapi import HTTPException, Request
from hostpay import SignatureVerificationError

@app.post("/webhooks/hostpay")
async def hook(request: Request):
    try:
        event = client.webhooks.construct_event(
            payload=await request.body(),   # raw bytes
            headers=request.headers,
            secret=WEBHOOK_SIGNING_SECRET,
        )
    except SignatureVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")
    if event.event == "deposit.completed":
        ...  # handle it
    return {"ok": True}

​
Error handling

Errors are typed by HTTP status so you can branch on the cause:
ErrorStatusMeaning
AuthenticationError401, 403Bad or missing credentials
InvalidRequestError400, 404, 422Validation failure, insufficient funds, missing resource
RateLimitError429Too many requests — back off and retry
APIError5xxServer-side problem
APIConnectionError—Network failure reaching the API
from hostpay import InvalidRequestError, RateLimitError

try:
    client.transfers.create(
        sender_wallet_id=wallet_id,
        recipient_identifier="johndoe",
        amount=25,
    )
except InvalidRequestError as e:
    print(f"Rejected ({e.status_code}): {e}")   # e.g. insufficient funds
except RateLimitError:
    ...  # back off and retry

​
Beyond payments

From hostpay 0.4.0 / @hostpay/sdk 0.3.0 the SDKs also cover:
  • Fees — client.fees: fee summary, configuration, and deposit / withdrawal / transfer / card-metadata estimates
  • Webhook subscriptions — client.webhooks.subscriptions: create, list, update, delete, and rotate-secret (the create and rotate responses include the signing secret once — store it)
  • Transaction sync — client.transactions.sync(reference_id) for instant post-payment status
  • Test-mode simulator — client.testing.simulate_monime_webhook(...) to complete or fail a pending Test Mode deposit (rejected in Live Mode)
  • app_info / appInfo — identify your platform in the User-Agent, e.g. HostPay(..., app_info="YourApp/1.0")
And from hostpay 0.5.0 / @hostpay/sdk 0.4.0:
  • Stripe Connect onboarding — client.connect: complete onboarding (requires the end customer’s IP for Stripe TOS acceptance), verification document upload, status sync, and deletion
  • Partial user update — client.users.patch(...): change only the fields you send

​
Other languages

Any language that speaks HTTP works — see the API reference for raw request examples, and Authentication for the required headers. The full OpenAPI spec is published in the SDK repository if you want to generate your own client.