bakong-v2 1.0.0__tar.gz

bakong_v2-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BAN Sothen
+
+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.

bakong_v2-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include bakong_v2/sdk/assets *

bakong_v2-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: bakong-v2
+Version: 1.0.0
+Summary: A Python package for Bakong KHQR payment integration using the BakongV2 API. (Unofficial)
+Home-page: https://bakong-v2.vercel.app
+Author: Lim Visa
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: image
+Requires-Dist: pillow; extra == "image"
+Requires-Dist: qrcode; extra == "image"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# Bakong-V2
+
+A Python package for Bakong KHQR payment integration powered by [BakongV2 API](https://bakong-v2.vercel.app).
+
+All requests go through the BakongV2 relay — no direct connection to NBC needed, no Cambodia IP required.
+
+## Installation
+
+```bash
+pip install bakong-v2
+```
+
+For QR image generation:
+
+```bash
+pip install "bakong-v2[image]"
+```
+
+## Quick Start
+
+```python
+from bakong_v2 import KHQR
+
+# Use your token from https://t.me/bakong_relay_bot
+khqr = KHQR("your_token_here")
+
+# Generate QR string (local, no API call)
+qr = khqr.create_qr(
+    bank_account="your_name@bank",
+    merchant_name="Your Name",
+    merchant_city="Phnom Penh",
+    amount=9800,
+    currency="KHR",
+)
+
+# Generate MD5 hash (local, no API call)
+md5 = khqr.generate_md5(qr)
+
+# Check payment status
+status = khqr.check_payment(md5)
+print(status)  # "PAID" or "UNPAID"
+
+# Get payment details
+info = khqr.get_payment(md5)
+print(info)
+
+# Generate deeplink
+link = khqr.generate_deeplink(
+    qr=qr,
+    appDeepLinkCallback="https://your-site.com/callback",
+    appIconUrl="https://your-site.com/logo.png",
+    appName="MyApp",
+)
+print(link)
+```
+
+## All Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_qr()` | Generate KHQR string locally |
+| `generate_md5()` | Compute MD5 hash of QR string |
+| `generate_deeplink()` | Generate Bakong deeplink |
+| `check_payment(md5)` | Check payment by MD5 → "PAID"/"UNPAID" |
+| `get_payment(md5)` | Get payment details by MD5 |
+| `check_payment_by_hash(hash)` | Check payment by transaction hash |
+| `get_payment_by_hash(hash)` | Get payment details by hash |
+| `check_payment_by_short_hash(hash, amount, currency)` | Check payment by short hash |
+| `get_payment_by_short_hash(hash, amount, currency)` | Get payment details by short hash |
+| `check_payment_by_instruction_ref(ref)` | Check payment by instruction ref |
+| `check_payment_by_external_ref(ref)` | Check payment by external ref |
+| `check_account(account_id)` | Check Bakong account info |
+| `check_bulk_payments(md5_list)` | Bulk check by MD5 list (max 50) |
+| `check_bulk_payments_by_hash(hash_list)` | Bulk check by hash list (max 50) |
+| `qr_image()` | Generate QR image (requires `[image]` extras) |
+
+## License
+
+MIT

bakong_v2-1.0.0/README.md

@@ -0,0 +1,79 @@
+# Bakong-V2
+
+A Python package for Bakong KHQR payment integration powered by [BakongV2 API](https://bakong-v2.vercel.app).
+
+All requests go through the BakongV2 relay — no direct connection to NBC needed, no Cambodia IP required.
+
+## Installation
+
+```bash
+pip install bakong-v2
+```
+
+For QR image generation:
+
+```bash
+pip install "bakong-v2[image]"
+```
+
+## Quick Start
+
+```python
+from bakong_v2 import KHQR
+
+# Use your token from https://t.me/bakong_relay_bot
+khqr = KHQR("your_token_here")
+
+# Generate QR string (local, no API call)
+qr = khqr.create_qr(
+    bank_account="your_name@bank",
+    merchant_name="Your Name",
+    merchant_city="Phnom Penh",
+    amount=9800,
+    currency="KHR",
+)
+
+# Generate MD5 hash (local, no API call)
+md5 = khqr.generate_md5(qr)
+
+# Check payment status
+status = khqr.check_payment(md5)
+print(status)  # "PAID" or "UNPAID"
+
+# Get payment details
+info = khqr.get_payment(md5)
+print(info)
+
+# Generate deeplink
+link = khqr.generate_deeplink(
+    qr=qr,
+    appDeepLinkCallback="https://your-site.com/callback",
+    appIconUrl="https://your-site.com/logo.png",
+    appName="MyApp",
+)
+print(link)
+```
+
+## All Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_qr()` | Generate KHQR string locally |
+| `generate_md5()` | Compute MD5 hash of QR string |
+| `generate_deeplink()` | Generate Bakong deeplink |
+| `check_payment(md5)` | Check payment by MD5 → "PAID"/"UNPAID" |
+| `get_payment(md5)` | Get payment details by MD5 |
+| `check_payment_by_hash(hash)` | Check payment by transaction hash |
+| `get_payment_by_hash(hash)` | Get payment details by hash |
+| `check_payment_by_short_hash(hash, amount, currency)` | Check payment by short hash |
+| `get_payment_by_short_hash(hash, amount, currency)` | Get payment details by short hash |
+| `check_payment_by_instruction_ref(ref)` | Check payment by instruction ref |
+| `check_payment_by_external_ref(ref)` | Check payment by external ref |
+| `check_account(account_id)` | Check Bakong account info |
+| `check_bulk_payments(md5_list)` | Bulk check by MD5 list (max 50) |
+| `check_bulk_payments_by_hash(hash_list)` | Bulk check by hash list (max 50) |
+| `qr_image()` | Generate QR image (requires `[image]` extras) |
+
+## License
+
+MIT

bakong_v2-1.0.0/bakong_v2/__init__.py

@@ -0,0 +1,3 @@
+from .khqr import KHQR
+
+__all__ = ["KHQR"]

bakong_v2-1.0.0/bakong_v2/khqr.py

@@ -0,0 +1,277 @@
+import json
+import warnings
+import urllib.request
+import urllib.parse
+from typing import Any
+from urllib.error import HTTPError
+
+from .sdk.crc import CRC
+from .sdk.mcc import MCC
+from .sdk.hash import HASH
+from .sdk.amount import Amount
+from .sdk.timestamp import TimeStamp
+from .sdk.image_tools import ImageTools
+from .sdk.country_code import CountryCode
+from .sdk.merchant_city import MerchantCity
+from .sdk.merchant_name import MerchantName
+from .sdk.point_of_initiation import PointOfInitiation
+from .sdk.transaction_currency import TransactionCurrency
+from .sdk.additional_data_field import AdditionalDataField
+from .sdk.payload_format_indicator import PayloadFormatIndicator
+from .sdk.global_unique_identifier import GlobalUniqueIdentifier
+
+from .sdk.version import __version__
+
+API_BASE = "https://bakong-v2.vercel.app/api/v2/bakong"
+
+
+class KHQR:
+    def __init__(self, token: str | None = None):
+        self.__crc = CRC()
+        self.__mcc = MCC()
+        self.__hash = HASH()
+        self.__amount = Amount()
+        self.__timestamp = TimeStamp()
+        self.__image_tools = ImageTools()
+        self.__country_code = CountryCode()
+        self.__merchant_city = MerchantCity()
+        self.__merchant_name = MerchantName()
+        self.__point_of_initiation = PointOfInitiation()
+        self.__transaction_currency = TransactionCurrency()
+        self.__additional_data_field = AdditionalDataField()
+        self.__payload_format_indicator = PayloadFormatIndicator()
+        self.__global_unique_identifier = GlobalUniqueIdentifier()
+        self.__token = token
+
+    def __check_token(self):
+        if not self.__token:
+            raise ValueError("Token is required. Get yours at https://t.me/bakong_relay_bot")
+
+    def __api_get(self, endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
+        self.__check_token()
+        params["token"] = self.__token
+        url = f"{API_BASE}{endpoint}?{urllib.parse.urlencode(params, doseq=True)}"
+        try:
+            with urllib.request.urlopen(url, timeout=15) as resp:
+                data = json.loads(resp.read().decode())
+        except HTTPError as e:
+            body = e.read().decode()
+            try:
+                err = json.loads(body)
+                msg = err.get("error", body)
+            except json.JSONDecodeError:
+                msg = body
+            raise ValueError(f"API error ({e.code}): {msg}")
+        except TimeoutError:
+            raise ValueError("API took too long to respond. Please try again later.")
+        except Exception as e:
+            raise ValueError(f"Failed to connect to API: {e}")
+        if isinstance(data, dict) and "error" in data:
+            raise ValueError(f"API error: {data['error']}")
+        return data
+
+    def __api_get_with_retry(self, endpoint: str, params: dict[str, Any], retries: int = 2) -> dict[str, Any]:
+        last_err = None
+        for attempt in range(retries + 1):
+            try:
+                return self.__api_get(endpoint, params)
+            except ValueError as e:
+                last_err = e
+                if attempt < retries:
+                    continue
+                raise last_err
+
+    def create_qr(
+        self,
+        bank_account: str,
+        merchant_name: str,
+        merchant_city: str,
+        amount: float,
+        currency: str,
+        store_label: str | None = None,
+        phone_number: str | None = None,
+        bill_number: str | None = None,
+        terminal_label: str | None = None,
+        static: bool = False,
+        expiration: int = 1
+    ) -> str:
+        if amount <= 0:
+            static = True
+        qr_data = self.__payload_format_indicator.value()
+        qr_data += self.__point_of_initiation.static() if static else self.__point_of_initiation.dynamic()
+        qr_data += self.__global_unique_identifier.value(bank_account)
+        qr_data += self.__mcc.value()
+        qr_data += self.__transaction_currency.value(currency)
+        if not static:
+            qr_data += self.__amount.value(amount)
+        qr_data += self.__country_code.value()
+        qr_data += self.__merchant_name.value(merchant_name)
+        qr_data += self.__merchant_city.value(merchant_city)
+        additional_data = self.__additional_data_field.value(
+            store_label=store_label,
+            phone_number=phone_number,
+            bill_number=bill_number,
+            terminal_label=terminal_label,
+        )
+        if additional_data:
+            qr_data += additional_data
+        qr_data += self.__timestamp.value(static, expiration)
+        qr_data += self.__crc.value(qr_data)
+        return qr_data
+
+    def generate_md5(self, qr: str) -> str:
+        return self.__hash.md5(qr)
+
+    def generate_deeplink(
+        self,
+        qr: str,
+        appDeepLinkCallback: str | None = None,
+        appIconUrl: str = "https://bakong.nbc.gov.kh/images/logo.svg",
+        appName: str = "MyAppName",
+        callback: str | None = None
+    ) -> str | None:
+        if callback is not None:
+            warnings.warn(
+                f"\n\n{'!'*31} DEPRECATION WARNING {'!'*31}\n"
+                f"Parameter 'callback' is deprecated in bakong-v2.\n"
+                f"Please update your code to use 'appDeepLinkCallback' instead.\n"
+                f"{'!'*83}\n",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            if appDeepLinkCallback is None:
+                appDeepLinkCallback = callback
+        if appDeepLinkCallback is None:
+            appDeepLinkCallback = "https://bakong.nbc.org.kh"
+
+        params = {
+            "qr": qr,
+            "AppName": appName,
+            "AppIconUrl": appIconUrl,
+            "callback": appDeepLinkCallback,
+        }
+        data = self.__api_get_with_retry("/generate-deeplink", params)
+        if data.get("responseCode") == 0:
+            d = data.get("data")
+            if isinstance(d, dict):
+                return d.get("shortLink") or d.get("fullLink")
+        return None
+
+    def check_payment(self, md5: str) -> str:
+        params = {"md5": md5}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            return "PAID"
+        return "UNPAID"
+
+    def get_payment(self, md5: str) -> dict[str, Any] | None:
+        params = {"md5": md5}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            d = data.get("data")
+            return d if isinstance(d, dict) else None
+        return None
+
+    def check_account(self, account_id: str) -> dict[str, Any] | None:
+        params = {"accountId": account_id}
+        data = self.__api_get_with_retry("/check-account", params)
+        if data.get("responseCode") == 0:
+            d = data.get("data")
+            return d if isinstance(d, dict) else None
+        return None
+
+    def check_payment_by_hash(self, hash: str) -> str:
+        params = {"hash": hash}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            return "PAID"
+        return "UNPAID"
+
+    def get_payment_by_hash(self, hash: str) -> dict[str, Any] | None:
+        params = {"hash": hash}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            d = data.get("data")
+            return d if isinstance(d, dict) else None
+        return None
+
+    def check_payment_by_short_hash(self, hash: str, amount: float, currency: str) -> str:
+        params = {"hash": hash, "amount": amount, "currency": currency}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            return "PAID"
+        return "UNPAID"
+
+    def get_payment_by_short_hash(self, hash: str, amount: float, currency: str) -> dict[str, Any] | None:
+        params = {"hash": hash, "amount": amount, "currency": currency}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            d = data.get("data")
+            return d if isinstance(d, dict) else None
+        return None
+
+    def check_payment_by_instruction_ref(self, instruction_ref: str) -> str:
+        params = {"instructionRef": instruction_ref}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            return "PAID"
+        return "UNPAID"
+
+    def check_payment_by_external_ref(self, external_ref: str) -> str:
+        params = {"externalRef": external_ref}
+        data = self.__api_get_with_retry("/check-payment", params)
+        if data.get("responseCode") == 0:
+            return "PAID"
+        return "UNPAID"
+
+    def check_bulk_payments(self, md5_list: list[str]) -> list[str]:
+        if len(md5_list) > 50:
+            raise ValueError("The md5_list exceeds the allowed limit of 50 hashes per request.")
+        params = {"md5": md5_list}
+        data = self.__api_get_with_retry("/check-payment-list", params)
+        data_list = data.get("data")
+        if not isinstance(data_list, list):
+            return []
+        paid = []
+        for item in data_list:
+            if isinstance(item, dict) and item.get("status") == "SUCCESS":
+                md5 = item.get("md5")
+                if isinstance(md5, str):
+                    paid.append(md5)
+        return paid
+
+    def check_bulk_payments_by_hash(self, hash_list: list[str]) -> list[str]:
+        if len(hash_list) > 50:
+            raise ValueError("The hash_list exceeds the allowed limit of 50 hashes per request.")
+        params = {"hash": hash_list}
+        data = self.__api_get_with_retry("/check-payment-list", params)
+        data_list = data.get("data")
+        if not isinstance(data_list, list):
+            return []
+        paid = []
+        for item in data_list:
+            if isinstance(item, dict) and item.get("status") == "SUCCESS":
+                h = item.get("hash")
+                if isinstance(h, str):
+                    paid.append(h)
+        return paid
+
+    def qr_image(
+        self, qr: str,
+        format: str = "png",
+        output_path: str | None = None,
+    ) -> str | bytes:
+        result = self.__image_tools.generate(qr)
+        f = format.lower()
+        if f in ("jpeg", "jpg"):
+            return result.to_jpeg(output_path)
+        elif f == "webp":
+            return result.to_webp(output_path)
+        elif f == "bytes":
+            return result.to_bytes()
+        elif f == "base64":
+            return result.to_base64()
+        elif f == "base64_uri":
+            return result.to_data_uri()
+        else:
+            return result.to_png(output_path)

bakong_v2-1.0.0/bakong_v2/sdk/__init__.py

@@ -0,0 +1,37 @@
+from .emv import EMV
+from .crc import CRC
+from .mcc import MCC
+from .hash import HASH
+from .amount import Amount
+from .timestamp import TimeStamp
+from .emv_parser import EMVParser
+from .image_tools import ImageTools
+from .country_code import CountryCode
+from .merchant_city import MerchantCity
+from .merchant_name import MerchantName
+from .point_of_initiation import PointOfInitiation
+from .transaction_currency import TransactionCurrency
+from .additional_data_field import AdditionalDataField
+from .global_unique_identifier import GlobalUniqueIdentifier
+from .payload_format_indicator import PayloadFormatIndicator
+from .version import __version__
+
+__all__ = [
+    "EMV",
+    "CRC",
+    "MCC",
+    "HASH",
+    "Amount",
+    "TimeStamp",
+    "EMVParser",
+    "ImageTools",
+    "CountryCode",
+    "MerchantCity",
+    "MerchantName",
+    "PointOfInitiation",
+    "TransactionCurrency",
+    "AdditionalDataField",
+    "GlobalUniqueIdentifier",
+    "PayloadFormatIndicator",
+    "__version__"
+]

bakong_v2-1.0.0/bakong_v2/sdk/additional_data_field.py

@@ -0,0 +1,94 @@
+from .emv import EMV
+
+# Initialize EMV instance
+emv = EMV()
+
+class AdditionalDataField:
+    def __init__(self):
+        """
+        Initialize the AdditionalDataField class with settings from the EMV configuration.
+        """
+        self.__additional_data_tag = emv.addtion_data_tag
+        self.__store_label_tag = emv.store_label
+        self.__mobile_number_tag = emv.addition_data_field_mobile_number
+        self.__bill_number_tag = emv.billnumber_tag
+        self.__terminal_label_tag = emv.terminal_label
+        
+        # Maximum lengths according to EMVCo / Bakong spec
+        self.__store_label_max = emv.invalid_length_store_label
+        self.__mobile_max = emv.invalid_length_mobile_number
+        self.__bill_max = emv.invalid_length_bill_number
+        self.__terminal_max = emv.invalid_length_terminal_label
+
+    def __format_field(self, tag: str, value: str) -> str:
+        """Format a single sub-field: TAG + LENGTH (02) + VALUE"""
+        value_str = str(value).strip()
+        if not value_str:
+            return ""
+        length = f"{len(value_str):02d}"
+        return f"{tag}{length}{value_str}"
+
+    def __validate_length(self, value: str, max_length: int, field_name: str):
+        """
+        Validate the length of a field value.
+
+        :param value: The value to be validated.
+        :param field_name: The name of the field for error reporting.
+        :raises ValueError: If the value exceeds the maximum allowed length.
+        """
+        if len(value) > max_length:
+            raise ValueError(f"{field_name} cannot exceed {max_length} characters. Your input length: {len(value)} characters.")
+    
+    def value(
+        self,
+        store_label: str | None = None,
+        phone_number: str | None = None,
+        bill_number: str | None = None,
+        terminal_label: str | None = None,
+        ) -> str:
+        """
+        Combine all formatted values into a single string with a length prefix.
+
+        :param store_label: The store label.
+        :param phone_number: The phone number.
+        :param bill_number: The bill number.
+        :param terminal_label: The terminal label.
+        :return: Combined formatted string with length prefix.
+        """
+        sub_fields = []
+
+        # Store Label (usually Tag 03)
+        if store_label:
+            self.__validate_length(store_label, self.__store_label_max, "Store label")
+            sub_fields.append(self.__format_field(self.__store_label_tag, store_label))
+
+        # Phone Number (usually Tag 04) - with Khmer phone normalization
+        if phone_number:
+            digits = ''.join(c for c in str(phone_number) if c.isdigit())
+            if digits.startswith('855'):
+                digits = digits[3:]
+            if not digits.startswith('0'):
+                digits = '0' + digits
+
+            self.__validate_length(digits, self.__mobile_max, "Phone number")
+            sub_fields.append(self.__format_field(self.__mobile_number_tag, digits))
+
+        # Bill Number (usually Tag 05)
+        if bill_number:
+            self.__validate_length(bill_number, self.__bill_max, "Bill number")
+            sub_fields.append(self.__format_field(self.__bill_number_tag, bill_number))
+
+        # Terminal Label (usually Tag 07)
+        if terminal_label:
+            self.__validate_length(terminal_label, self.__terminal_max, "Terminal label")
+            sub_fields.append(self.__format_field(self.__terminal_label_tag, terminal_label))
+
+        if not sub_fields:
+            # No additional data → return empty (do not include tag 62 at all)
+            return ""
+
+        combined = "".join(sub_fields)
+        total_length = f"{len(combined):02d}"
+
+        # Final format: 62 + LL + subfields
+        return f"{self.__additional_data_tag}{total_length}{combined}"

bakong_v2-1.0.0/bakong_v2/sdk/amount.py

@@ -0,0 +1,39 @@
+from .emv import EMV
+
+emv = EMV()
+
+class Amount:
+    def __init__(self):
+        self.__transaction_amount = emv.transaction_amount  # "54"
+        self.__max_length = emv.invalid_length_amount
+        
+    def value(self, amount: float | int | str) -> str:
+        """
+        Get the formatted amount value.
+
+        :param amount: The transaction amount to be formatted.
+        :return: Formatted string including transaction amount tag, length, and amount.
+        """
+        if not isinstance(amount, (int, float, str)):
+            raise ValueError("Amount must be a number or numeric string")
+
+        try:
+            amount_float = float(amount)
+        except ValueError:
+            raise ValueError(f"Invalid amount value: {amount}. Amount must be a number or a string representing a number.")
+
+        # Format amount (no trailing zeros)
+        amount_str = f"{amount_float:.2f}".rstrip("0").rstrip(".")
+
+        # EMV length = length of VALUE ONLY
+        length_of_amount = len(amount_str)
+
+        if length_of_amount > self.__max_length:
+            raise ValueError(
+                f"Formatted Amount exceeds maximum length of {self.__max_length} characters."
+                f"Your input length: {length_of_amount} characters."
+            )
+
+        length_str = str(length_of_amount).zfill(2)
+
+        return f"{self.__transaction_amount}{length_str}{amount_str}"