yookassa

Введение

YooKassa (ранее Yandex.Kassa) — платёжная система, позволяющая принимать платежи банковскими картами, через электронные кошельки и другие способы.

При интеграции с EnotPro через вебхук вы сможете:

• Принимать уведомления об успешных платежах
• Автоматически начислять баланс пользователю
• Обрабатывать отмены и возвраты платежей

Типы событий YooKassa

YooKassa присылает уведомления о следующих событиях:

Важно: Для большинства сценариев (одностадийные платежи) достаточно обрабатывать только payment.succeeded.

Предварительные требования

Данные для доступа к API YooKassa

Важно: Аутентификация в API ЮKassa происходит по HTTP Basic Auth: логин = shopId, пароль = secretKey.

Шаг 1: Создание вебхука в EnotPro

Создаём вебхук

1. Перейдите в раздел /adm → Web → Webhook.
2. Нажмите кнопку «Добавить».
3. Название: yookassa_payments.
4. Скопируйте сгенерированный URL (понадобится в личном кабинете ЮKassa).

Настраиваем разрешённые методы

Включаем вебхук

Переключатель «Включен» → ✅.

Шаг 2: Настройка вебхука в личном кабинете ЮKassa

1. Войдите в личный кабинет ЮKassa.
2. Перейдите в раздел «Интеграция» → «HTTP-уведомления» (формулировка может отличаться).

Укажите URL вебхука:

https://enotpro.app/wh/xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx

4. Выберите события для уведомлений (рекомендуется):

• payment.succeeded
• payment.canceled

5. Сохраните настройки.

Ссылка на официальную документацию: Настройка HTTP-уведомлений в ЮKassa

Шаг 3: Структура входящего запроса от YooKassa

Пример тела запроса для payment.succeeded

{
  "type": "notification",
  "event": "payment.succeeded",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "succeeded",
    "paid": true,
    "amount": {
      "value": "1000.00",
      "currency": "RUB"
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Пополнение баланса",
    "metadata": {
      "user_id": "123456789"
    },
    "payment_method": {
      "type": "bank_card",
      "card": {
        "first6": "555555",
        "last4": "4444",
        "card_type": "MasterCard"
      }
    }
  }
}

Доступные переменные в триггере MAIN

Шаг 5: Создание HTTP-ответа для YooKassa

ЮKassa ожидает получить ответ с кодом 200 OK. Если ответ не получен или код ошибки, ЮKassa будет повторять уведомления (с увеличивающимися интервалами).

Создаём HTTP-ответ в EnotPro

1. Перейдите в раздел /adm → Web → HTTP-ответы.
2. Нажмите «Добавить».
3. Название: yookassa_success.
4. Настройки:

Важно: ЮKassa игнорирует тело ответа, но код 200 обязателен.

Шаг 6: Настройка триггеров в EnotPro

Создаём HTTP-ответ для кастомного ответа

(См. Шаг 5 выше)

Настраиваем триггер MAIN

Триггер MAIN:

Реакция 1: Условие (проверяем тип события)
  → Тип: String
  → Путь: ${web.body.event}
  → Режим: равно
  → Значение: payment.succeeded
  → Если условие НЕ выполнено:
     → SendResponse (код 200, текст "Ignored")
     → StopTrigger

Реакция 2: SetVarLocal (сохраняем данные платежа)
  → Название: payment_id
  → Значение: ${web.body.object.id}

Реакция 3: SetVarLocal
  → Название: user_id
  → Значение: ${web.body.object.metadata.user_id}

Реакция 4: SetVarLocal
  → Название: amount
  → Значение: ${web.body.object.amount.value}

Реакция 5: SendResponse (подтверждаем получение)
  → HTTP-ответ: yookassa_success

Настраиваем триггер FINISH (из HTTP-ответа yookassa_success)

Здесь выполняем длительные операции — начисление баланса, отправку сообщений.

Триггер FINISH:

Реакция 1: Проверяем, что user_id получен
  → Тип: Has
  → Путь: ${localVar.user_id}
  → Если условие НЕ выполнено:
     → Log: "Ошибка: user_id не передан в metadata"
     → StopTrigger

Реакция 2: GetVarCloud (загружаем текущий баланс)
  → Тип: person
  → Название: balance
  → user_id: ${localVar.user_id}

Реакция 3: AddVarCloud (начисляем сумму)
  → Тип: person
  → Название: balance
  → Значение: ${localVar.amount}

Реакция 4: SendMessage (уведомляем пользователя)
  → chat_id: ${localVar.user_id}
  → Текст: «Ваш баланс пополнен на ${localVar.amount} руб.»

Реакция 5: Log
  → Текст: «Платёж ${localVar.payment_id} обработан, пользователю ${localVar.user_id} начислено ${localVar.amount} руб.»

Шаг 7: Формирование запроса на создание платежа (со стороны бота)

Чтобы пользователь мог инициировать платёж, бот должен отправить запрос к API ЮKassa на создание платежа.

Параметры запроса (minimal для одностадийного платежа)

{
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "capture": true,
  "confirmation": {
    "type": "redirect",
    "return_url": "https://t.me/ваш_бот"
  },
  "description": "Пополнение баланса",
  "metadata": {
    "user_id": "123456789"
  }
}

Пример создания платежа через SendRequest

Перейдите в раздел /adm → Web → HTTP-запросы.

Создайте запрос с параметрами:

В ответе ЮKassa вернёт поле confirmation.confirmation_url — на эту ссылку нужно отправить пользователя.