Billing Webhook (YooKassa)

Webhook обновляет статус платежа и активирует подписку только при успешной оплате.

Endpoint

POST /v1/billing/yookassa/webhook

Подлинность webhook подтверждается обратной проверкой статуса платежа через YooKassa API (GET /v3/payments/{id}).

Basic Auth может присутствовать, но не является обязательным условием обработки.

Для отладки: YOOKASSA_WEBHOOK_DEBUG=true включает маскированные headers и preview body в логах.

Поддерживаемые события

  • payment.waiting_for_capture — gateway проверяет статус через API YooKassa и отправляет capture.
  • payment.succeeded — активируется подписка по metadata.plan_code.
  • payment.canceled — платеж помечается отмененным, подписка не создается.

IP webhook сверяется с allowlist YooKassa (по умолчанию официальный список в коде). Для строгой блокировки включите YOOKASSA_WEBHOOK_ENFORCE_IP=true.

Пример payload

{
  "event": "payment.succeeded",
  "object": {
    "id": "payment-id",
    "status": "succeeded",
    "metadata": {
      "user_id": "...",
      "plan_code": "pro_year_500k"
    }
  }
}

Создание платежа из кабинета

POST /v1/billing/yookassa/create-payment
{ "plan_code": "pro_month_50k" }

Ответ содержит confirmation_url для редиректа пользователя на оплату.