Python SDK
bitmomo is the official Python SDK. It needs Python 3.10 or later, has one dependency (httpx), includes type hints, and offers both a synchronous and an asynchronous client.
pip install bitmomoConfigure a client
Section titled “Configure a client”import osimport bitmomo
client = bitmomo.Client( api_key=os.environ["BITMOMO_API_KEY"], base_url="https://api.dev.bitmomo.app", timeout=10.0, # seconds)For asyncio applications, use bitmomo.AsyncClient with the same arguments and await every call:
async with bitmomo.AsyncClient(api_key=key, base_url="https://api.dev.bitmomo.app") as client: payment = await client.create_payment(amount="100.00", crypto_type="USDT_TRC20")base_urlis required. It must be anhttps://origin with no path, query, fragment or credentials. Plainhttp://is accepted only forlocalhost.- The client never follows redirects, so your key is never sent to another host.
- Both clients are context managers;
close()(oraclose()) releases the connection pool.
Create a payment
Section titled “Create a payment”payment = client.create_payment( amount="100.00", # Ghana cedis: a decimal string, int or Decimal, never a float crypto_type="USDT_TRC20", order_id="order_1001", idempotency_key=bitmomo.new_idempotency_key(), # store this with the order first)print(payment.id, payment.crypto_amount, payment.deposit_address, payment.qr_code_data)Methods
Section titled “Methods”| Method | Endpoint | Scope |
|---|---|---|
create_payment(amount=, crypto_type=, ...) |
POST /gateway/payments |
payments:write |
get_payment(payment_id) |
GET /gateway/payments/{id} |
payments:read |
list_payments(page=, limit=, status=) |
GET /gateway/payments |
payments:read |
get_balances() |
GET /gateway/balances |
payments:read |
request_payout(amount=, idempotency_key=, settlement_method=) |
POST /gateway/payouts |
payouts:write |
get_webhook_config() |
GET /gateway/webhooks/config |
webhooks:read |
update_webhook_config(url=, events=, is_active=) |
PUT /gateway/webhooks/config |
webhooks:write |
delete_webhook_config() |
DELETE /gateway/webhooks/config |
webhooks:write |
rotate_webhook_secret() |
POST /gateway/webhooks/config/rotate |
webhooks:write |
create_payment_link(name=, ...) |
POST /gateway/payment-links |
payments:write |
list_payment_links() |
GET /gateway/payment-links |
payments:read |
get_payment_link(link_id) |
GET /gateway/payment-links/{id} |
payments:read |
get_payment_status(payment_id) |
GET /payments/{id}/status |
none (public) |
get_rates() |
GET /rates |
none (public) |
Keyword arguments mirror the API’s field names. Responses are frozen dataclasses with the same field names (for example payment.order_terms.order_id).
request_payout requires an idempotency_key; create it with bitmomo.new_idempotency_key(), save it, and reuse it on retries. Without one, the SDK refuses to send the request.
Webhook helpers
Section titled “Webhook helpers”| Helper | Use |
|---|---|
bitmomo.webhooks.verify_event(raw_body, signature, secrets=, timestamp=, key_version=) |
Full verification: signature, freshness and signed headers. Returns a result that is truthy when valid, with .envelope or .reason. |
bitmomo.webhooks.verify_signature(raw_body, signature, secret) |
Signature check only. Prefer verify_event. |
bitmomo.webhooks.DeliveryDedupeCache(ttl_seconds=86400) |
In-memory, thread-safe duplicate filter: seen(delivery_id) returns True for a repeat. Use a database for anything that matters. |
from bitmomo import webhooks
result = webhooks.verify_event( raw_body, # bytes, exactly as received headers["X-Webhook-Signature"], secrets=[webhooks.WebhookSecret(version=1, secret=os.environ["BITMOMO_WEBHOOK_SECRET"])], timestamp=headers.get("X-Webhook-Timestamp"), key_version=headers.get("X-Webhook-Key-Version"),)if not result: ... # reply 400; result.reason is e.g. "bad-signature" or "stale-timestamp"Read the raw body before any JSON parsing: request.get_data() in Flask, await request.body() in FastAPI or Starlette, request.body in Django. See Webhooks for the full flow.
Errors and retries
Section titled “Errors and retries”Every failure raises bitmomo.BitmomoError with status, code, message, request_id and retriable. status is 0 when no response arrived (NETWORK_ERROR) or the response broke the contract (SCHEMA_ERROR). Reads retry up to 3 times in total on 429 and 5xx (max_retries=2 by default), honouring Retry-After up to 60 seconds. Writes are never retried automatically; see Errors.
Money values
Section titled “Money values”Money fields are decimal.Decimal. Print them with format(value, "f") to avoid scientific notation. Amounts you send may be a Decimal, an int or a decimal string; a float raises TypeError, because it cannot hold cents exactly. On balances, use the *_exact fields; the plain floats are for display only.
- Package: pypi.org/project/bitmomo
- SDK changelog