"""Bankemes Merchant API client for Python 3.8+ (standard library only). Server-side only: a Merchant API token must never reach a browser. """ from __future__ import annotations import hashlib import hmac import json import re import time import urllib.error import urllib.parse import urllib.request import uuid from typing import Any, Dict, List, Optional, Union __version__ = "1.0.0" __all__ = ["Bankemes", "BankemesError", "verify_webhook_signature", "construct_webhook_event"] _TOKEN = re.compile(r"^bms_(live|test)_[A-Za-z0-9]{8}_[A-Za-z0-9_-]{43}$") class BankemesError(Exception): """API error: status (0 = network), code (e.g. ORDER_ALREADY_EXISTS), request_id, details.""" def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None, details: Optional[Dict[str, Any]] = None): super().__init__(message) self.status = status self.code = code self.request_id = request_id self.details = details or {} class _Resource: def __init__(self, client: "Bankemes"): self._c = client class Bankemes: """Client. `sandbox` is True for a bms_test_ token (no bank; outcomes are simulated).""" def __init__(self, token: str, base_url: str = "https://bankemes.kz", max_retries: int = 2, timeout: float = 20.0, opener=None): if not isinstance(token, str) or not _TOKEN.match(token): raise ValueError("Bankemes: token must be a bms_live_... or bms_test_... Merchant API token.") self._token = token self.sandbox = token.startswith("bms_test_") self.base_url = base_url.rstrip("/") self.max_retries = max_retries self.timeout = timeout self._open = opener or urllib.request.urlopen self.payments = _Payments(self) self.remote_invoices = _RemoteInvoices(self) self.refunds = _Refunds(self) self.payment_links = _PaymentLinks(self) self.customers = _Customers(self) self.schedules = _Schedules(self) def request(self, method: str, path: str, body: Any = None, idempotency_key: Optional[str] = None, idempotent: bool = True) -> Dict[str, Any]: # A POST is retried only with an Idempotency-Key, and with the same key every time. key = (idempotency_key or "sdk-" + str(uuid.uuid4())) if method == "POST" and idempotent else None safe = method == "GET" or key is not None data = None if body is None else json.dumps(body).encode("utf-8") headers = {"Authorization": "Bearer " + self._token, "Accept": "application/json", "User-Agent": "bankemes-python/" + __version__} if data is not None: headers["Content-Type"] = "application/json" if key: headers["Idempotency-Key"] = key attempt = 0 while True: req = urllib.request.Request(self.base_url + path, data=data, method=method, headers=headers) try: with self._open(req, timeout=self.timeout) as res: text = res.read().decode("utf-8") return json.loads(text) if text else {} except urllib.error.HTTPError as e: text = e.read().decode("utf-8", "replace") retryable = e.code == 429 or e.code >= 500 if safe and retryable and attempt < self.max_retries: after = e.headers.get("Retry-After") if e.headers else None time.sleep(min(float(after), 30.0) if after and after.isdigit() else 0.3 * 2 ** attempt) attempt += 1 continue try: err = (json.loads(text) if text else {}).get("error", {}) except ValueError: err = {} details = {k: v for k, v in err.items() if k not in ("code", "message", "request_id")} raise BankemesError(e.code, err.get("code", "HTTP_ERROR"), err.get("message", "HTTP %d" % e.code), err.get("request_id"), details) from None except (urllib.error.URLError, TimeoutError, ConnectionError) as e: if safe and attempt < self.max_retries: time.sleep(0.3 * 2 ** attempt) attempt += 1 continue raise BankemesError(0, "NETWORK_ERROR", str(e)) from None @staticmethod def _q(params: Optional[Dict[str, Any]]) -> str: items = {k: v for k, v in (params or {}).items() if v is not None} return ("?" + urllib.parse.urlencode(items)) if items else "" @staticmethod def _id(v: str) -> str: return urllib.parse.quote(v, safe="") class _Payments(_Resource): def create(self, params: Dict[str, Any], idempotency_key: Optional[str] = None): """Checkout payment: order_id, amount, description, success_url, cancel_url, metadata, items.""" return self._c.request("POST", "/api/v1/payments", params, idempotency_key) def retrieve(self, payment_id: str): return self._c.request("GET", "/api/v1/payments/" + self._c._id(payment_id)) def list(self, **params): return self._c.request("GET", "/api/v1/payments" + self._c._q(params)) def cancel(self, payment_id: str): return self._c.request("POST", "/api/v1/payments/%s/cancel" % self._c._id(payment_id), {}, idempotent=False) def events(self, payment_id: str): return self._c.request("GET", "/api/v1/payments/%s/events" % self._c._id(payment_id)) class _RemoteInvoices(_Resource): def create(self, params: Dict[str, Any], idempotency_key: Optional[str] = None): """Kaspi invoice to the buyer's phone: order_id, phone, amount, description.""" return self._c.request("POST", "/api/v1/invoices/remote", params, idempotency_key) def retrieve(self, invoice_id: str): return self._c.request("GET", "/api/v1/invoices/remote/" + self._c._id(invoice_id)) def cancel(self, invoice_id: str): return self._c.request("POST", "/api/v1/invoices/remote/%s/cancel" % self._c._id(invoice_id), {}, idempotent=False) class _Refunds(_Resource): def create(self, payment_id: str, amount: Optional[int] = None, reason: str = "", idempotency_key: Optional[str] = None): """Full (amount=None) or partial refund. status 'unknown' (HTTP 202): never retry, check Kaspi Pay.""" body: Dict[str, Any] = {"reason": reason} if amount is not None: body["amount"] = amount return self._c.request("POST", "/api/v1/payments/%s/refunds" % self._c._id(payment_id), body, idempotency_key) def list(self, payment_id: str): return self._c.request("GET", "/api/v1/payments/%s/refunds" % self._c._id(payment_id)) class _PaymentLinks(_Resource): def create(self, params: Dict[str, Any]): return self._c.request("POST", "/api/v1/payment-links", params, idempotent=False) def list(self): return self._c.request("GET", "/api/v1/payment-links") def retrieve(self, link_id: str): return self._c.request("GET", "/api/v1/payment-links/" + self._c._id(link_id)) def revoke(self, link_id: str): return self._c.request("POST", "/api/v1/payment-links/%s/revoke" % self._c._id(link_id), {}, idempotent=False) def stats(self, link_id: str): return self._c.request("GET", "/api/v1/payment-links/%s/stats" % self._c._id(link_id)) class _Customers(_Resource): def create(self, params: Dict[str, Any]): return self._c.request("POST", "/api/v1/customers", params, idempotent=False) def list(self, **params): return self._c.request("GET", "/api/v1/customers" + self._c._q(params)) def retrieve(self, customer_id: str): return self._c.request("GET", "/api/v1/customers/" + self._c._id(customer_id)) def invoice(self, customer_id: str, params: Dict[str, Any]): return self._c.request("POST", "/api/v1/customers/%s/invoices" % self._c._id(customer_id), params, idempotent=False) class _Schedules(_Resource): def create(self, params: Dict[str, Any]): return self._c.request("POST", "/api/v1/schedules", params, idempotent=False) def retrieve(self, schedule_id: str): return self._c.request("GET", "/api/v1/schedules/" + self._c._id(schedule_id)) def pause(self, schedule_id: str): return self._c.request("POST", "/api/v1/schedules/%s/pause" % self._c._id(schedule_id), {}, idempotent=False) def resume(self, schedule_id: str): return self._c.request("POST", "/api/v1/schedules/%s/resume" % self._c._id(schedule_id), {}, idempotent=False) def cancel(self, schedule_id: str): return self._c.request("POST", "/api/v1/schedules/%s/cancel" % self._c._id(schedule_id), {}, idempotent=False) def verify_webhook_signature(raw_body: Union[bytes, str], header: Optional[str], secret: Union[str, List[str]], tolerance: int = 300, now: Optional[float] = None) -> bool: """Checks Bankemes-Signature on the RAW body: t=,v1=.")>[,v1=...].""" if not header: return False fields = [p.strip().split("=", 1) for p in header.split(",")] try: t = int(next(v for k, v in (f for f in fields if len(f) == 2) if k == "t")) except (StopIteration, ValueError): return False if abs(int(now if now is not None else time.time()) - t) > tolerance: return False body = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8") for s in [secret] if isinstance(secret, str) else secret: expected = hmac.new(s.encode("utf-8"), str(t).encode() + b"." + body, hashlib.sha256).hexdigest() for f in fields: if len(f) == 2 and f[0] == "v1" and hmac.compare_digest(f[1], expected): return True return False def construct_webhook_event(raw_body: Union[bytes, str], header: Optional[str], secret: Union[str, List[str]], tolerance: int = 300) -> Dict[str, Any]: """Verifies and parses a webhook; raises BankemesError(SIGNATURE_INVALID) otherwise.""" if not verify_webhook_signature(raw_body, header, secret, tolerance): raise BankemesError(400, "SIGNATURE_INVALID", "Bankemes-Signature does not match.") return json.loads(raw_body if isinstance(raw_body, str) else raw_body.decode("utf-8"))