Metadata-Version: 2.4
Name: mavunta
Version: 1.0.0
Summary: Official Python SDK for the Mavunta Pay API.
Project-URL: Homepage, https://developers.mavunta.com
Author: Chainwaka Technologies
License: MIT
Keywords: crypto,mavunta,mpesa,payment-gateway,payments,usdt
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# mavunta

Official Python SDK for the [Mavunta Pay API](https://developers.mavunta.com).
Standard library only (no dependencies), Python 3.8+.

```bash
pip install mavunta
```

## Quickstart

Create an intent, redirect the customer to its hosted checkout, and fulfil the
order on the signed `payment_intent.paid` webhook.

```python
import os
from mavunta import Mavunta

mavunta = Mavunta(api_key=os.environ["MAVUNTA_SECRET_KEY"])

intent = mavunta.payment_intents.create(
    amount="2500",
    currency="KES",
    settlement_currency="USDT",
    payment_methods=["mpesa", "card", "mavunta_balance"],
    merchant_reference="ORDER-1001",
)

# Redirect the customer to:
print(intent["checkout_url"])
```

A `cwk_test_…` key runs in sandbox (no real money); a `cwk_live_…` key is live.
Every create call sends an `Idempotency-Key` automatically, so an automatic
retry (on 429/5xx) never double-charges.

## Resources

```python
mavunta.auth.verify()
mavunta.rates.retrieve()
mavunta.quotes.create(source_currency="KES", target_asset="USDT", amount="2500")

mavunta.payment_intents.create(amount="2500", currency="KES", idempotency_key="order-1001")
mavunta.payment_intents.retrieve("pi_...")
mavunta.payment_intents.list(limit=20, status="paid")
mavunta.payment_intents.cancel("pi_...")
mavunta.payment_intents.refund_request("pi_...", reason="Customer returned item")

mavunta.payment_links.create(title="Deposit", amount="15000", currency="KES")
mavunta.payment_links.retrieve("pl_...")
```

## Verify webhooks

Pass the **raw** request body (str or bytes).

```python
event = mavunta.webhooks.verify(
    payload=raw_body,
    signature=headers["Mavunta-Signature"],
    timestamp=headers["Mavunta-Timestamp"],
    secret=os.environ["MAVUNTA_WEBHOOK_SECRET"],
)
if event["type"] == "payment_intent.paid":
    ...  # fulfil the order, dedupe on event["id"]
```

## Errors

```python
from mavunta import MavuntaError

try:
    mavunta.payment_intents.create(amount="0", currency="KES")
except MavuntaError as err:
    print(err.type, err.code, err, err.request_id)
```

The full contract is published as OpenAPI at <https://www.mavunta.com/openapi.yaml>.

## License

MIT
