Metadata-Version: 2.4
Name: amatopay
Version: 0.1.0
Summary: Official Python client for the AmatoPay payment gateway API
Keywords: amatopay,payments,payment-gateway,burundi,mobile-money
Author: AmatoPay
Author-email: AmatoPay <ndiku6241@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Dist: ipython>=8.18.1
Requires-Dist: requests>=2.31
Requires-Python: >=3.9
Project-URL: Homepage, https://amatopay.bi
Project-URL: Documentation, https://amatopay.bi/developers/
Description-Content-Type: text/markdown

# amatopay

Official Python client for the [AmatoPay](https://amatopay.bi) payment gateway API — collect
mobile-money payments (alias push or QR), track payments and deliveries, and verify webhooks.

## Install

```bash
uv add amatopay
# or
pip install amatopay
```

## Quickstart

```python
import amatopay

client = amatopay.AmatoPay(api_key="sk_live_...")  # or set AMATOPAY_API_KEY

session = client.checkout.create_session(
    order_number="ORDER-1001",
    amount="100000.00",
    currency="BIF",
    payer_alias="+25779000000",
    return_url="https://merchant.bi/payment/result",
)
print(session["checkout_url"])  # send the payer here, or redirect them
```

`AmatoPay()` with no arguments reads `AMATOPAY_API_KEY` (and `AMATOPAY_BASE_URL`, if you're
pointed at a non-default environment) from the environment — handy for keeping secrets out of code.

## What's here

- **`client.ping()`** — confirm your API key works and check onboarding/activation status.
- **`client.checkout`** — verify a payer alias, create alias-push or QR payment sessions, poll a
  hosted checkout session's status.
- **`client.payments`** — list/retrieve payments, confirm delivery with a payer's secure code.
- **`client.fees`** — preview the fee for a given amount before creating a session.
- **`client.deliveries`** — track fulfillment (mark shipped/delivered) and buyer-protection claims.
- **`amatopay.webhooks`** — verify and parse signed webhook deliveries.

See [`examples/`](examples/) for runnable scripts, and the
[developer docs](https://amatopay.bi/developers/) for the full API reference.

## Handling errors

Every non-2xx response raises a typed exception, all subclasses of `amatopay.APIError`:

| Status | Exception |
| --- | --- |
| 400 | `ValidationError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionError` |
| 404 | `NotFoundError` |
| 429 | `RateLimitError` |
| 5xx | `ServerError` |

```python
try:
    client.checkout.create_session(...)
except amatopay.ValidationError as e:
    print(e.body)  # {"payer_alias": ["This alias is not payable."]}
except amatopay.PermissionError:
    print("Merchant not active yet, or missing a required capability.")
```

## Verifying webhooks

```python
import amatopay

@app.route("/webhooks/amatopay", methods=["POST"])
def amatopay_webhook():
    try:
        event = amatopay.webhooks.construct_event(
            request.get_data(),  # raw bytes — verify before parsing JSON yourself
            request.headers["AmatoPay-Signature"],
            endpoint_secret,  # your whsec_... for this endpoint
        )
    except amatopay.SignatureVerificationError:
        return "", 400

    if event["type"] == "payment.paid":
        ...
    return "", 200
```

## Development

This project uses [uv](https://docs.astral.sh/uv/).

```bash
uv sync              # install deps + dev tools into .venv
uv run pytest        # run the test suite
uv run ruff check .  # lint
uv build             # build the sdist + wheel into dist/
```

## License

MIT
