Интеграция с ЮKassa API: полное руководство по приёму онлайн-платежей

 1import httpx
 2import base64
 3import uuid
 4
 5class YooKassaAPI:
 6    BASE_URL = "https://api.yookassa.ru/v3"
 7    
 8    def __init__(self, shop_id: str, secret_key: str):
 9        self.shop_id = shop_id
10        self.secret_key = secret_key
11        self._auth = base64.b64encode(
12            f"{shop_id}:{secret_key}".encode()
13        ).decode()
14    
15    def _get_headers(self, idempotency_key: str = None) -> dict:
16        headers = {
17            "Authorization": f"Basic {self._auth}",
18            "Content-Type": "application/json",
19        }
20        if idempotency_key:
21            headers["Idempotence-Key"] = idempotency_key
22        return headers
23    
24    async def create_payment(
25        self,
26        amount: float,
27        currency: str = "RUB",
28        description: str = "",
29        return_url: str = "",
30        payment_method: str = "bank_card",
31        metadata: dict = None,
32        capture: bool = True,
33        receipt_email: str = None,
34    ) -> dict:
35        """Создать платёж"""
36        payload = {
37            "amount": {"value": f"{amount:.2f}", "currency": currency},
38            "confirmation": {
39                "type": "redirect",
40                "return_url": return_url,
41            },
42            "capture": capture,
43            "description": description[:128],
44        }
45        
46        if payment_method:
47            payload["payment_method_data"] = {"type": payment_method}
48        
49        if metadata:
50            payload["metadata"] = metadata
51        
52        if receipt_email:
53            payload["receipt"] = {
54                "customer": {"email": receipt_email},
55                "items": [{
56                    "description": description[:128],
57                    "quantity": "1.00",
58                    "amount": {"value": f"{amount:.2f}", "currency": currency},
59                    "vat_code": "1",  # Без НДС
60                }],
61            }
62        
63        idempotency_key = str(uuid.uuid4())
64        async with httpx.AsyncClient() as client:
65            response = await client.post(
66                f"{self.BASE_URL}/payments",
67                headers=self._get_headers(idempotency_key),
68                json=payload,
69            )
70            response.raise_for_status()
71            return response.json()
72    
73    async def get_payment(self, payment_id: str) -> dict:
74        """Получить информацию о платеже"""
75        async with httpx.AsyncClient() as client:
76            response = await client.get(
77                f"{self.BASE_URL}/payments/{payment_id}",
78                headers=self._get_headers(),
79            )
80            response.raise_for_status()
81            return response.json()
82    
83    async def create_refund(
84        self,
85        payment_id: str,
86        amount: float,
87        currency: str = "RUB",
88    ) -> dict:
89        """Создать возврат"""
90        idempotency_key = str(uuid.uuid4())
91        async with httpx.AsyncClient() as client:
92            response = await client.post(
93                f"{self.BASE_URL}/refunds",
94                headers=self._get_headers(idempotency_key),
95                json={
96                    "payment_id": payment_id,
97                    "amount": {"value": f"{amount:.2f}", "currency": currency},
98                },
99            )
100            response.raise_for_status()
101            return response.json()

 1from fastapi import FastAPI, Request, HTTPException
 2import hmac
 3import hashlib
 4
 5app = FastAPI()
 6
 7YOOKASSA_SECRET = "your_shop_secret_key"
 8
 9def verify_yookassa_signature(body: bytes, signature: str) -> bool:
10    """Проверка подписи webhook от ЮKassa"""
11    expected = hmac.new(
12        YOOKASSA_SECRET.encode(),
13        body,
14        hashlib.sha256,
15    ).hexdigest()
16    return hmac.compare_digest(expected, signature)
17
18@app.post("/webhook/yookassa")
19async def handle_yookassa_webhook(request: Request):
20    """Обработка webhook от ЮKassa"""
21    body = await request.body()
22    
23    # Проверяем подпись (в продакшене обязательно!)
24    signature = request.headers.get("X-Signature", "")
25    if not verify_yookassa_signature(body, signature):
26        raise HTTPException(401, "Invalid signature")
27    
28    data = await request.json()
29    event = data.get("event")
30    payment = data.get("object", {})
31    
32    if event == "payment.succeeded":
33        await handle_payment_success(payment)
34    elif event == "payment.canceled":
35        await handle_payment_canceled(payment)
36    elif event == "refund.succeeded":
37        await handle_refund_success(payment)
38    
39    return {"status": "ok"}
40
41async def handle_payment_success(payment: dict):
42    """Обработка успешного платежа"""
43    order_id = payment.get("metadata", {}).get("order_id")
44    payment_id = payment["id"]
45    amount = float(payment["amount"]["value"])
46    
47    # 1. Обновляем статус заказа в БД
48    await update_order_status(order_id, "paid", payment_id)
49    
50    # 2. Отправляем уведомление клиенту
51    await send_order_confirmation(order_id)
52    
53    # 3. Уведомляем менеджера в Telegram
54    await notify_manager(
55        f"✅ Оплата получена!\n"
56        f"Заказ: #{order_id}\n"
57        f"Сумма: {amount} ₽\n"
58        f"Способ: {payment.get('payment_method', {}).get('type', 'Неизвестен')}"
59    )
60    
61    # 4. Если цифровой товар — отправляем сразу
62    order = await get_order(order_id)
63    if order.get("type") == "digital":
64        await deliver_digital_product(order_id)
65
66async def handle_payment_canceled(payment: dict):
67    """Обработка отменённого платежа"""
68    order_id = payment.get("metadata", {}).get("order_id")
69    
70    # Обновляем статус
71    await update_order_status(order_id, "payment_failed")
72    
73    # Уведомляем клиента
74    await send_payment_retry_link(order_id)
75    
76    # Уведомляем менеджера
77    await notify_manager(
78        f"❌ Платёж отменён\n"
79        f"Заказ: #{order_id}\n"
80        f"Причина: {payment.get('cancellation_details', {}).get('reason', 'Неизвестна')}"
81    )

 1async def create_two_stage_payment(api: YooKassaAPI, order: dict) -> dict:
 2    """Создать двухстадийный платёж"""
 3    # capture=False — только блокируем сумму
 4    payment = await api.create_payment(
 5        amount=order["total"],
 6        description=f"Заказ #{order['id']}",
 7        return_url=f"https://shop.ru/order/{order['id']}",
 8        capture=False,  # Не списываем сразу
 9        metadata={"order_id": order["id"]},
10    )
11    return payment
12
13async def confirm_payment(api: YooKassaAPI, payment_id: str, amount: float = None):
14    """Подтвердить платёж (списать заблокированную сумму)"""
15    payload = {}
16    if amount:
17        payload["amount"] = {"value": f"{amount:.2f}", "currency": "RUB"}
18    
19    async with httpx.AsyncClient() as client:
20        response = await client.post(
21            f"{api.BASE_URL}/payments/{payment_id}/capture",
22            headers=api._get_headers(str(uuid.uuid4())),
23            json=payload,
24        )
25        response.raise_for_status()
26        return response.json()

 1from datetime import datetime, timedelta
 2import asyncio
 3
 4class SubscriptionManager:
 5    def __init__(self, yukassa: YooKassaAPI, db):
 6        self.yukassa = yukassa
 7        self.db = db
 8    
 9    async def create_subscription(
10        self,
11        user_id: int,
12        plan_id: str,
13        payment_method_id: str,
14    ) -> dict:
15        """Создать подписку"""
16        plan = await self.db.get_plan(plan_id)
17        
18        subscription = {
19            "user_id": user_id,
20            "plan_id": plan_id,
21            "payment_method_id": payment_method_id,
22            "amount": plan["price"],
23            "currency": "RUB",
24            "interval": plan["interval"],  # monthly, weekly, yearly
25            "status": "active",
26            "next_payment_at": datetime.now() + timedelta(days=plan["interval_days"]),
27            "created_at": datetime.now(),
28        }
29        
30        await self.db.save_subscription(subscription)
31        
32        # Первый платёж сразу
33        await self._charge_subscription(subscription)
34        
35        return subscription
36    
37    async def _charge_subscription(self, subscription: dict) -> dict:
38        """Списать платёж по подписке"""
39        try:
40            payment = await self.yukassa.create_payment(
41                amount=subscription["amount"],
42                description=f"Подписка: {subscription['plan_id']}",
43                payment_method_id=subscription["payment_method_id"],
44                metadata={
45                    "subscription_id": subscription["id"],
46                    "user_id": subscription["user_id"],
47                },
48                receipt_email=subscription.get("email"),
49            )
50            
51            if payment["status"] == "succeeded":
52                # Платёж прошёл
53                await self.db.update_subscription(subscription["id"], {
54                    "status": "active",
55                    "last_payment_at": datetime.now(),
56                    "next_payment_at": self._calc_next_date(subscription),
57                    "failed_attempts": 0,
58                })
59                await self._notify_success(subscription, payment)
60            else:
61                # Платёж не прошёл
62                await self._handle_payment_failure(subscription, payment)
63            
64            return payment
65        except Exception as e:
66            await self._handle_payment_failure(subscription, {"error": str(e)})
67            raise
68    
69    async def _handle_payment_failure(self, subscription: dict, payment: dict):
70        """Обработка неудачного платежа по подписке"""
71        failed_attempts = subscription.get("failed_attempts", 0) + 1
72        
73        if failed_attempts >= 3:
74            # 3 неудачные попытки — приостанавливаем подписку
75            await self.db.update_subscription(subscription["id"], {
76                "status": "suspended",
77                "failed_attempts": failed_attempts,
78            })
79            await self._notify_suspended(subscription)
80        else:
81            # Повторная попытка через 24 часа
82            await self.db.update_subscription(subscription["id"], {
83                "status": "retry_pending",
84                "failed_attempts": failed_attempts,
85                "next_retry_at": datetime.now() + timedelta(hours=24),
86            })
87            await self._notify_retry(subscription, failed_attempts)
88    
89    async def process_subscriptions(self):
90        """Cron-задача: обработка подписок по расписанию"""
91        while True:
92            # Получаем подписки, по которым пора списывать
93            due = await self.db.get_due_subscriptions()
94            
95            for subscription in due:
96                try:
97                    await self._charge_subscription(subscription)
98                except Exception as e:
99                    print(f"Ошибка списания подписки {subscription['id']}: {e}")
100                
101                # Пауза между списаниями
102                await asyncio.sleep(0.5)
103            
104            # Проверяем каждые 15 минут
105            await asyncio.sleep(900)