Metadata-Version: 2.5
Name: bitmomo
Version: 0.1.0
Summary: BitMomo merchant SDK: accept crypto payments and verify webhooks in Python
Project-URL: Homepage, https://docs.bitmomo.app
Project-URL: Documentation, https://docs.bitmomo.app
Author: BitMomo
License-Expression: MIT
License-File: LICENSE
Keywords: bitmomo,cedi,crypto,ghana,payments,stablecoin,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# BitMomo Python SDK

Accept crypto payments in your Python application and verify BitMomo webhooks.
Sync and async clients, exact `Decimal` money, and one dependency (`httpx`).

> **Test money only.** BitMomo currently runs on test networks. Live API keys
> are disabled, so nothing you do with this SDK moves real money.

Guides and the API reference: https://docs.bitmomo.app

## Install

```bash
pip install bitmomo
```

Python 3.10 or newer.

## Create a payment

```python
import bitmomo

client = bitmomo.Client(
    api_key=os.environ["BITMOMO_API_KEY"],
    base_url="https://api.dev.bitmomo.app",
)

payment = client.create_payment(
    amount="150.00",                 # GHS, as a string, int or Decimal; never a float
    crypto_type="USDT_TRC20",
    order_id="order-1001",
    idempotency_key="order-1001",    # reuse the same key if you retry
)
print(payment.deposit_address, payment.crypto_amount, payment.qr_code_data)
```

Show the customer `qr_code_data` (or `deposit_address` and `crypto_amount`).
Then wait for the webhook, or poll:

```python
status = client.get_payment_status(payment.id)   # "pending", "confirmed", "completed", ...
detail = client.get_payment(payment.id)           # economics, payout state, order terms
```

### Async

```python
async with bitmomo.AsyncClient(api_key=key, base_url="https://api.dev.bitmomo.app") as client:
    payment = await client.create_payment(amount="150.00", crypto_type="USDT_TRC20")
```

## Verify webhooks

Verify the **raw** request body, before parsing it. Keep both secrets during
the 24 hours after you rotate.

```python
from bitmomo import webhooks

dedupe = webhooks.DeliveryDedupeCache()

def handle(request):
    result = webhooks.verify_event(
        request.body,                                   # bytes, exactly as received
        request.headers["X-Webhook-Signature"],
        secrets=[webhooks.WebhookSecret(version=1, secret=WEBHOOK_SECRET)],
        timestamp=request.headers.get("X-Webhook-Timestamp"),
        key_version=request.headers.get("X-Webhook-Key-Version"),
    )
    if not result:
        return 400                                      # result.reason says why
    if dedupe.seen(result.envelope.delivery_id):
        return 200                                      # already handled
    event = json.loads(request.body)
    ...
    return 200
```

Deliveries arrive at least once. The in-memory cache is enough for one
process; store processed `delivery_id`s durably if a duplicate would cause a
second effect (shipping twice, crediting twice).

## Everything the client can do

| Method | API |
|---|---|
| `create_payment(...)` | `POST /api/v1/gateway/payments` |
| `get_payment(payment_id)` | `GET /api/v1/gateway/payments/{id}` |
| `get_payment_status(payment_id)` | `GET /api/v1/payments/{id}/status` |
| `list_payments(page=, limit=, status=)` | `GET /api/v1/gateway/payments` |
| `request_payout(amount=, idempotency_key=, settlement_method=)` | `POST /api/v1/gateway/payouts` |
| `get_rates()` | `GET /api/v1/rates` |
| `get_balances()` | `GET /api/v1/gateway/balances` |
| `get_webhook_config()` | `GET /api/v1/gateway/webhooks/config` |
| `update_webhook_config(url=, events=, is_active=)` | `PUT /api/v1/gateway/webhooks/config` |
| `rotate_webhook_secret()` | `POST /api/v1/gateway/webhooks/config/rotate` |
| `delete_webhook_config()` | `DELETE /api/v1/gateway/webhooks/config` |
| `create_payment_link(name=, ...)` | `POST /api/v1/gateway/payment-links` |
| `list_payment_links()` | `GET /api/v1/gateway/payment-links` |
| `get_payment_link(link_id)` | `GET /api/v1/gateway/payment-links/{id}` |

Each API key carries scopes. A key without the right scope gets a
`BitmomoError` with status 403.

## 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 automatically on 429 and 5xx, twice by default (`max_retries=`),
  honouring `Retry-After` up to 60 seconds.
- Writes are never retried for you. Retry them yourself with the same
  idempotency key; `request_payout` refuses to send without one.
- Redirects are refused, so your API key is never sent to another host.
- `base_url` must be an HTTPS origin (plain HTTP only for localhost).

## Money

Money fields are `decimal.Decimal`. Use `format(value, "f")` to print them
without scientific notation. Amounts you send may be `Decimal`, `int` or a
decimal string; floats are refused because they cannot hold cents exactly.

## License

MIT
