mmpay-python-sdk 0.1.0__tar.gz

mmpay_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,169 @@
+
+# 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/__init__.py

@@ -0,0 +1,3 @@
+from .client import MMPaySDK
+
+__all__ = ["MMPaySDK"]

mmpay_python_sdk-0.1.0/mmpay/client.py

@@ -0,0 +1,224 @@
+import time
+import json
+import hmac
+import hashlib
+import requests
+from typing import List, Optional, TypedDict, Dict, Any
+
+# --- Type Definitions to mirror your Interfaces ---
+
+class Item(TypedDict):
+    name: str
+    amount: float
+    quantity: int
+
+class PaymentRequest(TypedDict):
+    orderId: str
+    amount: float
+    items: List[Item]
+    currency: Optional[str]
+    callbackUrl: Optional[str]
+
+class XPaymentRequest(PaymentRequest, total=False):
+    appId: str
+    nonce: str
+
+class HandShakeRequest(TypedDict):
+    orderId: str
+    nonce: str
+
+class SDKOptions(TypedDict):
+    appId: str
+    publishableKey: str
+    secretKey: str
+    apiBaseUrl: str
+
+# --- Main SDK Class ---
+
+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']
+        self._api_base_url = options['apiBaseUrl'].rstrip('/')
+        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'),
+            string_to_sign.encode('utf-8'),
+            hashlib.sha256
+        ).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]:
+        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)
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            '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()
+            data = response.json()
+            if 'token' in data:
+                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}
+
+    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 = {
+            "appId": self._app_id,
+            "nonce": nonce,
+            "amount": params['amount'],
+            "orderId": params['orderId'],
+            "items": params['items'],
+        }
+        if 'callbackUrl' in params:
+            xpayload['callbackUrl'] = params['callbackUrl']
+        if 'currency' in params:
+            xpayload['currency'] = params['currency']
+
+        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']})
+        if 'error' in handshake_res:
+            return handshake_res
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            'X-Mmpay-Btoken': self._btoken,
+            '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": response.text if response else None}
+
+    # --- Production Methods ---
+
+    def handshake(self, payload: HandShakeRequest) -> Dict[str, Any]:
+        endpoint = f"{self._api_base_url}/payments/handshake"
+        nonce = self._get_nonce()
+        
+        body_string = self._json_stringify(payload)
+        signature = self._generate_signature(body_string, nonce)
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            '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()
+            data = response.json()
+            if 'token' in data:
+                self._btoken = data['token']
+            return data
+        except requests.exceptions.RequestException as e:
+            return {"error": str(e), "details": response.text if response else None}
+
+    def pay(self, params: PaymentRequest) -> Dict[str, Any]:
+        endpoint = f"{self._api_base_url}/payments/create"
+        nonce = self._get_nonce()
+
+        xpayload: XPaymentRequest = {
+            "appId": self._app_id,
+            "nonce": nonce,
+            "amount": params['amount'],
+            "orderId": params['orderId'],
+            "items": params['items'],
+        }
+        if 'callbackUrl' in params:
+            xpayload['callbackUrl'] = params['callbackUrl']
+        if 'currency' in params:
+            xpayload['currency'] = params['currency']
+
+        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']})
+        if 'error' in handshake_res:
+            return handshake_res
+
+        headers = {
+            'Authorization': f"Bearer {self._publishable_key}",
+            'X-Mmpay-Btoken': self._btoken,
+            '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": response.text if response else None}
+
+    # --- Verification ---
+
+    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.")
+
+        string_to_sign = f"{nonce}.{payload}"
+        generated_signature = hmac.new(
+            self._secret_key.encode('utf-8'),
+            string_to_sign.encode('utf-8'),
+            hashlib.sha256
+        ).hexdigest()
+
+        if generated_signature != expected_signature:
+            print(f"Signature mismatch: gen={generated_signature}, exp={expected_signature}")
+            return False
+        
+        return True

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

@@ -0,0 +1,11 @@
+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/mmpay_python_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+setup.py
+mmpay/__init__.py
+mmpay/client.py
+mmpay_python_sdk.egg-info/PKG-INFO
+mmpay_python_sdk.egg-info/SOURCES.txt
+mmpay_python_sdk.egg-info/dependency_links.txt
+mmpay_python_sdk.egg-info/requires.txt
+mmpay_python_sdk.egg-info/top_level.txt
+test/test_sdk.py

mmpay_python_sdk-0.1.0/mmpay_python_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mmpay_python_sdk-0.1.0/mmpay_python_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

mmpay_python_sdk-0.1.0/mmpay_python_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+mmpay

mmpay_python_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mmpay_python_sdk-0.1.0/setup.py

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,21 @@
+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)