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.
Files changed (56) hide show
  1. py_momo_sdk-1.0.6/.gitignore +74 -0
  2. py_momo_sdk-1.0.6/CHANGELOG.md +64 -0
  3. py_momo_sdk-1.0.6/CONTRIBUTING.md +57 -0
  4. py_momo_sdk-1.0.6/LICENSE +21 -0
  5. py_momo_sdk-1.0.6/PKG-INFO +216 -0
  6. py_momo_sdk-1.0.6/README.md +177 -0
  7. py_momo_sdk-1.0.6/SECURITY.md +21 -0
  8. py_momo_sdk-1.0.6/py_momo_sdk/__init__.py +81 -0
  9. py_momo_sdk-1.0.6/py_momo_sdk/_async/__init__.py +1 -0
  10. py_momo_sdk-1.0.6/py_momo_sdk/_async/client.py +134 -0
  11. py_momo_sdk-1.0.6/py_momo_sdk/_async/http.py +134 -0
  12. py_momo_sdk-1.0.6/py_momo_sdk/_async/products/__init__.py +1 -0
  13. py_momo_sdk-1.0.6/py_momo_sdk/_async/products/base.py +209 -0
  14. py_momo_sdk-1.0.6/py_momo_sdk/_async/products/collection.py +293 -0
  15. py_momo_sdk-1.0.6/py_momo_sdk/_async/products/disbursement.py +237 -0
  16. py_momo_sdk-1.0.6/py_momo_sdk/_async/products/remittance.py +89 -0
  17. py_momo_sdk-1.0.6/py_momo_sdk/_async/sandbox.py +145 -0
  18. py_momo_sdk-1.0.6/py_momo_sdk/_cli.py +454 -0
  19. py_momo_sdk-1.0.6/py_momo_sdk/airtel/__init__.py +6 -0
  20. py_momo_sdk-1.0.6/py_momo_sdk/airtel/auth.py +156 -0
  21. py_momo_sdk-1.0.6/py_momo_sdk/airtel/client.py +196 -0
  22. py_momo_sdk-1.0.6/py_momo_sdk/airtel/config.py +53 -0
  23. py_momo_sdk-1.0.6/py_momo_sdk/airtel/models.py +180 -0
  24. py_momo_sdk-1.0.6/py_momo_sdk/airtel/products/collection.py +83 -0
  25. py_momo_sdk-1.0.6/py_momo_sdk/airtel/products/disbursement.py +89 -0
  26. py_momo_sdk-1.0.6/py_momo_sdk/auth.py +67 -0
  27. py_momo_sdk-1.0.6/py_momo_sdk/client.py +141 -0
  28. py_momo_sdk-1.0.6/py_momo_sdk/config.py +128 -0
  29. py_momo_sdk-1.0.6/py_momo_sdk/exceptions.py +52 -0
  30. py_momo_sdk-1.0.6/py_momo_sdk/http.py +169 -0
  31. py_momo_sdk-1.0.6/py_momo_sdk/models.py +322 -0
  32. py_momo_sdk-1.0.6/py_momo_sdk/products/__init__.py +1 -0
  33. py_momo_sdk-1.0.6/py_momo_sdk/products/base.py +203 -0
  34. py_momo_sdk-1.0.6/py_momo_sdk/products/collection.py +293 -0
  35. py_momo_sdk-1.0.6/py_momo_sdk/products/disbursement.py +237 -0
  36. py_momo_sdk-1.0.6/py_momo_sdk/products/remittance.py +89 -0
  37. py_momo_sdk-1.0.6/py_momo_sdk/py.typed +0 -0
  38. py_momo_sdk-1.0.6/py_momo_sdk/sandbox.py +142 -0
  39. py_momo_sdk-1.0.6/py_momo_sdk/utils.py +387 -0
  40. py_momo_sdk-1.0.6/py_momo_sdk/webhooks.py +144 -0
  41. py_momo_sdk-1.0.6/pyproject.toml +92 -0
  42. py_momo_sdk-1.0.6/tests/conftest.py +71 -0
  43. py_momo_sdk-1.0.6/tests/integration/test_airtel_client.py +656 -0
  44. py_momo_sdk-1.0.6/tests/integration/test_collection.py +676 -0
  45. py_momo_sdk-1.0.6/tests/integration/test_disbursement.py +341 -0
  46. py_momo_sdk-1.0.6/tests/integration/test_remittance.py +195 -0
  47. py_momo_sdk-1.0.6/tests/integration/test_sandbox.py +214 -0
  48. py_momo_sdk-1.0.6/tests/unit/test_airtel_auth.py +220 -0
  49. py_momo_sdk-1.0.6/tests/unit/test_auth.py +82 -0
  50. py_momo_sdk-1.0.6/tests/unit/test_cli.py +387 -0
  51. py_momo_sdk-1.0.6/tests/unit/test_config.py +122 -0
  52. py_momo_sdk-1.0.6/tests/unit/test_exceptions.py +38 -0
  53. py_momo_sdk-1.0.6/tests/unit/test_http.py +314 -0
  54. py_momo_sdk-1.0.6/tests/unit/test_models.py +142 -0
  55. py_momo_sdk-1.0.6/tests/unit/test_utils.py +127 -0
  56. 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
+ [![PyPI version](https://img.shields.io/pypi/v/py-momo-sdk.svg)](https://pypi.org/project/py-momo-sdk/)
43
+ [![Build status](https://github.com/wkambale/pymomo/actions/workflows/ci.yml/badge.svg)](https://github.com/wkambale/pymomo/actions)
44
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg)](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
+ [![PyPI version](https://img.shields.io/pypi/v/py-momo-sdk.svg)](https://pypi.org/project/py-momo-sdk/)
4
+ [![Build status](https://github.com/wkambale/pymomo/actions/workflows/ci.yml/badge.svg)](https://github.com/wkambale/pymomo/actions)
5
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg)](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.