"""KazPayment SDK для Python 3.8+ — только стандартная библиотека. Документация API: https://kazpayment.kz/docs/api """ import hashlib import hmac import http.client import json import time import urllib.error import urllib.parse import urllib.request __all__ = ["KazPayment", "KazPaymentError", "verify_webhook_signature", "parse_webhook"] __version__ = "1.3.0" DEFAULT_BASE = "https://kazpayment.kz/api/v1" class KazPaymentError(Exception): """Ошибка API: ``status`` — HTTP, ``code`` — машинный код из таблицы «Ошибки» документации.""" def __init__(self, message, status=0, code="network", retry_after_seconds=None, body=None): super().__init__(message) self.status = status self.code = code self.retry_after_seconds = retry_after_seconds self.body = body # Отличает «не передано» от «передано None» там, где None — осмысленное значение. _UNSET = object() def _compact(d): return {k: v for k, v in d.items() if v is not None} def _ref(value): return urllib.parse.quote(str(value), safe="") class KazPayment: """Клиент API. ``api_key`` — ключ интеграции из кабинета («Подключения» → «Интеграция»).""" def __init__(self, api_key, base_url=DEFAULT_BASE, timeout=15.0, max_retries=2, opener=None): if not api_key: raise ValueError("KazPayment: нужен api_key — ключ интеграции из кабинета") self.api_key = api_key self.base_url = base_url.rstrip("/") self.timeout = timeout self.max_retries = max_retries self._open = opener or urllib.request.urlopen def request(self, method, path, body=None, idempotent=None, timeout=None): """Запрос к API. Сам повторяет только безопасное: ``429 rate_limited`` — после ``retryAfterSeconds``; сетевой сбой — для GET и для вызовов, идемпотентных по своему номеру (заказ, возврат, код с ключом).""" if idempotent is None: idempotent = method == "GET" data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None attempt = 0 while True: req = urllib.request.Request(self.base_url + path, data=data, method=method) req.add_header("Authorization", "Bearer " + self.api_key) req.add_header("Accept", "application/json") if data is not None: req.add_header("Content-Type", "application/json") try: with self._open(req, timeout=timeout or self.timeout) as res: raw = res.read() return self._decode(raw, ok=True) except urllib.error.HTTPError as err: payload = self._decode(err.read(), ok=False) or {} code = payload.get("code") or "http_%d" % err.code if err.code == 429 and code == "rate_limited" and attempt < self.max_retries: time.sleep(max(1, int(payload.get("retryAfterSeconds") or 1))) attempt += 1 continue raise KazPaymentError( payload.get("error") or "HTTP %d" % err.code, status=err.code, code=code, retry_after_seconds=payload.get("retryAfterSeconds"), body=payload, ) from None except (urllib.error.URLError, OSError, http.client.HTTPException) as err: if idempotent and attempt < self.max_retries: time.sleep(0.5 * 2 ** attempt) attempt += 1 continue raise KazPaymentError("KazPayment недоступен: %s" % err) from None @staticmethod def _decode(raw, ok): if not raw: return {} text = raw.decode("utf-8", errors="replace") try: return json.loads(text) except ValueError: # Не JSON при успехе — прокси или страница защиты: молчаливый # «успех» без payUrl хуже ошибки. if ok: raise KazPaymentError("KazPayment ответил не JSON — вероятно, прокси между вами и сервисом", status=200, code="bad_response", body=text[:500]) from None return {"error": text[:500]} def whoami(self): return self.request("GET", "/whoami") def kaspi_status(self): return self.request("GET", "/kaspi") def get_metrics(self, part=None, month=None): """Показатели бизнеса: ``part`` — раздел (без него — оплаты), ``month`` — ``ГГГГ-ММ``.""" path = "/metrics" + ("/" + _ref(part) if part else "") return self.request("GET", path + ("?month=" + _ref(month) if month else "")) def set_metrics_digest(self, enabled): """Включить или выключить недельную сводку показателей.""" return self.request("PUT", "/metrics/digest", {"enabled": enabled}, idempotent=True) # ─── Заказы ─── def create_order(self, external_ref, amount, comment=None, customer_phone=None, return_url=None, auto_invoice=None, invoice_text=None): """Завести заказ и получить ``payUrl``. Повтор с тем же номером вернёт тот же заказ.""" body = _compact({ "external_ref": external_ref, "amount": amount, "comment": comment, "customer_phone": customer_phone, "return_url": return_url, "auto_invoice": auto_invoice, "invoice_text": invoice_text, }) return self.request("POST", "/orders", body, idempotent=True) def get_order(self, external_ref): return self.request("GET", "/orders/" + _ref(external_ref)) def refund_order(self, external_ref, amount, reason, refund_ref): """Вернуть деньги. ``refund_ref`` — номер возврата в вашем учёте: по нему повтор безопасен.""" body = {"amount": amount, "reason": reason, "refund_ref": refund_ref} # Касса отвечает до минуты (docs/api.md, «Исход неизвестен»). return self.request("POST", "/orders/%s/refund" % _ref(external_ref), body, idempotent=True, timeout=max(self.timeout, 75.0)) def cancel_order(self, external_ref, reason=None): """Отменить неоплаченный заказ. Повтор безопасен: уже отменённый — успех с ``repeated``.""" return self.request("POST", "/orders/%s/cancel" % _ref(external_ref), _compact({"reason": reason}), idempotent=True) def send_invoice(self, external_ref, phone): """Выставить счёт по заказу в приложение Kaspi покупателя по номеру. Прежний счёт уже оплачен — ошибка ``invoice_already_paid``: снова платить не надо. Kaspi не принял (на номере нет Kaspi) — ошибка ``invoice_rejected``. При обрыве не повторяется: второй вызов выставил бы счёт заново — сперва посмотрите ``get_order``. """ return self.request("POST", "/orders/%s/remote" % _ref(external_ref), {"phone": phone}, idempotent=False) def notify_order(self, external_ref, channel="whatsapp", link=None, amount=None, lang=None): body = _compact({"channel": channel, "link": link, "amount": amount, "lang": lang}) return self.request("POST", "/orders/%s/notify" % _ref(external_ref), body) # ─── Абонементы ─── def list_plans(self): return self.request("GET", "/plans") def create_payer(self, phone, full_name=None, email=None, lang=None): body = _compact({"phone": phone, "full_name": full_name, "email": email, "lang": lang}) # Без автоповтора при обрыве: второй запрос, пока идёт первый, упрётся в гонку. return self.request("POST", "/payers", body) def create_subscription(self, payer_phone, plan_id, starts_on=None, ends_on=None, amount=None): body = _compact({ "payer_phone": payer_phone, "plan_id": plan_id, "starts_on": starts_on, "ends_on": ends_on, "amount": amount, }) # Без автоповтора при обрыве: пока первый запрос не закончился, второй # мог бы завести вторую подписку — сперва list_subscriptions. return self.request("POST", "/subscriptions", body) def list_subscriptions(self, payer_phone=None): q = "?payer_phone=" + _ref(payer_phone) if payer_phone else "" return self.request("GET", "/subscriptions" + q) def set_subscription_status(self, subscription_id, status): """``active``, ``paused`` или ``cancelled``.""" return self.request("PUT", "/subscriptions/" + _ref(subscription_id), {"status": status}) # ─── Настройки бизнеса (то же, что в кабинете) ─── def get_unpaid_policy(self): """Что делать, когда клиент не оплатил подписку: ``{mode, days, missed_periods_max, reissue_pause_days}``.""" return self.request("GET", "/settings/unpaid-policy") def set_unpaid_policy(self, mode=None, days=None, missed_periods_max=_UNSET, reissue_pause_days=None): """Сменить режим неоплаты и/или предел долга за перерыв. ``mode``: ``debt``, ``merge``, ``forgive`` (нужен ``days``), ``cancel`` (нужен ``days``). ``missed_periods_max=None`` — выключить подсчёт долга; не передан — не меняется. ``reissue_pause_days`` — дней до нового счёта, если прежний исчез из Kaspi, 0 — сразу. Повтор безопасен. """ body = _compact({"mode": mode, "days": days}) if missed_periods_max is not _UNSET: body["missed_periods_max"] = missed_periods_max if reissue_pause_days is not None: body["reissue_pause_days"] = reissue_pause_days return self.request("PUT", "/settings/unpaid-policy", body, idempotent=True) def get_plan_unpaid_policy(self, plan_id): """Правило неоплаты тарифа: ``{own: False}`` — общее правило тарифов.""" return self.request("GET", "/plans/%s/unpaid-policy" % _ref(plan_id)) def set_plan_unpaid_policy(self, plan_id, own, mode=None, days=None, missed_periods_max=None): """Отдельное правило тарифа (``own=True`` + ``mode``…) или общее (``own=False``). Повтор безопасен.""" body = {"own": True, "mode": mode, "days": days, "missed_periods_max": missed_periods_max} if own else {"own": False} return self.request("PUT", "/plans/%s/unpaid-policy" % _ref(plan_id), body, idempotent=True) def get_auto_billing(self): """Стоят ли счета по расписанию на паузе: ``{paused, subscriptions, kassa_connected}``.""" return self.request("GET", "/settings/auto-billing") def start_auto_billing(self): """«Начать выставлять счета». Повтор безопасен.""" return self.request("POST", "/settings/auto-billing/start", idempotent=True) # ─── Сообщения ─── def send_sms(self, phone, text, kind=None): return self.request("POST", "/sms", _compact({"phone": phone, "text": text, "kind": kind})) def whatsapp_order(self, phone, order, state, lang=None): return self.request("POST", "/whatsapp/order", _compact({"phone": phone, "order": order, "state": state, "lang": lang})) def whatsapp_cart(self, phone, items, total, lang=None): return self.request("POST", "/whatsapp/cart", _compact({"phone": phone, "items": items, "total": total, "lang": lang})) def request_otp(self, phone, idempotency_key=None): body = _compact({"phone": phone, "idempotency_key": idempotency_key}) return self.request("POST", "/otp/request", body, idempotent=idempotency_key is not None) def verify_otp(self, request_id, code): return self.request("POST", "/otp/verify", {"requestId": request_id, "code": code}) # ─── Вебхук ─── def set_webhook(self, url): """Возвращает НОВЫЙ ``secret`` — сохраните его, он показывается один раз.""" return self.request("PUT", "/webhook", {"url": url}) def get_webhook(self): return self.request("GET", "/webhook") def delete_webhook(self): return self.request("DELETE", "/webhook") def test_webhook(self): return self.request("POST", "/webhook/test") def verify_webhook_signature(raw_body, signature, secret): """Заголовок ``X-Kazpayment-Signature: sha256=`` — HMAC-SHA256 от сырых байт тела.""" if not signature or not secret: return False if isinstance(raw_body, str): raw_body = raw_body.encode("utf-8") expected = "sha256=" + hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest() # Байтами: compare_digest на строках с не-ASCII бросает TypeError, а # заголовок присылает кто угодно. return hmac.compare_digest(str(signature).encode("utf-8"), expected.encode("utf-8")) def parse_webhook(raw_body, signature, secret): """Проверить подпись и разобрать событие; неверная подпись — ``KazPaymentError``.""" if not verify_webhook_signature(raw_body, signature, secret): raise KazPaymentError("Подпись вебхука не сошлась", status=400, code="bad_signature") if isinstance(raw_body, bytes): raw_body = raw_body.decode("utf-8") return json.loads(raw_body)