mmpay-python-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

mmpay_python_sdk-0.1.2/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: mmpay-python-sdk
+Version: 0.1.2
+Summary: Python SDK for MyanMyanPay
+Home-page: https://github.com/nawing/MMPay-Python-SDK
+Author: Naw Ing
+Author-email: nawing@myanmyanpay.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# MMPay Python SDK
+
+A Python client library for integrating with the MMPay Payment Gateway. This SDK is a direct port of the official Node.js SDK, providing utilities for payment creation, transaction retrieval, handshake authentication, and callback verification for technical architects and developers.
+
+## Features
+
+- Sandbox & Production Support: Dedicated methods for both environments.
+- Payment Creation & Retrieval: Endpoints to create payments and fetch transaction statuses.
+- HMAC SHA256 Signing: Automatic signature generation for request integrity.
+- Callback Verification: Utility to verify incoming webhooks from MMPay.
+- Type Definitions: Includes TypedDict definitions for clear payload structuring.
+
+## Installation
+
+```bash 
+pip install mmpay-python-sdk 
+```
+
+## Configuration
+
+To use the SDK, you need your App ID, Publishable Key, and Secret Key provided by the MyanMyanPay dashboard.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| appId | str | Yes | Your unique Application ID. |
+| publishableKey | str | Yes | Public key for authentication. |
+| secretKey | str | Yes | Private key used for signing requests (HMAC). |
+| apiBaseUrl | str | Yes | The base URL for the MMPay API. |
+
+
+```python
+from mmpay import MMPaySDK
+
+options = {
+    "appId": "YOUR_APP_ID",
+    "publishableKey": "YOUR_PUBLISHABLE_KEY",
+    "secretKey": "YOUR_SECRET_KEY",
+    "apiBaseUrl": "https://xxx.myanmyanpay.com"
+}
+
+sdk = MMPaySDK(options)
+```
+
+## Usage
+
+### 1. Payment Request Payload
+
+Passed to `sdk.pay(params)` or `sdk.sandbox_pay(params)`.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `orderId` | `str` | Yes | Unique identifier for the order (e.g., "ORD-001"). |
+| `amount` | `float` | Yes | Total transaction amount. |
+| `items` | `List[Item]` | No | A list of items included in the order. |
+| `callbackUrl` | `str` | No | URL where the webhook callback will be sent. |
+| `customMessage` | `str` | No | Custom message to be attached to the transaction. |
+
+**Item Object**
+
+Used inside the `items` list of a Payment Request.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `str` | Yes | Name of the product/service. |
+| `amount` | `float` | Yes | Price per unit. |
+| `quantity` | `int` | Yes | Quantity of the item. |
+
+### 2. Create a Payment (Sandbox)
+
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-SANDBOX-001",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.sandbox_pay(payment_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+### 3. Retrieve a Payment 
+
+```python
+#(Sandbox)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.sandbox_get(get_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+
+```python
+#(Production)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.get(get_request)
+    print(response)
+```
+
+### 4. Create a Payment (Production)
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-LIVE-98765",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.pay(payment_request)
+    print(response.get('url'))
+
+except Exception as e:
+    print(e)
+```
+
+### 5. Verify Callback (Webhook)
+
+When MyanMyanPay sends a callback to your `callbackUrl`[cite: 1], you must verify the request signature to ensure it is genuine. 
+
+**Incoming Headers**
+
+| Field Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `Content-Type` | `str` | Yes | `application/json` |
+| `X-Mmpay-Signature` | `str` | Yes | Generated HMAC signature |
+| `X-Mmpay-Nonce` | `str` | Yes | Unique nonce string |
+
+**Example Verification (Flask)**
+
+
+```python
+from flask import request
+
+@app.route('/webhook/mmpay', methods=['POST'])
+def mmpay_webhook():
+    payload_str = request.data.decode('utf-8')
+    nonce = request.headers.get('X-Mmpay-Nonce')
+    signature = request.headers.get('X-Mmpay-Signature')
+
+    try:
+        is_valid = sdk.verify_cb(payload_str, nonce, signature)
+        
+        if is_valid:
+            return "Verified", 200
+        else:
+            return "Invalid Signature", 400
+
+    except ValueError as e:
+        return str(e), 400
+```
+
+## Error Codes
+
+### API Key Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `KA0001` | Bearer Token Not Included |
+| `KA0002` | API Key Not 'LIVE' |
+| `KA0003` | Signature mismatch |
+| `KA0004` | Internal Server Error |
+| `KA0005` | IP Not whitelisted |
+| `429` | Rate limit hit (1000 req/min) |
+
+### JWT Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `BA001` | `Btoken` nonce token missing |
+| `BA002` | `Btoken` nonce mismatch |
+
+## License
+
+MIT

mmpay_python_sdk-0.1.2/README.md

@@ -0,0 +1,205 @@
+# MMPay Python SDK
+
+A Python client library for integrating with the MMPay Payment Gateway. This SDK is a direct port of the official Node.js SDK, providing utilities for payment creation, transaction retrieval, handshake authentication, and callback verification for technical architects and developers.
+
+## Features
+
+- Sandbox & Production Support: Dedicated methods for both environments.
+- Payment Creation & Retrieval: Endpoints to create payments and fetch transaction statuses.
+- HMAC SHA256 Signing: Automatic signature generation for request integrity.
+- Callback Verification: Utility to verify incoming webhooks from MMPay.
+- Type Definitions: Includes TypedDict definitions for clear payload structuring.
+
+## Installation
+
+```bash 
+pip install mmpay-python-sdk 
+```
+
+## Configuration
+
+To use the SDK, you need your App ID, Publishable Key, and Secret Key provided by the MyanMyanPay dashboard.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| appId | str | Yes | Your unique Application ID. |
+| publishableKey | str | Yes | Public key for authentication. |
+| secretKey | str | Yes | Private key used for signing requests (HMAC). |
+| apiBaseUrl | str | Yes | The base URL for the MMPay API. |
+
+
+```python
+from mmpay import MMPaySDK
+
+options = {
+    "appId": "YOUR_APP_ID",
+    "publishableKey": "YOUR_PUBLISHABLE_KEY",
+    "secretKey": "YOUR_SECRET_KEY",
+    "apiBaseUrl": "https://xxx.myanmyanpay.com"
+}
+
+sdk = MMPaySDK(options)
+```
+
+## Usage
+
+### 1. Payment Request Payload
+
+Passed to `sdk.pay(params)` or `sdk.sandbox_pay(params)`.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `orderId` | `str` | Yes | Unique identifier for the order (e.g., "ORD-001"). |
+| `amount` | `float` | Yes | Total transaction amount. |
+| `items` | `List[Item]` | No | A list of items included in the order. |
+| `callbackUrl` | `str` | No | URL where the webhook callback will be sent. |
+| `customMessage` | `str` | No | Custom message to be attached to the transaction. |
+
+**Item Object**
+
+Used inside the `items` list of a Payment Request.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `str` | Yes | Name of the product/service. |
+| `amount` | `float` | Yes | Price per unit. |
+| `quantity` | `int` | Yes | Quantity of the item. |
+
+### 2. Create a Payment (Sandbox)
+
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-SANDBOX-001",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.sandbox_pay(payment_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+### 3. Retrieve a Payment 
+
+```python
+#(Sandbox)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.sandbox_get(get_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+
+```python
+#(Production)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.get(get_request)
+    print(response)
+```
+
+### 4. Create a Payment (Production)
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-LIVE-98765",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.pay(payment_request)
+    print(response.get('url'))
+
+except Exception as e:
+    print(e)
+```
+
+### 5. Verify Callback (Webhook)
+
+When MyanMyanPay sends a callback to your `callbackUrl`[cite: 1], you must verify the request signature to ensure it is genuine. 
+
+**Incoming Headers**
+
+| Field Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `Content-Type` | `str` | Yes | `application/json` |
+| `X-Mmpay-Signature` | `str` | Yes | Generated HMAC signature |
+| `X-Mmpay-Nonce` | `str` | Yes | Unique nonce string |
+
+**Example Verification (Flask)**
+
+
+```python
+from flask import request
+
+@app.route('/webhook/mmpay', methods=['POST'])
+def mmpay_webhook():
+    payload_str = request.data.decode('utf-8')
+    nonce = request.headers.get('X-Mmpay-Nonce')
+    signature = request.headers.get('X-Mmpay-Signature')
+
+    try:
+        is_valid = sdk.verify_cb(payload_str, nonce, signature)
+        
+        if is_valid:
+            return "Verified", 200
+        else:
+            return "Invalid Signature", 400
+
+    except ValueError as e:
+        return str(e), 400
+```
+
+## Error Codes
+
+### API Key Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `KA0001` | Bearer Token Not Included |
+| `KA0002` | API Key Not 'LIVE' |
+| `KA0003` | Signature mismatch |
+| `KA0004` | Internal Server Error |
+| `KA0005` | IP Not whitelisted |
+| `429` | Rate limit hit (1000 req/min) |
+
+### JWT Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `BA001` | `Btoken` nonce token missing |
+| `BA002` | `Btoken` nonce mismatch |
+
+## License
+
+MIT

{mmpay_python_sdk-0.1.0 → mmpay_python_sdk-0.1.2}/mmpay/client.py

@@ -3,43 +3,82 @@ import json
 import hmac
 import hashlib
 import requests
-from typing import List, Optional, TypedDict, Dict, Any
-
-# --- Type Definitions to mirror your Interfaces ---
+from typing import List, Optional, TypedDict, Dict, Any, Union
 
 class Item(TypedDict):
     name: str
     amount: float
     quantity: int
 
-class PaymentRequest(TypedDict):
+class _PaymentRequestRequired(TypedDict):
     orderId: str
     amount: float
+
+class PaymentRequest(_PaymentRequestRequired, total=False):
     items: List[Item]
-    currency: Optional[str]
-    callbackUrl: Optional[str]
+    currency: str
+    callbackUrl: str
+    customMessage: str
 
-class XPaymentRequest(PaymentRequest, total=False):
+class _XPaymentRequestRequired(TypedDict):
     appId: str
     nonce: str
 
+class XPaymentRequest(PaymentRequest, _XPaymentRequestRequired):
+    pass
+
 class HandShakeRequest(TypedDict):
     orderId: str
     nonce: str
 
+class HandShakeResponse(TypedDict):
+    token: str
+
+class CallbackIncomingData(TypedDict):
+    orderId: str
+    amount: float
+    method: str
+    currency: str
+    vendor: str
+    status: str
+    condition: str
+    transactionRefId: str
+    callbackUrl: Optional[str]
+    customMessage: Optional[str]
+
 class SDKOptions(TypedDict):
     appId: str
     publishableKey: str
     secretKey: str
     apiBaseUrl: str
 
-# --- Main SDK Class ---
+class _PayGetRequestRequired(TypedDict):
+    orderId: str
+
+class PayGetRequest(_PayGetRequestRequired, total=False):
+    nonce: str
+
+class PayGetResponse(TypedDict, total=False):
+    appId: str
+    orderId: str
+    amount: float
+    vendor: str
+    method: str
+    customMessage: str
+    callbackUrl: str
+    callbackUrlStatus: str
+    callbackAt: str
+    disbursementId: str
+    disStatus: str
+    status: str
+    condition: str
+    createdAt: str
+    transactionRefId: str
+    qr: str
+    url: str
 
 class MMPaySDK:
     def __init__(self, options: SDKOptions):
-        """
-        Initializes the SDK with the merchant's keys and the API endpoint.
-        """
         self._app_id = options['appId']
         self._publishable_key = options['publishableKey']
         self._secret_key = options['secretKey']
@@ -47,9 +86,6 @@ class MMPaySDK:
         self._btoken: Optional[str] = None
 
     def _generate_signature(self, body_string: str, nonce: str) -> str:
-        """
-        Generates an HMAC SHA256 signature for request integrity.
-        """
         string_to_sign = f"{nonce}.{body_string}"
         return hmac.new(
             self._secret_key.encode('utf-8'),
@@ -58,23 +94,15 @@ class MMPaySDK:
         ).hexdigest()
 
     def _get_nonce(self) -> str:
-        """Helper to get current timestamp as string (milliseconds)"""
         return str(int(time.time() * 1000))
 
     def _json_stringify(self, data: Any) -> str:
-        """
-        Mimics JS JSON.stringify exactly (no spaces).
-        Crucial for signature verification.
-        """
         return json.dumps(data, separators=(',', ':'))
 
-    # --- Sandbox Methods ---
-
-    def sandbox_handshake(self, payload: HandShakeRequest) -> Dict[str, Any]:
+    def sandbox_handshake(self, payload: HandShakeRequest) -> Union[HandShakeResponse, Dict[str, Any]]:
         endpoint = f"{self._api_base_url}/payments/sandbox-handshake"
         nonce = self._get_nonce()
         
-        # Ensure payload is serialized exactly as the signature expects
         body_string = self._json_stringify(payload)
         signature = self._generate_signature(body_string, nonce)
 
@@ -93,37 +121,41 @@ class MMPaySDK:
                 self._btoken = data['token']
             return data
         except requests.exceptions.RequestException as e:
-            # In a real SDK, you might want to raise custom exceptions here
-            return {"error": str(e), "details": response.text if response else None}
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
 
     def sandbox_pay(self, params: PaymentRequest) -> Dict[str, Any]:
         endpoint = f"{self._api_base_url}/payments/sandbox-create"
         nonce = self._get_nonce()
 
-        # Construct payload
-        xpayload: XPaymentRequest = {
+        xpayload: Dict[str, Any] = {
             "appId": self._app_id,
             "nonce": nonce,
             "amount": params['amount'],
             "orderId": params['orderId'],
-            "items": params['items'],
         }
+
+        if 'items' in params:
+            xpayload['items'] = params['items']
         if 'callbackUrl' in params:
             xpayload['callbackUrl'] = params['callbackUrl']
-        if 'currency' in params:
-            xpayload['currency'] = params['currency']
+        if 'customMessage' in params:
+            xpayload['customMessage'] = params['customMessage']
 
         body_string = self._json_stringify(xpayload)
         signature = self._generate_signature(body_string, nonce)
 
-        # Perform handshake first (as per TS logic)
-        handshake_res = self.sandbox_handshake({'orderId': xpayload['orderId'], 'nonce': xpayload['nonce']})
+        handshake_payload: HandShakeRequest = {
+            'orderId': str(xpayload['orderId']), 
+            'nonce': str(xpayload['nonce'])
+        }
+        
+        handshake_res = self.sandbox_handshake(handshake_payload)
         if 'error' in handshake_res:
             return handshake_res
 
         headers = {
             'Authorization': f"Bearer {self._publishable_key}",
-            'X-Mmpay-Btoken': self._btoken,
+            'X-Mmpay-Btoken': self._btoken or '',
             'X-Mmpay-Nonce': nonce,
             'X-Mmpay-Signature': signature,
             'Content-Type': 'application/json',
@@ -134,11 +166,45 @@ class MMPaySDK:
             response.raise_for_status()
             return response.json()
         except requests.exceptions.RequestException as e:
-            return {"error": str(e), "details": response.text if response else None}
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
+
+    def sandbox_get(self, params: PayGetRequest) -> Union[PayGetResponse, Dict[str, Any]]:
+        endpoint = f"{self._api_base_url}/payments/sandbox-get"
+        nonce = self._get_nonce()
+
+        xpayload: Dict[str, Any] = {
+            "orderId": params['orderId'],
+            "nonce": nonce
+        }
+
+        body_string = self._json_stringify(xpayload)
+        signature = self._generate_signature(body_string, nonce)
 
-    # --- Production Methods ---
+        handshake_payload: HandShakeRequest = {
+            'orderId': str(xpayload['orderId']),
+            'nonce': str(xpayload['nonce'])
+        }
 
-    def handshake(self, payload: HandShakeRequest) -> Dict[str, Any]:
+        handshake_res = self.sandbox_handshake(handshake_payload)
+        if 'error' in handshake_res:
+            return handshake_res
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            'X-Mmpay-Btoken': self._btoken or '',
+            'X-Mmpay-Nonce': nonce,
+            'X-Mmpay-Signature': signature,
+            'Content-Type': 'application/json',
+        }
+
+        try:
+            response = requests.post(endpoint, data=body_string, headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
+
+    def handshake(self, payload: HandShakeRequest) -> Union[HandShakeResponse, Dict[str, Any]]:
         endpoint = f"{self._api_base_url}/payments/handshake"
         nonce = self._get_nonce()
         
@@ -160,35 +226,41 @@ class MMPaySDK:
                 self._btoken = data['token']
             return data
         except requests.exceptions.RequestException as e:
-            return {"error": str(e), "details": response.text if response else None}
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
 
     def pay(self, params: PaymentRequest) -> Dict[str, Any]:
         endpoint = f"{self._api_base_url}/payments/create"
         nonce = self._get_nonce()
 
-        xpayload: XPaymentRequest = {
+        xpayload: Dict[str, Any] = {
             "appId": self._app_id,
             "nonce": nonce,
             "amount": params['amount'],
             "orderId": params['orderId'],
-            "items": params['items'],
         }
+
+        if 'items' in params:
+            xpayload['items'] = params['items']
         if 'callbackUrl' in params:
             xpayload['callbackUrl'] = params['callbackUrl']
-        if 'currency' in params:
-            xpayload['currency'] = params['currency']
+        if 'customMessage' in params:
+            xpayload['customMessage'] = params['customMessage']
 
         body_string = self._json_stringify(xpayload)
         signature = self._generate_signature(body_string, nonce)
 
-        # Perform handshake
-        handshake_res = self.handshake({'orderId': xpayload['orderId'], 'nonce': xpayload['nonce']})
+        handshake_payload: HandShakeRequest = {
+            'orderId': str(xpayload['orderId']), 
+            'nonce': str(xpayload['nonce'])
+        }
+        
+        handshake_res = self.handshake(handshake_payload)
         if 'error' in handshake_res:
             return handshake_res
 
         headers = {
             'Authorization': f"Bearer {self._publishable_key}",
-            'X-Mmpay-Btoken': self._btoken,
+            'X-Mmpay-Btoken': self._btoken or '',
             'X-Mmpay-Nonce': nonce,
             'X-Mmpay-Signature': signature,
             'Content-Type': 'application/json',
@@ -199,14 +271,45 @@ class MMPaySDK:
             response.raise_for_status()
             return response.json()
         except requests.exceptions.RequestException as e:
-            return {"error": str(e), "details": response.text if response else None}
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
+
+    def get(self, params: PayGetRequest) -> Union[PayGetResponse, Dict[str, Any]]:
+        endpoint = f"{self._api_base_url}/payments/get"
+        nonce = self._get_nonce()
+
+        xpayload: Dict[str, Any] = {
+            "orderId": params['orderId'],
+            "nonce": nonce
+        }
+
+        body_string = self._json_stringify(xpayload)
+        signature = self._generate_signature(body_string, nonce)
+
+        handshake_payload: HandShakeRequest = {
+            'orderId': str(xpayload['orderId']),
+            'nonce': str(xpayload['nonce'])
+        }
+
+        handshake_res = self.handshake(handshake_payload)
+        if 'error' in handshake_res:
+            return handshake_res
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            'X-Mmpay-Btoken': self._btoken or '',
+            'X-Mmpay-Nonce': nonce,
+            'X-Mmpay-Signature': signature,
+            'Content-Type': 'application/json',
+        }
 
-    # --- Verification ---
+        try:
+            response = requests.post(endpoint, data=body_string, headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            return {"error": str(e), "details": getattr(e.response, 'text', '')}
 
     def verify_cb(self, payload: str, nonce: str, expected_signature: str) -> bool:
-        """
-        Verifies the signature of a callback request.
-        """
         if not payload or not nonce or not expected_signature:
             raise ValueError("Callback verification failed: Missing payload, nonce, or signature.")
 

mmpay_python_sdk-0.1.2/mmpay_python_sdk.egg-info/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: mmpay-python-sdk
+Version: 0.1.2
+Summary: Python SDK for MyanMyanPay
+Home-page: https://github.com/nawing/MMPay-Python-SDK
+Author: Naw Ing
+Author-email: nawing@myanmyanpay.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# MMPay Python SDK
+
+A Python client library for integrating with the MMPay Payment Gateway. This SDK is a direct port of the official Node.js SDK, providing utilities for payment creation, transaction retrieval, handshake authentication, and callback verification for technical architects and developers.
+
+## Features
+
+- Sandbox & Production Support: Dedicated methods for both environments.
+- Payment Creation & Retrieval: Endpoints to create payments and fetch transaction statuses.
+- HMAC SHA256 Signing: Automatic signature generation for request integrity.
+- Callback Verification: Utility to verify incoming webhooks from MMPay.
+- Type Definitions: Includes TypedDict definitions for clear payload structuring.
+
+## Installation
+
+```bash 
+pip install mmpay-python-sdk 
+```
+
+## Configuration
+
+To use the SDK, you need your App ID, Publishable Key, and Secret Key provided by the MyanMyanPay dashboard.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| appId | str | Yes | Your unique Application ID. |
+| publishableKey | str | Yes | Public key for authentication. |
+| secretKey | str | Yes | Private key used for signing requests (HMAC). |
+| apiBaseUrl | str | Yes | The base URL for the MMPay API. |
+
+
+```python
+from mmpay import MMPaySDK
+
+options = {
+    "appId": "YOUR_APP_ID",
+    "publishableKey": "YOUR_PUBLISHABLE_KEY",
+    "secretKey": "YOUR_SECRET_KEY",
+    "apiBaseUrl": "https://xxx.myanmyanpay.com"
+}
+
+sdk = MMPaySDK(options)
+```
+
+## Usage
+
+### 1. Payment Request Payload
+
+Passed to `sdk.pay(params)` or `sdk.sandbox_pay(params)`.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `orderId` | `str` | Yes | Unique identifier for the order (e.g., "ORD-001"). |
+| `amount` | `float` | Yes | Total transaction amount. |
+| `items` | `List[Item]` | No | A list of items included in the order. |
+| `callbackUrl` | `str` | No | URL where the webhook callback will be sent. |
+| `customMessage` | `str` | No | Custom message to be attached to the transaction. |
+
+**Item Object**
+
+Used inside the `items` list of a Payment Request.
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `str` | Yes | Name of the product/service. |
+| `amount` | `float` | Yes | Price per unit. |
+| `quantity` | `int` | Yes | Quantity of the item. |
+
+### 2. Create a Payment (Sandbox)
+
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-SANDBOX-001",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.sandbox_pay(payment_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+### 3. Retrieve a Payment 
+
+```python
+#(Sandbox)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.sandbox_get(get_request)
+    print(response)
+
+except Exception as e:
+    print(e)
+```
+
+
+```python
+#(Production)
+try:
+    get_request = {
+        "orderId": "ORD-SANDBOX-001"
+    }
+
+    response = sdk.get(get_request)
+    print(response)
+```
+
+### 4. Create a Payment (Production)
+
+```python
+try:
+    payment_request = {
+        "orderId": "ORD-LIVE-98765",
+        "amount": 5000,
+        "callbackUrl": "https://your-site.com/webhook/mmpay",
+        "customMessage": "Your Custom Message",
+        "items": [
+            {
+                "name": "Premium Subscription",
+                "amount": 5000,
+                "quantity": 1
+            }
+        ]
+    }
+
+    response = sdk.pay(payment_request)
+    print(response.get('url'))
+
+except Exception as e:
+    print(e)
+```
+
+### 5. Verify Callback (Webhook)
+
+When MyanMyanPay sends a callback to your `callbackUrl`[cite: 1], you must verify the request signature to ensure it is genuine. 
+
+**Incoming Headers**
+
+| Field Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `Content-Type` | `str` | Yes | `application/json` |
+| `X-Mmpay-Signature` | `str` | Yes | Generated HMAC signature |
+| `X-Mmpay-Nonce` | `str` | Yes | Unique nonce string |
+
+**Example Verification (Flask)**
+
+
+```python
+from flask import request
+
+@app.route('/webhook/mmpay', methods=['POST'])
+def mmpay_webhook():
+    payload_str = request.data.decode('utf-8')
+    nonce = request.headers.get('X-Mmpay-Nonce')
+    signature = request.headers.get('X-Mmpay-Signature')
+
+    try:
+        is_valid = sdk.verify_cb(payload_str, nonce, signature)
+        
+        if is_valid:
+            return "Verified", 200
+        else:
+            return "Invalid Signature", 400
+
+    except ValueError as e:
+        return str(e), 400
+```
+
+## Error Codes
+
+### API Key Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `KA0001` | Bearer Token Not Included |
+| `KA0002` | API Key Not 'LIVE' |
+| `KA0003` | Signature mismatch |
+| `KA0004` | Internal Server Error |
+| `KA0005` | IP Not whitelisted |
+| `429` | Rate limit hit (1000 req/min) |
+
+### JWT Layer (SERVER SDK)
+
+| Code | Description |
+| :--- | :--- |
+| `BA001` | `Btoken` nonce token missing |
+| `BA002` | `Btoken` nonce mismatch |
+
+## License
+
+MIT

mmpay_python_sdk-0.1.2/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup, find_packages
+import pathlib
+
+# Get the long description from the README file
+here = pathlib.Path(__file__).parent.resolve()
+long_description = (here / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name="mmpay-python-sdk",
+    version="0.1.2",
+    description="Python SDK for MyanMyanPay",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Naw Ing",
+    author_email="nawing@myanmyanpay.com",
+    url="https://github.com/nawing/MMPay-Python-SDK", # Link to your repo
+    packages=find_packages(),
+    install_requires=[
+        "requests",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Topic :: Office/Business :: Financial :: Point-Of-Sale",
+    ],
+    python_requires=">=3.6",
+)

mmpay_python_sdk-0.1.2/test/test_sdk.py

@@ -0,0 +1,76 @@
+import time
+import os
+import random
+import string
+from dotenv import load_dotenv
+
+# from mmpay import MMPaySDK
+from mmpay import MMPaySDK  
+
+# Load environment variables from .env file
+load_dotenv()
+
+def generate_secure_random_string(length: int) -> str:
+    """
+    Generates a random alphanumeric string.
+    """
+    # Using random.choices to generate a string of requested length
+    # This mimics the base36 behavior of the JS example
+    chars = string.ascii_lowercase + string.digits
+    return ''.join(random.choices(chars, k=length))
+
+def start():
+    """
+    Executes the payment call and measures network latency.
+    """
+    # Initialize SDK
+    # specific env keys matching your JS example
+    mmpay = MMPaySDK({
+        'appId': os.getenv('APP_ID', ''),
+        'publishableKey': os.getenv('PUB_KEY', ''),
+        'secretKey': os.getenv('SEC_KEY', ''),
+        'apiBaseUrl': os.getenv('BASEURL', '')
+    })
+
+    # Generate Order ID
+    order_id = generate_secure_random_string(6)
+
+    # Start Timer
+    # time.perf_counter() is the Python equivalent to performance.now()
+    start_time = time.perf_counter()
+
+    try:
+        payload = {
+            "orderId": order_id,
+            "amount": 1500,
+            "customMessage": "MyanMyanPay Is The Best",
+            "items": [{"name": "Items", "amount": 3000, "quantity": 1}]
+        }
+
+        # Execute Payment (Synchronous in Python version)
+        response = mmpay.sandbox_pay(payload)
+
+        # End Timer
+        end_time = time.perf_counter()
+        
+        # Calculate latency in milliseconds
+        latency_ms = (end_time - start_time) * 1000
+
+        print(f"\n--- Transaction Request Successful ---")
+        print(f"Order ID: {order_id}")
+        print(f"**Network Latency: {latency_ms:.3f} ms**")
+        print(f"Response: {response}")
+        print(f"------------------------------\n")
+
+    except Exception as error:
+        end_time = time.perf_counter()
+        latency_ms = (end_time - start_time) * 1000
+
+        print(f"\n--- Transaction Request Failed ---")
+        print(f"Order ID: {order_id}")
+        print(f"**Network Latency: {latency_ms:.3f} ms**")
+        print(f"Error Message: {str(error)}")
+        print(f"--------------------------\n")
+
+if __name__ == "__main__":
+    start()

mmpay_python_sdk-0.1.0/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: mmpay-python-sdk
-Version: 0.1.0
-Summary: Python SDK for MMPay (Ported from JS)
-Author: Your Name
-Requires-Python: >=3.6
-Requires-Dist: requests
-Dynamic: author
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary

mmpay_python_sdk-0.1.0/README.md

@@ -1,169 +0,0 @@
-
-# MMPay Python SDK
-
-A Python client library for integrating with the MMPay Payment Gateway. This SDK is a direct port of the official Node.js SDK, providing utilities for payment creation, handshake authentication, and callback verification.
-
-## Features
-
-- **Sandbox & Production Support**: dedicated methods for both environments.
-- **HMAC SHA256 Signing**: Automatic signature generation for request integrity.
-- **Callback Verification**: Utility to verify incoming webhooks from MMPay.
-- **Type Definitions**: Includes `TypedDict` definitions for clear payload structuring.
-
-## Installation
-
-Install the package via pip:
-
-```bash
-pip install mmpay-python-sdk
-```
-
-## Configuration
-
-To use the SDK, you need your **App ID**, **Publishable Key**, and **Secret Key** provided by the MMPay dashboard.
-
-Used when instantiating `MMPaySDK(options)`.
-
-| Parameter | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| `appId` | `str` | Yes | Your unique Application ID. |
-| `publishableKey` | `str` | Yes | Public key for authentication. |
-| `secretKey` | `str` | Yes | Private key used for signing requests (HMAC). |
-| `apiBaseUrl` | `str` | Yes | The base URL for the MMPay API. |
-
-```python
-from mmpay import MMPaySDK
-
-# Initialize the SDK
-options = {
-    "appId": "YOUR_APP_ID",
-    "publishableKey": "YOUR_PUBLISHABLE_KEY",
-    "secretKey": "YOUR_SECRET_KEY",
-    "apiBaseUrl": "[https://xxx.myanmyanpay.com](https://xxx.myanmyanpay.com)" # Replace with actual API Base URL [ Register With Us]
-}
-
-sdk = MMPaySDK(options)
-```
-
-
-
-
-## Usage
-
-### 1. Create a Payment (Sandbox)
-
-Use `sandbox_pay` to create a payment order in the Sandbox environment. This handles the handshake and signature generation automatically.
-
-
-### 1. Payment Request (`pay` / `sandbox_pay`)
-
-Passed to `sdk.pay(params)` or `sdk.sandbox_pay(params)`.
-
-| Parameter | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| `orderId` | `str` | Yes | Unique identifier for the order (e.g., "ORD-001"). |
-| `amount` | `number` | Yes | Total transaction amount. |
-| `items` | `List[Item]` | Yes | A list of items included in the order (see table below). |
-| `currency` | `str` | No | Currency code (e.g., "MMK", "USD"). |
-| `callbackUrl` | `str` | No | URL where the webhook callback will be sent. |
-
-### 2. Item Object
-
-Used inside the `items` list of a Payment Request.
-
-| Parameter | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| `name` | `str` | Yes | Name of the product or service. |
-| `amount` | `number` | Yes | Price per unit. |
-| `quantity` | `int` | Yes | Quantity of the item. |
-
-
-```python
-try:
-    payment_request = {
-        "orderId": "ORD-SANDBOX-001",
-        "amount": 5000,             # Amount in minor units (e.g., cents) or as required
-        "currency": "MMK",
-        "callbackUrl": "[https://your-site.com/webhook/mmpay](https://your-site.com/webhook/mmpay)",
-        "items": [
-            {
-                "name": "Premium Subscription",
-                "amount": 5000,
-                "quantity": 1
-            }
-        ]
-    }
-
-    response = sdk.sandbox_pay(payment_request)
-    print("Payment Response:", response)
-
-except Exception as e:
-    print("Error creating payment:", e)
-```
-
-### 2. Create a Payment (Production)
-
-For production environments, use the `pay` method.
-
-```python
-try:
-    payment_request = {
-        "orderId": "ORD-LIVE-98765",
-        "amount": 10000,
-        "items": [
-            {"name": "E-Commerce Item", "amount": 10000, "quantity": 1}
-        ]
-    }
-
-    # Helper automatically handles the handshake and signing
-    response = sdk.pay(payment_request)
-    print("Production Payment URL:", response.get('url'))
-
-except Exception as e:
-    print("Error:", e)
-```
-
-### 3. Verify Callback (Webhook)
-
-When MMPay sends a callback to your `callbackUrl`, you must verify the request signature to ensure it is genuine.
-
-### Callback Verification (`verify_cb`)
-
-| Parameter | Type | Description |
-| :--- | :--- | :--- |
-| `payload` | `str` | The **raw** JSON string body of the incoming request. |
-| `nonce` | `str` | The value of the `X-Mmpay-Nonce` header. |
-| `expected_signature` | `str` | The value of the `X-Mmpay-Signature` header. |
-
-**Example using Flask:**
-
-```python
-from flask import request
-
-@app.route('/webhook/mmpay', methods=['POST'])
-def mmpay_webhook():
-    # 1. Get the raw payload body as a string (Crucial for signature check)
-    payload_str = request.data.decode('utf-8') 
-    
-    # 2. Get headers
-    nonce = request.headers.get('X-Mmpay-Nonce')
-    signature = request.headers.get('X-Mmpay-Signature')
-
-    try:
-        # 3. Verify
-        is_valid = sdk.verify_cb(payload_str, nonce, signature)
-        
-        if is_valid:
-            # Process the order (e.g., mark as paid in DB)
-            return "Verified", 200
-        else:
-            return "Invalid Signature", 400
-
-    except ValueError as e:
-        return str(e), 400
-```
-
-
-## License
-
-MIT

mmpay_python_sdk-0.1.0/mmpay_python_sdk.egg-info/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: mmpay-python-sdk
-Version: 0.1.0
-Summary: Python SDK for MMPay (Ported from JS)
-Author: Your Name
-Requires-Python: >=3.6
-Requires-Dist: requests
-Dynamic: author
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary

mmpay_python_sdk-0.1.0/setup.py

@@ -1,13 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="mmpay-python-sdk",
-    version="0.1.0",
-    description="Python SDK for MMPay (Ported from JS)",
-    author="Your Name",
-    packages=find_packages(),
-    install_requires=[
-        "requests",
-    ],
-    python_requires=">=3.6",
-)

mmpay_python_sdk-0.1.0/test/test_sdk.py

@@ -1,21 +0,0 @@
-from mmpay import MMPaySDK
-
-# Initialize
-sdk = MMPaySDK({
-    "appId": "your_app_id",
-    "publishableKey": "your_pub_key",
-    "secretKey": "your_secret_key",
-    "apiBaseUrl": "https://api.mmpay.com" # Example URL
-})
-
-# Create a Payment (Sandbox)
-response = sdk.sandbox_pay({
-    "orderId": "ORD-123456789",
-    "amount": 1000,
-    "callbackUrl": "https://yoursite.com/callback",
-    "items": [
-        {"name": "Test Item", "amount": 1000, "quantity": 1}
-    ]
-})
-
-print(response)