py-momo-sdk 1.0.6__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- py_momo_sdk-1.0.6/.gitignore +74 -0
- py_momo_sdk-1.0.6/CHANGELOG.md +64 -0
- py_momo_sdk-1.0.6/CONTRIBUTING.md +57 -0
- py_momo_sdk-1.0.6/LICENSE +21 -0
- py_momo_sdk-1.0.6/PKG-INFO +216 -0
- py_momo_sdk-1.0.6/README.md +177 -0
- py_momo_sdk-1.0.6/SECURITY.md +21 -0
- py_momo_sdk-1.0.6/py_momo_sdk/__init__.py +81 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/__init__.py +1 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/client.py +134 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/http.py +134 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/products/__init__.py +1 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/products/base.py +209 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/products/collection.py +293 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/products/disbursement.py +237 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/products/remittance.py +89 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_async/sandbox.py +145 -0
- py_momo_sdk-1.0.6/py_momo_sdk/_cli.py +454 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/__init__.py +6 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/auth.py +156 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/client.py +196 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/config.py +53 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/models.py +180 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/products/collection.py +83 -0
- py_momo_sdk-1.0.6/py_momo_sdk/airtel/products/disbursement.py +89 -0
- py_momo_sdk-1.0.6/py_momo_sdk/auth.py +67 -0
- py_momo_sdk-1.0.6/py_momo_sdk/client.py +141 -0
- py_momo_sdk-1.0.6/py_momo_sdk/config.py +128 -0
- py_momo_sdk-1.0.6/py_momo_sdk/exceptions.py +52 -0
- py_momo_sdk-1.0.6/py_momo_sdk/http.py +169 -0
- py_momo_sdk-1.0.6/py_momo_sdk/models.py +322 -0
- py_momo_sdk-1.0.6/py_momo_sdk/products/__init__.py +1 -0
- py_momo_sdk-1.0.6/py_momo_sdk/products/base.py +203 -0
- py_momo_sdk-1.0.6/py_momo_sdk/products/collection.py +293 -0
- py_momo_sdk-1.0.6/py_momo_sdk/products/disbursement.py +237 -0
- py_momo_sdk-1.0.6/py_momo_sdk/products/remittance.py +89 -0
- py_momo_sdk-1.0.6/py_momo_sdk/py.typed +0 -0
- py_momo_sdk-1.0.6/py_momo_sdk/sandbox.py +142 -0
- py_momo_sdk-1.0.6/py_momo_sdk/utils.py +387 -0
- py_momo_sdk-1.0.6/py_momo_sdk/webhooks.py +144 -0
- py_momo_sdk-1.0.6/pyproject.toml +92 -0
- py_momo_sdk-1.0.6/tests/conftest.py +71 -0
- py_momo_sdk-1.0.6/tests/integration/test_airtel_client.py +656 -0
- py_momo_sdk-1.0.6/tests/integration/test_collection.py +676 -0
- py_momo_sdk-1.0.6/tests/integration/test_disbursement.py +341 -0
- py_momo_sdk-1.0.6/tests/integration/test_remittance.py +195 -0
- py_momo_sdk-1.0.6/tests/integration/test_sandbox.py +214 -0
- py_momo_sdk-1.0.6/tests/unit/test_airtel_auth.py +220 -0
- py_momo_sdk-1.0.6/tests/unit/test_auth.py +82 -0
- py_momo_sdk-1.0.6/tests/unit/test_cli.py +387 -0
- py_momo_sdk-1.0.6/tests/unit/test_config.py +122 -0
- py_momo_sdk-1.0.6/tests/unit/test_exceptions.py +38 -0
- py_momo_sdk-1.0.6/tests/unit/test_http.py +314 -0
- py_momo_sdk-1.0.6/tests/unit/test_models.py +142 -0
- py_momo_sdk-1.0.6/tests/unit/test_utils.py +127 -0
- py_momo_sdk-1.0.6/tests/unit/test_webhooks.py +118 -0
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
build/
|
|
11
|
+
develop-eggs/
|
|
12
|
+
dist/
|
|
13
|
+
downloads/
|
|
14
|
+
eggs/
|
|
15
|
+
.eggs/
|
|
16
|
+
lib/
|
|
17
|
+
lib64/
|
|
18
|
+
parts/
|
|
19
|
+
sdist/
|
|
20
|
+
var/
|
|
21
|
+
wheels/
|
|
22
|
+
share/python-wheels/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.installed.cfg
|
|
25
|
+
*.egg
|
|
26
|
+
MANIFEST
|
|
27
|
+
|
|
28
|
+
# Pyinstaller
|
|
29
|
+
*.manifest
|
|
30
|
+
*.spec
|
|
31
|
+
|
|
32
|
+
# Installer logs
|
|
33
|
+
pip-log.txt
|
|
34
|
+
pip-delete-this-directory.txt
|
|
35
|
+
|
|
36
|
+
# Unit test / coverage reports
|
|
37
|
+
htmlcov/
|
|
38
|
+
.tox/
|
|
39
|
+
.nosenv/
|
|
40
|
+
.pytest_cache/
|
|
41
|
+
.mypy_cache/
|
|
42
|
+
.ruff_cache/
|
|
43
|
+
.hypothesis/
|
|
44
|
+
.poetry/
|
|
45
|
+
.pdm/
|
|
46
|
+
poetry.lock
|
|
47
|
+
pdm.lock
|
|
48
|
+
.env
|
|
49
|
+
.venv
|
|
50
|
+
venv/
|
|
51
|
+
ENV/
|
|
52
|
+
env/
|
|
53
|
+
.coverage
|
|
54
|
+
.coverage.*
|
|
55
|
+
coverage.xml
|
|
56
|
+
*.cover
|
|
57
|
+
*.gcov
|
|
58
|
+
.pyre/
|
|
59
|
+
.pytype/
|
|
60
|
+
|
|
61
|
+
# Environments
|
|
62
|
+
.env
|
|
63
|
+
.venv
|
|
64
|
+
venv/
|
|
65
|
+
ENV/
|
|
66
|
+
env/
|
|
67
|
+
/site
|
|
68
|
+
|
|
69
|
+
# IDEs
|
|
70
|
+
.idea/
|
|
71
|
+
.vscode/
|
|
72
|
+
*.swp
|
|
73
|
+
*.swo
|
|
74
|
+
.DS_Store
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to the Py MoMo SDK (`py-momo-sdk`) project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## 1.0.6 - 2026-11-20
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
- Renamed the brand, PyPI distribution, Python package, classes, CLI command, and environment variables from `Py MoMo API` / `py-momo-api` / `py_momo_api` / `PyMomoAPI` to **Py MoMo SDK** (`py-momo-sdk`, `py_momo_sdk`, `PyMomoSDK`, `AsyncPyMomoSDK`, `PyMomoSDKConfig`, `PyMomoSDKError`, `PyMomoSDKServerError`, CLI `py-momo-sdk`, and `PY_MOMO_SDK_*`).
|
|
9
|
+
- Updated documentation, tests, and GitHub Pages site links to reflect `Py MoMo SDK` and `https://wkambale.github.io/pymomo/`.
|
|
10
|
+
|
|
11
|
+
## 1.0.5 - 2026-11-20
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
- Redesigned the MkDocs documentation site with semantic CSS design tokens, variable `Inter` and `JetBrains Mono` typography (`cv11`, `ss01`, `text-wrap: balance`, `text-wrap: pretty`, `tabular-nums`), alternating surface bands, horizontally aligned card grids, SVG brand geometry, and an accessible icon-only scroll-to-top control.
|
|
15
|
+
- Refined `README.md` and all documentation pages for strict editorial hygiene: sentence case throughout, zero ampersands in prose, zero em or en dashes, zero numbered headings or cards, and clear next-action navigation links.
|
|
16
|
+
|
|
17
|
+
## 1.0.4 - 2026-11-20
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
- Rebranded the project to **Py MoMo SDK** (`py-momo-sdk` on PyPI, importable package `py_momo_sdk`, CLI command `py-momo-sdk`, and `PY_MOMO_SDK_*` environment variables).
|
|
21
|
+
- Renamed core client, config, and exception classes to `PyMomoSDK`, `AsyncPyMomoSDK`, `PyMomoSDKConfig`, `PyMomoSDKError`, and `PyMomoSDKServerError`.
|
|
22
|
+
- Switched project license to MIT License (Copyright (c) 2026 Wesley Kambale) across `LICENSE`, `pyproject.toml`, and `README.md`.
|
|
23
|
+
- Updated all documentation, CLI help text, tests, and CI workflows to match `py_momo_sdk`, `py-momo-sdk`, and `PyMomoSDK`.
|
|
24
|
+
|
|
25
|
+
## 1.0.3 - 2026-11-20
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
- Aligned package license metadata in `pyproject.toml` and `README.md`.
|
|
29
|
+
- Updated package metadata, README, and documentation for `py-momo-sdk` 1.0.3 and Airtel Money coverage.
|
|
30
|
+
- Updated `SECURITY.md` supported versions to `1.0.x`.
|
|
31
|
+
- Cleaned up trailing whitespace, missing EOF newlines, and non-UUID `api_user` example placeholders across documentation.
|
|
32
|
+
|
|
33
|
+
## 1.0.2 - 2026-11-20
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
- Collection CIBA OAuth2 token exchange (`Collection.create_oauth2_token` in sync and async clients) with secret-redacting `OAuth2TokenResponse`.
|
|
37
|
+
- Webhook authenticity verification helpers: constant-time `WebhookHandler.verify_hmac_signature` (SHA-256 and SHA-512) and fail-closed `WebhookHandler.verify_source_ip`.
|
|
38
|
+
- Public sandbox provisioner factories `create_sandbox_provisioner(subscription_key)` on sync and async clients.
|
|
39
|
+
- CLI `--version` / `-V` flag, `collection status <reference_id>` command, and `--base-url` option across commands.
|
|
40
|
+
- Dedicated Airtel Money documentation (`docs/airtel.md`) and PEP 561 `py.typed` marker.
|
|
41
|
+
|
|
42
|
+
### Changed
|
|
43
|
+
- Enforced strict HTTPS base URL and relative request path validation, disabled automatic HTTP redirects (`follow_redirects=False`), and validated canonical UUID v4 reference IDs, ISO currency/country codes, positive finite amounts, timeouts, callback URLs, and header control characters.
|
|
44
|
+
- Hardened response JSON and Pydantic model parsing across all MTN MoMo and Airtel endpoints via shared `parse_model` and `parse_json_dict` helpers.
|
|
45
|
+
- Added thread-safe and async-safe double-checked token refresh locking with conditional cache invalidation (`expected_token`) to prevent concurrent token storms and stale invalidations.
|
|
46
|
+
- Hardened secret redaction across configs, models, token caches, sandbox provisioners, HTTP error chains, and CLI error handling.
|
|
47
|
+
- Hardened GitHub Actions workflows with SHA-pinned actions, least-privilege permissions, strict Hatch sdist/wheel packaging allowlists, and full Bandit scanning without global rule skips.
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
- Fixed `AirtelTransactionResponse.is_successful()`, `is_pending()`, and `is_failed()` to evaluate `data.transaction.status` rather than outer envelope result codes, and fixed the Airtel disbursement status endpoint path (`/standard/v1/disbursements/{id}`).
|
|
51
|
+
- Fixed Python 3.11+ enum string interpolation for `AccountHolderIdType` path segments.
|
|
52
|
+
- Fixed MkDocs root configuration and updated documentation examples to use valid UUID v4 values and public APIs.
|
|
53
|
+
|
|
54
|
+
## 0.1.0 - 2026-06-15
|
|
55
|
+
|
|
56
|
+
### Added
|
|
57
|
+
- First public release of the client library.
|
|
58
|
+
- Complete Collection product client (request to pay, request to withdraw, balances, consent queries).
|
|
59
|
+
- Complete Disbursement product client (transfers, deposits, refunds, balances).
|
|
60
|
+
- Complete Remittance product client (transfers, balances).
|
|
61
|
+
- Standard and asynchronous client implementations.
|
|
62
|
+
- Sandbox API user and API key provisioning helpers.
|
|
63
|
+
- Typer-based command-line interface tool.
|
|
64
|
+
- Webhook JSON payload parse utilities.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Contributions are welcome. Follow these guidelines to set up your environment, follow code styling standards, and write tests.
|
|
4
|
+
|
|
5
|
+
## Development setup
|
|
6
|
+
|
|
7
|
+
Clone the repository and install the development dependencies:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
git clone https://github.com/wkambale/pymomo.git
|
|
11
|
+
cd pymomo
|
|
12
|
+
pip install -e ".[dev]"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Styling rules
|
|
16
|
+
|
|
17
|
+
We enforce strict formatting rules to maintain codebase quality:
|
|
18
|
+
- Formatting: Black with a line limit of 88.
|
|
19
|
+
- Import ordering: Isort configured with the Black profile.
|
|
20
|
+
- Linters: Ruff default ruleset.
|
|
21
|
+
- Security: Bandit scans must report zero high-severity findings.
|
|
22
|
+
|
|
23
|
+
### Formatting commands
|
|
24
|
+
|
|
25
|
+
Verify your format and style before submitting a pull request:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
ruff check .
|
|
29
|
+
black --check .
|
|
30
|
+
isort --check .
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Type safety
|
|
34
|
+
|
|
35
|
+
The library is strictly typed. Run mypy to ensure there are no errors:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
mypy py_momo_sdk/
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Writing and running tests
|
|
42
|
+
|
|
43
|
+
All new methods and error handlers must be verified by unit tests under `tests/`.
|
|
44
|
+
|
|
45
|
+
### Intercepting external requests
|
|
46
|
+
|
|
47
|
+
No tests should make live connection requests to MTN or Airtel servers. Use `pytest-httpx` to register mock responses.
|
|
48
|
+
|
|
49
|
+
### Running the test suite
|
|
50
|
+
|
|
51
|
+
Run the test suite and verify test coverage using:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pytest --cov=py_momo_sdk --cov-report=term-missing
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The coverage threshold is **90%** minimum.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Wesley Kambale
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: py-momo-sdk
|
|
3
|
+
Version: 1.0.6
|
|
4
|
+
Summary: Py MoMo SDK: Python client for the MTN Mobile Money (MoMo) and Airtel Money APIs
|
|
5
|
+
Project-URL: Homepage, https://wkambale.github.io/pymomo/
|
|
6
|
+
Project-URL: Repository, https://github.com/wkambale/pymomo
|
|
7
|
+
Project-URL: Documentation, https://wkambale.github.io/pymomo/
|
|
8
|
+
Project-URL: Changelog, https://github.com/wkambale/pymomo/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Wesley Kambale
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: africa,airtel,fintech,mobile money,momo,mtn,payments
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: httpx<1,>=0.28.1
|
|
24
|
+
Requires-Dist: pydantic<3,>=2.0
|
|
25
|
+
Requires-Dist: typer<1,>=0.12
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: bandit>=1.7; extra == 'dev'
|
|
28
|
+
Requires-Dist: black>=26.10.1; extra == 'dev'
|
|
29
|
+
Requires-Dist: build<2,>=1.2; extra == 'dev'
|
|
30
|
+
Requires-Dist: isort>=5; extra == 'dev'
|
|
31
|
+
Requires-Dist: mypy>=2.4.1; extra == 'dev'
|
|
32
|
+
Requires-Dist: pre-commit>=4.6.2; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
37
|
+
Requires-Dist: ruff>=0.4; extra == 'dev'
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
|
|
40
|
+
# Py MoMo SDK (`py-momo-sdk`)
|
|
41
|
+
|
|
42
|
+
[](https://pypi.org/project/py-momo-sdk/)
|
|
43
|
+
[](https://github.com/wkambale/pymomo/actions)
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
|
|
46
|
+
Py MoMo SDK (`py-momo-sdk` 1.0.6) is a strictly typed, production-grade Python client library for the MTN Mobile Money (MoMo) Open API and Airtel Money API. It provides synchronous and asynchronous clients with matching interfaces, automatic token caching, strict validation, and complete product coverage.
|
|
47
|
+
|
|
48
|
+
Developed for high reliability and clean developer experience, Py MoMo SDK adheres to the strict security standards of modern payment systems.
|
|
49
|
+
|
|
50
|
+
- **PyPI package:** [py-momo-sdk](https://pypi.org/project/py-momo-sdk/) (`1.0.6`, imported as `py_momo_sdk`)
|
|
51
|
+
- **Documentation:** [https://wkambale.github.io/pymomo/](https://wkambale.github.io/pymomo/)
|
|
52
|
+
- **Repository:** [https://github.com/wkambale/pymomo](https://github.com/wkambale/pymomo)
|
|
53
|
+
|
|
54
|
+
## Features
|
|
55
|
+
|
|
56
|
+
- **Sync and async parity:** `PyMomoSDK` and `AsyncPyMomoSDK` backed by `httpx.Client` and `httpx.AsyncClient` with matching interfaces.
|
|
57
|
+
- **Pydantic v2 models:** Fully typed request and response validation and serialization.
|
|
58
|
+
- **Automated token caching:** Thread-safe and async-safe in-memory token management with automatic cache invalidation and retry-once logic.
|
|
59
|
+
- **Comprehensive API coverage:** Full MTN MoMo Collection (including CIBA and OAuth2 token exchange), Disbursement, Remittance, Sandbox, and Airtel Money APIs.
|
|
60
|
+
- **Robust security:** Strict HTTPS and input validation, constant-time webhook HMAC and source IP verification, and secret-redacting exceptions and representations.
|
|
61
|
+
- **CLI utility:** Ships with the `py-momo-sdk` Typer-powered CLI to bootstrap sandbox credentials, initiate payments, and query balances or transaction status.
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
|
|
65
|
+
Install `py-momo-sdk` (1.0.6) from PyPI using pip:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pip install py-momo-sdk
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
For development dependencies, install with:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install -e ".[dev]"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Quickstart
|
|
78
|
+
|
|
79
|
+
### Sandbox provisioning
|
|
80
|
+
|
|
81
|
+
Bootstrap a new sandbox API user and API key:
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
from py_momo_sdk import PyMomoSDK, PyMomoSDKConfig
|
|
85
|
+
|
|
86
|
+
config = PyMomoSDKConfig(environment="sandbox")
|
|
87
|
+
|
|
88
|
+
with PyMomoSDK(config) as client:
|
|
89
|
+
provisioner = client.create_sandbox_provisioner("your-sandbox-subscription-key")
|
|
90
|
+
credentials = provisioner.provision(callback_host="https://example.com")
|
|
91
|
+
|
|
92
|
+
print(f"API user: {credentials['api_user']}")
|
|
93
|
+
print(f"API key: {credentials['api_key']}")
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Collection (synchronous example)
|
|
97
|
+
|
|
98
|
+
Request a payment from a subscriber using the synchronous client:
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from py_momo_sdk import ProductConfig, PyMomoSDK, PyMomoSDKConfig
|
|
102
|
+
|
|
103
|
+
config = PyMomoSDKConfig(
|
|
104
|
+
environment="sandbox",
|
|
105
|
+
collection=ProductConfig(
|
|
106
|
+
subscription_key="your-collection-subscription-key",
|
|
107
|
+
api_user="550e8400-e29b-41d4-a716-446655440000",
|
|
108
|
+
api_key="your-api-key",
|
|
109
|
+
callback_url="https://example.com/webhook",
|
|
110
|
+
),
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
with PyMomoSDK(config) as client:
|
|
114
|
+
# Query account balance
|
|
115
|
+
balance = client.collection.get_balance()
|
|
116
|
+
print(f"Available balance: {balance.available_balance} {balance.currency}")
|
|
117
|
+
|
|
118
|
+
# Initiate a request to pay
|
|
119
|
+
reference_id = client.collection.request_to_pay(
|
|
120
|
+
amount="1000.00",
|
|
121
|
+
currency="UGX",
|
|
122
|
+
payer_msisdn="256771234567",
|
|
123
|
+
external_id="ext-tx-12345",
|
|
124
|
+
payer_message="Payment for invoice 123",
|
|
125
|
+
payee_note="Thank you for shopping with us",
|
|
126
|
+
)
|
|
127
|
+
print(f"Transaction reference: {reference_id}")
|
|
128
|
+
|
|
129
|
+
# Check status
|
|
130
|
+
tx = client.collection.get_payment_status(reference_id)
|
|
131
|
+
print(f"Transaction status: {tx.status}")
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Disbursement (asynchronous example)
|
|
135
|
+
|
|
136
|
+
Send funds using the asynchronous client:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
import asyncio
|
|
140
|
+
from py_momo_sdk import AsyncPyMomoSDK, ProductConfig, PyMomoSDKConfig
|
|
141
|
+
|
|
142
|
+
config = PyMomoSDKConfig(
|
|
143
|
+
environment="sandbox",
|
|
144
|
+
disbursement=ProductConfig(
|
|
145
|
+
subscription_key="your-disbursement-subscription-key",
|
|
146
|
+
api_user="550e8400-e29b-41d4-a716-446655440000",
|
|
147
|
+
api_key="your-api-key",
|
|
148
|
+
),
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
async def main() -> None:
|
|
152
|
+
async with AsyncPyMomoSDK(config) as client:
|
|
153
|
+
# Check active status of a mobile money user
|
|
154
|
+
is_active = await client.disbursement.is_account_holder_active("256771234567")
|
|
155
|
+
print(f"Account holder active: {is_active}")
|
|
156
|
+
|
|
157
|
+
# Initiate a transfer
|
|
158
|
+
reference_id = await client.disbursement.transfer(
|
|
159
|
+
amount="5000.00",
|
|
160
|
+
currency="UGX",
|
|
161
|
+
payee_msisdn="256771234567",
|
|
162
|
+
external_id="disb-tx-9999",
|
|
163
|
+
payer_message="Staff salary payment",
|
|
164
|
+
payee_note="Disbursement successful",
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
# Query transaction details
|
|
168
|
+
status = await client.disbursement.get_transfer_status(reference_id)
|
|
169
|
+
print(f"Transfer status: {status.status} (ID: {status.financial_transaction_id})")
|
|
170
|
+
|
|
171
|
+
asyncio.run(main())
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## CLI usage
|
|
175
|
+
|
|
176
|
+
Py MoMo SDK bundles the `py-momo-sdk` CLI tool for sandbox management, balance checks, and payment queries:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
# Show installed version
|
|
180
|
+
py-momo-sdk --version
|
|
181
|
+
|
|
182
|
+
# Provision a sandbox environment
|
|
183
|
+
py-momo-sdk sandbox provision --subscription-key "your-key"
|
|
184
|
+
|
|
185
|
+
# Query the collection balance
|
|
186
|
+
py-momo-sdk collection balance --subscription-key "your-key" --api-user "550e8400-e29b-41d4-a716-446655440000" --api-key "key"
|
|
187
|
+
|
|
188
|
+
# Check the status of a request to pay transaction
|
|
189
|
+
py-momo-sdk collection status "550e8400-e29b-41d4-a716-446655440000" --subscription-key "your-key" --api-user "550e8400-e29b-41d4-a716-446655440000" --api-key "key"
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Use `py-momo-sdk --help` to list all available commands and flags.
|
|
193
|
+
|
|
194
|
+
## Testing
|
|
195
|
+
|
|
196
|
+
Run checks, security analysis, and coverage reports:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
# Style and format checks
|
|
200
|
+
ruff check .
|
|
201
|
+
black --check .
|
|
202
|
+
isort --check .
|
|
203
|
+
|
|
204
|
+
# Static type check
|
|
205
|
+
mypy py_momo_sdk/
|
|
206
|
+
|
|
207
|
+
# Security analysis
|
|
208
|
+
bandit -r py_momo_sdk/
|
|
209
|
+
|
|
210
|
+
# Test execution with coverage
|
|
211
|
+
pytest --cov=py_momo_sdk --cov-report=term-missing
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
MIT License. Copyright (c) 2026 Wesley Kambale. See [LICENSE](LICENSE) for more details.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Py MoMo SDK (`py-momo-sdk`)
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/py-momo-sdk/)
|
|
4
|
+
[](https://github.com/wkambale/pymomo/actions)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
Py MoMo SDK (`py-momo-sdk` 1.0.6) is a strictly typed, production-grade Python client library for the MTN Mobile Money (MoMo) Open API and Airtel Money API. It provides synchronous and asynchronous clients with matching interfaces, automatic token caching, strict validation, and complete product coverage.
|
|
8
|
+
|
|
9
|
+
Developed for high reliability and clean developer experience, Py MoMo SDK adheres to the strict security standards of modern payment systems.
|
|
10
|
+
|
|
11
|
+
- **PyPI package:** [py-momo-sdk](https://pypi.org/project/py-momo-sdk/) (`1.0.6`, imported as `py_momo_sdk`)
|
|
12
|
+
- **Documentation:** [https://wkambale.github.io/pymomo/](https://wkambale.github.io/pymomo/)
|
|
13
|
+
- **Repository:** [https://github.com/wkambale/pymomo](https://github.com/wkambale/pymomo)
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **Sync and async parity:** `PyMomoSDK` and `AsyncPyMomoSDK` backed by `httpx.Client` and `httpx.AsyncClient` with matching interfaces.
|
|
18
|
+
- **Pydantic v2 models:** Fully typed request and response validation and serialization.
|
|
19
|
+
- **Automated token caching:** Thread-safe and async-safe in-memory token management with automatic cache invalidation and retry-once logic.
|
|
20
|
+
- **Comprehensive API coverage:** Full MTN MoMo Collection (including CIBA and OAuth2 token exchange), Disbursement, Remittance, Sandbox, and Airtel Money APIs.
|
|
21
|
+
- **Robust security:** Strict HTTPS and input validation, constant-time webhook HMAC and source IP verification, and secret-redacting exceptions and representations.
|
|
22
|
+
- **CLI utility:** Ships with the `py-momo-sdk` Typer-powered CLI to bootstrap sandbox credentials, initiate payments, and query balances or transaction status.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
Install `py-momo-sdk` (1.0.6) from PyPI using pip:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pip install py-momo-sdk
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
For development dependencies, install with:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install -e ".[dev]"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Quickstart
|
|
39
|
+
|
|
40
|
+
### Sandbox provisioning
|
|
41
|
+
|
|
42
|
+
Bootstrap a new sandbox API user and API key:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from py_momo_sdk import PyMomoSDK, PyMomoSDKConfig
|
|
46
|
+
|
|
47
|
+
config = PyMomoSDKConfig(environment="sandbox")
|
|
48
|
+
|
|
49
|
+
with PyMomoSDK(config) as client:
|
|
50
|
+
provisioner = client.create_sandbox_provisioner("your-sandbox-subscription-key")
|
|
51
|
+
credentials = provisioner.provision(callback_host="https://example.com")
|
|
52
|
+
|
|
53
|
+
print(f"API user: {credentials['api_user']}")
|
|
54
|
+
print(f"API key: {credentials['api_key']}")
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Collection (synchronous example)
|
|
58
|
+
|
|
59
|
+
Request a payment from a subscriber using the synchronous client:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from py_momo_sdk import ProductConfig, PyMomoSDK, PyMomoSDKConfig
|
|
63
|
+
|
|
64
|
+
config = PyMomoSDKConfig(
|
|
65
|
+
environment="sandbox",
|
|
66
|
+
collection=ProductConfig(
|
|
67
|
+
subscription_key="your-collection-subscription-key",
|
|
68
|
+
api_user="550e8400-e29b-41d4-a716-446655440000",
|
|
69
|
+
api_key="your-api-key",
|
|
70
|
+
callback_url="https://example.com/webhook",
|
|
71
|
+
),
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
with PyMomoSDK(config) as client:
|
|
75
|
+
# Query account balance
|
|
76
|
+
balance = client.collection.get_balance()
|
|
77
|
+
print(f"Available balance: {balance.available_balance} {balance.currency}")
|
|
78
|
+
|
|
79
|
+
# Initiate a request to pay
|
|
80
|
+
reference_id = client.collection.request_to_pay(
|
|
81
|
+
amount="1000.00",
|
|
82
|
+
currency="UGX",
|
|
83
|
+
payer_msisdn="256771234567",
|
|
84
|
+
external_id="ext-tx-12345",
|
|
85
|
+
payer_message="Payment for invoice 123",
|
|
86
|
+
payee_note="Thank you for shopping with us",
|
|
87
|
+
)
|
|
88
|
+
print(f"Transaction reference: {reference_id}")
|
|
89
|
+
|
|
90
|
+
# Check status
|
|
91
|
+
tx = client.collection.get_payment_status(reference_id)
|
|
92
|
+
print(f"Transaction status: {tx.status}")
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Disbursement (asynchronous example)
|
|
96
|
+
|
|
97
|
+
Send funds using the asynchronous client:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import asyncio
|
|
101
|
+
from py_momo_sdk import AsyncPyMomoSDK, ProductConfig, PyMomoSDKConfig
|
|
102
|
+
|
|
103
|
+
config = PyMomoSDKConfig(
|
|
104
|
+
environment="sandbox",
|
|
105
|
+
disbursement=ProductConfig(
|
|
106
|
+
subscription_key="your-disbursement-subscription-key",
|
|
107
|
+
api_user="550e8400-e29b-41d4-a716-446655440000",
|
|
108
|
+
api_key="your-api-key",
|
|
109
|
+
),
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
async def main() -> None:
|
|
113
|
+
async with AsyncPyMomoSDK(config) as client:
|
|
114
|
+
# Check active status of a mobile money user
|
|
115
|
+
is_active = await client.disbursement.is_account_holder_active("256771234567")
|
|
116
|
+
print(f"Account holder active: {is_active}")
|
|
117
|
+
|
|
118
|
+
# Initiate a transfer
|
|
119
|
+
reference_id = await client.disbursement.transfer(
|
|
120
|
+
amount="5000.00",
|
|
121
|
+
currency="UGX",
|
|
122
|
+
payee_msisdn="256771234567",
|
|
123
|
+
external_id="disb-tx-9999",
|
|
124
|
+
payer_message="Staff salary payment",
|
|
125
|
+
payee_note="Disbursement successful",
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
# Query transaction details
|
|
129
|
+
status = await client.disbursement.get_transfer_status(reference_id)
|
|
130
|
+
print(f"Transfer status: {status.status} (ID: {status.financial_transaction_id})")
|
|
131
|
+
|
|
132
|
+
asyncio.run(main())
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## CLI usage
|
|
136
|
+
|
|
137
|
+
Py MoMo SDK bundles the `py-momo-sdk` CLI tool for sandbox management, balance checks, and payment queries:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
# Show installed version
|
|
141
|
+
py-momo-sdk --version
|
|
142
|
+
|
|
143
|
+
# Provision a sandbox environment
|
|
144
|
+
py-momo-sdk sandbox provision --subscription-key "your-key"
|
|
145
|
+
|
|
146
|
+
# Query the collection balance
|
|
147
|
+
py-momo-sdk collection balance --subscription-key "your-key" --api-user "550e8400-e29b-41d4-a716-446655440000" --api-key "key"
|
|
148
|
+
|
|
149
|
+
# Check the status of a request to pay transaction
|
|
150
|
+
py-momo-sdk collection status "550e8400-e29b-41d4-a716-446655440000" --subscription-key "your-key" --api-user "550e8400-e29b-41d4-a716-446655440000" --api-key "key"
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Use `py-momo-sdk --help` to list all available commands and flags.
|
|
154
|
+
|
|
155
|
+
## Testing
|
|
156
|
+
|
|
157
|
+
Run checks, security analysis, and coverage reports:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
# Style and format checks
|
|
161
|
+
ruff check .
|
|
162
|
+
black --check .
|
|
163
|
+
isort --check .
|
|
164
|
+
|
|
165
|
+
# Static type check
|
|
166
|
+
mypy py_momo_sdk/
|
|
167
|
+
|
|
168
|
+
# Security analysis
|
|
169
|
+
bandit -r py_momo_sdk/
|
|
170
|
+
|
|
171
|
+
# Test execution with coverage
|
|
172
|
+
pytest --cov=py_momo_sdk --cov-report=term-missing
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT License. Copyright (c) 2026 Wesley Kambale. See [LICENSE](LICENSE) for more details.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
The following versions of Py MoMo SDK (`py-momo-sdk`) currently receive security updates:
|
|
6
|
+
|
|
7
|
+
| Version | Supported |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| 1.0.x | Yes |
|
|
10
|
+
| < 1.0.0 | No |
|
|
11
|
+
|
|
12
|
+
## Reporting a vulnerability
|
|
13
|
+
|
|
14
|
+
Do not open public GitHub issues for suspected security vulnerabilities.
|
|
15
|
+
|
|
16
|
+
To report a security issue privately, either:
|
|
17
|
+
|
|
18
|
+
1. Use GitHub's private vulnerability reporting feature on `wkambale/pymomo` under the **Security** tab.
|
|
19
|
+
2. Email the maintainers at `info@aiforuganda.org` with a clear description of the issue, affected versions, and minimal steps to reproduce.
|
|
20
|
+
|
|
21
|
+
You can expect an acknowledgement within 72 hours and a status update on remediation and coordinated disclosure timelines once the report is triaged.
|