mvola-api-lib 1.0.0__tar.gz

mvola_api_lib-1.0.0/.cursor/rules/lib-mvola-best-practices.mdc

@@ -0,0 +1,13 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+
+# Best practices for creating the Mvola library payment solution in Python globs
+
+- Use the official Mvola SDK for secure and reliable integration
+- Implement proper error handling and logging for payment transactions
+- Ensure compliance with Mvola's security guidelines and regulations
+- Regularly update the Mvola library to benefit from the latest features and security patches
+- Test payment flows thoroughly in a sandbox environment before going live

mvola_api_lib-1.0.0/.gitignore

@@ -0,0 +1,103 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environnements virtuels
+venv/
+ENV/
+env/
+.venv/
+.env/
+env.bak/
+venv.bak/
+
+# Documentation MkDocs
+site/
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Tests unitaires / couverture
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Fichiers d'environnement
+.env
+.env.test
+.env.local
+
+# Fichiers IDE
+# VS Code
+.vscode/
+.history/
+*.code-workspace
+
+# PyCharm
+.idea/
+*.iml
+*.iws
+*.ipr
+*.iws
+.idea_modules/
+
+# Fichiers système
+.DS_Store
+Thumbs.db
+*.swp
+*~
+._*
+.Spotlight-V100
+.Trashes

mvola_api_lib-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niainarisoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

mvola_api_lib-1.0.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: mvola-api-lib
+Version: 1.0.0
+Summary: Une bibliothèque Python robuste pour l'intégration de l'API de paiement MVola
+Project-URL: Homepage, https://github.com/Niainarisoa01/Mvlola_API_Lib
+Project-URL: Bug Tracker, https://github.com/Niainarisoa01/Mvlola_API_Lib/issues
+Project-URL: Documentation, https://niainarisoa01.github.io/Mvlola_API_Lib
+Author-email: Niainarisoa <niainarisoa.mail@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Niainarisoa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE. 
+License-File: LICENSE
+Keywords: api,fintech,madagascar,mvola,payment
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: black>=21.5b2; extra == 'dev'
+Requires-Dist: flake8>=3.9.2; extra == 'dev'
+Requires-Dist: isort>=5.9.1; extra == 'dev'
+Requires-Dist: pytest-cov>=2.12.0; extra == 'dev'
+Requires-Dist: pytest>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=8.2.8; extra == 'docs'
+Requires-Dist: mkdocs>=1.3.0; extra == 'docs'
+Requires-Dist: mkdocstrings-python>=0.7.1; extra == 'docs'
+Requires-Dist: mkdocstrings>=0.18.0; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: flask>=2.0.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# MVola API Python Library
+
+A robust Python library for integrating with MVola mobile payment API in Madagascar.
+
+## Installation
+
+```bash
+pip install mvola_api
+```
+
+## Features
+
+- Simple and intuitive API for MVola payment integration
+- Handles authentication token generation and management
+- Supports merchant payment operations
+- Comprehensive error handling
+- Logging support
+- Built-in parameter validation
+- Works with both sandbox and production environments
+
+## Quick Start
+
+```python
+from mvola_api import MVolaClient, SANDBOX_URL
+
+# Initialize the client
+client = MVolaClient(
+    consumer_key="your_consumer_key",
+    consumer_secret="your_consumer_secret",
+    partner_name="Your Application Name",
+    partner_msisdn="0340000000",  # Your merchant number
+    sandbox=True  # Use sandbox environment
+)
+
+# Generate a token
+token_data = client.generate_token()
+print(f"Token generated: {token_data['access_token'][:10]}...")
+
+# Initiate a payment
+result = client.initiate_payment(
+    amount=10000,
+    debit_msisdn="0343500003",  # Customer phone number
+    credit_msisdn="0343500004",  # Merchant phone number
+    description="Payment for service",
+    callback_url="https://example.com/callback"
+)
+
+# Track the server correlation ID for status checks
+server_correlation_id = result['response']['serverCorrelationId']
+print(f"Transaction initiated with correlation ID: {server_correlation_id}")
+
+# Check transaction status
+status = client.get_transaction_status(server_correlation_id)
+print(f"Transaction status: {status['response']['status']}")
+
+# Once transaction is completed, get details using transaction ID
+transaction_id = status['response'].get('objectReference')
+if transaction_id:
+    details = client.get_transaction_details(transaction_id)
+    print(f"Transaction details: {details['response']}")
+```
+
+## Sandbox Testing
+
+For sandbox testing, use the following test phone numbers:
+- 0343500003
+- 0343500004
+
+## Error Handling
+
+The library provides custom exceptions for different error types:
+
+```python
+from mvola_api import MVolaClient, MVolaError, MVolaAuthError, MVolaTransactionError
+
+client = MVolaClient(...)
+
+try:
+    result = client.initiate_payment(...)
+except MVolaAuthError as e:
+    print(f"Authentication error: {e}")
+except MVolaTransactionError as e:
+    print(f"Transaction error: {e}")
+except MVolaError as e:
+    print(f"General MVola error: {e}")
+```
+
+## API Documentation
+
+### MVolaClient
+
+The main client class for interacting with MVola API.
+
+#### Initialization
+
+```python
+client = MVolaClient(
+    consumer_key,          # Consumer key from MVola Developer Portal
+    consumer_secret,       # Consumer secret from MVola Developer Portal
+    partner_name,          # Your application/merchant name
+    partner_msisdn=None,   # Partner MSISDN (phone number)
+    sandbox=True,          # Use sandbox environment
+    logger=None            # Custom logger
+)
+```
+
+#### Methods
+
+- `generate_token(force_refresh=False)`: Generate an access token
+- `initiate_payment(amount, debit_msisdn, credit_msisdn, description, ...)`: Initiate a merchant payment
+- `get_transaction_status(server_correlation_id, user_language="FR")`: Get transaction status
+- `get_transaction_details(transaction_id, user_language="FR")`: Get transaction details
+
+## Best Practices
+
+1. **Token Management**: The library handles token refresh automatically, but you can force a refresh if needed.
+2. **Error Handling**: Always implement proper error handling in your application.
+3. **Logging**: The library includes logging, but you can provide your own logger.
+4. **Sandbox Testing**: Always test your integration in the sandbox environment before going live.
+5. **Webhook Handling**: Implement proper webhook handling for transaction notifications.
+
+## Development
+
+### Requirements
+
+- Python 3.6+
+- requests library
+
+### Installation for Development
+
+```bash
+git clone https://github.com/yourusername/mvola_api.git
+cd mvola_api
+pip install -e .
+```
+
+## License
+
+MIT
+
+## Credits
+
+Developed based on the official MVola API documentation. 

mvola_api_lib-1.0.0/README.md

@@ -0,0 +1,143 @@
+# MVola API Python Library
+
+A robust Python library for integrating with MVola mobile payment API in Madagascar.
+
+## Installation
+
+```bash
+pip install mvola_api
+```
+
+## Features
+
+- Simple and intuitive API for MVola payment integration
+- Handles authentication token generation and management
+- Supports merchant payment operations
+- Comprehensive error handling
+- Logging support
+- Built-in parameter validation
+- Works with both sandbox and production environments
+
+## Quick Start
+
+```python
+from mvola_api import MVolaClient, SANDBOX_URL
+
+# Initialize the client
+client = MVolaClient(
+    consumer_key="your_consumer_key",
+    consumer_secret="your_consumer_secret",
+    partner_name="Your Application Name",
+    partner_msisdn="0340000000",  # Your merchant number
+    sandbox=True  # Use sandbox environment
+)
+
+# Generate a token
+token_data = client.generate_token()
+print(f"Token generated: {token_data['access_token'][:10]}...")
+
+# Initiate a payment
+result = client.initiate_payment(
+    amount=10000,
+    debit_msisdn="0343500003",  # Customer phone number
+    credit_msisdn="0343500004",  # Merchant phone number
+    description="Payment for service",
+    callback_url="https://example.com/callback"
+)
+
+# Track the server correlation ID for status checks
+server_correlation_id = result['response']['serverCorrelationId']
+print(f"Transaction initiated with correlation ID: {server_correlation_id}")
+
+# Check transaction status
+status = client.get_transaction_status(server_correlation_id)
+print(f"Transaction status: {status['response']['status']}")
+
+# Once transaction is completed, get details using transaction ID
+transaction_id = status['response'].get('objectReference')
+if transaction_id:
+    details = client.get_transaction_details(transaction_id)
+    print(f"Transaction details: {details['response']}")
+```
+
+## Sandbox Testing
+
+For sandbox testing, use the following test phone numbers:
+- 0343500003
+- 0343500004
+
+## Error Handling
+
+The library provides custom exceptions for different error types:
+
+```python
+from mvola_api import MVolaClient, MVolaError, MVolaAuthError, MVolaTransactionError
+
+client = MVolaClient(...)
+
+try:
+    result = client.initiate_payment(...)
+except MVolaAuthError as e:
+    print(f"Authentication error: {e}")
+except MVolaTransactionError as e:
+    print(f"Transaction error: {e}")
+except MVolaError as e:
+    print(f"General MVola error: {e}")
+```
+
+## API Documentation
+
+### MVolaClient
+
+The main client class for interacting with MVola API.
+
+#### Initialization
+
+```python
+client = MVolaClient(
+    consumer_key,          # Consumer key from MVola Developer Portal
+    consumer_secret,       # Consumer secret from MVola Developer Portal
+    partner_name,          # Your application/merchant name
+    partner_msisdn=None,   # Partner MSISDN (phone number)
+    sandbox=True,          # Use sandbox environment
+    logger=None            # Custom logger
+)
+```
+
+#### Methods
+
+- `generate_token(force_refresh=False)`: Generate an access token
+- `initiate_payment(amount, debit_msisdn, credit_msisdn, description, ...)`: Initiate a merchant payment
+- `get_transaction_status(server_correlation_id, user_language="FR")`: Get transaction status
+- `get_transaction_details(transaction_id, user_language="FR")`: Get transaction details
+
+## Best Practices
+
+1. **Token Management**: The library handles token refresh automatically, but you can force a refresh if needed.
+2. **Error Handling**: Always implement proper error handling in your application.
+3. **Logging**: The library includes logging, but you can provide your own logger.
+4. **Sandbox Testing**: Always test your integration in the sandbox environment before going live.
+5. **Webhook Handling**: Implement proper webhook handling for transaction notifications.
+
+## Development
+
+### Requirements
+
+- Python 3.6+
+- requests library
+
+### Installation for Development
+
+```bash
+git clone https://github.com/yourusername/mvola_api.git
+cd mvola_api
+pip install -e .
+```
+
+## License
+
+MIT
+
+## Credits
+
+Developed based on the official MVola API documentation. 

mvola_api_lib-1.0.0/api-mvola/__init__.py

@@ -0,0 +1,24 @@
+"""
+MVola API Python Library
+
+A robust Python library for MVola payment integration.
+"""
+
+from .auth import MVolaAuth
+from .client import MVolaClient
+from .constants import PRODUCTION_URL, SANDBOX_URL
+from .exceptions import MVolaAuthError, MVolaError, MVolaTransactionError
+from .transaction import MVolaTransaction
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MVolaClient",
+    "MVolaAuth",
+    "MVolaTransaction",
+    "SANDBOX_URL",
+    "PRODUCTION_URL",
+    "MVolaError",
+    "MVolaAuthError",
+    "MVolaTransactionError",
+]

mvola_api_lib-1.0.0/api-mvola/auth.py

@@ -0,0 +1,117 @@
+"""
+MVola API Authentication Module
+"""
+
+import base64
+import time
+from urllib.parse import urljoin
+
+import requests
+
+from .constants import GRANT_TYPE, TOKEN_ENDPOINT, TOKEN_SCOPE
+from .exceptions import MVolaAuthError
+
+
+class MVolaAuth:
+    """
+    Class for managing authentication with MVola API
+    """
+
+    def __init__(self, consumer_key, consumer_secret, base_url):
+        """
+        Initialize the auth module
+
+        Args:
+            consumer_key (str): Consumer key from MVola Developer Portal
+            consumer_secret (str): Consumer secret from MVola Developer Portal
+            base_url (str): Base URL for the API (sandbox or production)
+        """
+        self.consumer_key = consumer_key
+        self.consumer_secret = consumer_secret
+        self.base_url = base_url
+        self.token = None
+        self.token_expiry = 0
+
+    def _encode_credentials(self):
+        """
+        Encode consumer key and secret for Basic Auth
+
+        Returns:
+            str: Base64 encoded credentials
+        """
+        credentials = f"{self.consumer_key}:{self.consumer_secret}"
+        encoded = base64.b64encode(credentials.encode()).decode()
+        return encoded
+
+    def generate_token(self, force_refresh=False):
+        """
+        Generate an access token for MVola API
+
+        Args:
+            force_refresh (bool): Force token refresh even if current token is valid
+
+        Returns:
+            dict: Token response with access_token, token_type, expires_in, scope
+
+        Raises:
+            MVolaAuthError: If token generation fails
+        """
+        # Check if token is still valid (with 60 seconds buffer)
+        current_time = time.time()
+        if not force_refresh and self.token and current_time < self.token_expiry - 60:
+            return self.token
+
+        # Set up the request
+        url = urljoin(self.base_url, TOKEN_ENDPOINT)
+        headers = {
+            "Authorization": f"Basic {self._encode_credentials()}",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Cache-Control": "no-cache",
+        }
+        data = {"grant_type": GRANT_TYPE, "scope": TOKEN_SCOPE}
+
+        try:
+            response = requests.post(url, headers=headers, data=data)
+            response.raise_for_status()  # Raise exception for non-200 responses
+
+            token_data = response.json()
+            # Calculate token expiry time
+            self.token = token_data
+            self.token_expiry = current_time + token_data.get("expires_in", 3600)
+
+            return token_data
+
+        except requests.exceptions.RequestException as e:
+            error_message = "Failed to generate token"
+
+            # Try to extract error details if available
+            if hasattr(e, "response") and e.response is not None:
+                try:
+                    error_data = e.response.json()
+                    if "error" in error_data:
+                        error_message = f"{error_message}: {error_data.get('error_description', error_data['error'])}"
+                except (ValueError, KeyError):
+                    pass
+
+            raise MVolaAuthError(
+                message=error_message,
+                code=(
+                    e.response.status_code
+                    if hasattr(e, "response") and e.response
+                    else None
+                ),
+                response=e.response if hasattr(e, "response") else None,
+            ) from e
+
+    def get_access_token(self, force_refresh=False):
+        """
+        Get current access token or generate a new one
+
+        Args:
+            force_refresh (bool): Force token refresh
+
+        Returns:
+            str: Access token string
+        """
+        token_data = self.generate_token(force_refresh)
+        return token_data["access_token"]