Metadata-Version: 2.4
Name: mtnmomo-py
Version: 0.1.0
Summary: Typed synchronous client for the MTN MoMo APIs
Project-URL: Homepage, https://github.com/robin-001/mtnmomo-py
Project-URL: Repository, https://github.com/robin-001/mtnmomo-py.git
Project-URL: Issues, https://github.com/robin-001/mtnmomo-py/issues
Author: Robin
License: MIT
License-File: LICENSE
Keywords: api-client,mobile-money,momo,mtn,payments
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: build<2,>=1.2; extra == 'test'
Requires-Dist: pytest<9,>=8; extra == 'test'
Requires-Dist: respx<1,>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# mtnmomo-py

`mtnmomo-py` is a synchronous Python 3.10+ client for the MTN MoMo Collection, Disbursement, OAuth/CIBA, and Sandbox Provisioning APIs.

## Install

```bash
pip install mtnmomo-py
```

## Configure

Supply credentials explicitly or through environment variables. Do not commit API keys, subscription keys, or `credentials.json`.

```python
from mtnmomo import MoMoClient, MoMoConfig, ProductCredentials

config = MoMoConfig(
    collection=ProductCredentials(
        subscription_key="collection-subscription-key",
        api_user="collection-api-user",
        api_key="collection-api-key",
    ),
    disbursement=ProductCredentials(
        subscription_key="disbursement-subscription-key",
        api_user="disbursement-api-user",
        api_key="disbursement-api-key",
    ),
    target_environment="sandbox",
)

with MoMoClient(config) as client:
    balance = client.collection.get_account_balance()
    print(balance.available_balance, balance.currency)
```

`MoMoConfig.from_env()` reads:

- `MTN_MOMO_COLLECTION_SUBSCRIPTION_KEY`
- `MTN_MOMO_COLLECTION_API_USER`
- `MTN_MOMO_COLLECTION_API_KEY`
- `MTN_MOMO_DISBURSEMENT_SUBSCRIPTION_KEY`
- `MTN_MOMO_DISBURSEMENT_API_USER`
- `MTN_MOMO_DISBURSEMENT_API_KEY`
- `MTN_MOMO_TARGET_ENVIRONMENT` (defaults to `sandbox`)
- `MTN_MOMO_BASE_URL` (defaults to the MTN sandbox URL)
- `MTN_MOMO_TIMEOUT` (defaults to `30` seconds)

## Collection example

```python
from mtnmomo import Party

reference_id = client.collection.request_to_pay(
    {
        "amount": "100",
        "currency": "EUR",
        "externalId": "order-123",
        "payer": Party("MSISDN", "46733123453"),
        "payerMessage": "Order 123",
        "payeeNote": "Order 123",
    },
    callback_url="https://merchant.example/momo/callback",
)
status = client.collection.get_request_to_pay_status(reference_id)
```

## Disbursement example

```python
reference_id = client.disbursement.transfer(
    {
        "amount": "100",
        "currency": "EUR",
        "externalId": "payout-123",
        "payee": Party("MSISDN", "46733123453"),
    },
    callback_url="https://merchant.example/momo/callback",
)
```

## Testing

```bash
pip install -e .[test]
pytest
```

Tests are network-free by default. Safe sandbox token tests require explicit environment configuration and opt-in:

```bash
MTN_MOMO_RUN_INTEGRATION=1 pytest -m integration
```

State-changing sandbox operations remain mocked by default.

## Publishing

Build artifacts with `python -m build`; inspect them to confirm secrets are absent. Publish using a user-managed PyPI token or Trusted Publishing after testing the release on TestPyPI.
