Skip to content
Test money only. BitMomo currently runs on test networks. Payments use testnet coins and no real money moves. Live keys are not available yet.

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.

Terminal window
pip install bitmomo
import os
import 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_url is required. It must be an https:// origin with no path, query, fragment or credentials. Plain http:// is accepted only for localhost.
  • The client never follows redirects, so your key is never sent to another host.
  • Both clients are context managers; close() (or aclose()) releases the connection pool.
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)
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.

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.

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 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.