YooKassa
Продукт: Shelter Cloud | Уровень: Shelter | Статус: Stable
ID системы: 22
Описание
Интеграция с платёжной системой YooKassa (ранее Яндекс.Касса) для приёма онлайн-платежей. Поддерживает оплату банковскими картами, СБП, электронными кошельками и другие способы.
Настройка в Shelter Cloud
Параметры учётной записи настраиваются через PrivateSettings:
| Параметр | Описание |
|---|---|
| ShopID | Идентификатор магазина |
| SecretKey | Секретный ключ |
| Receipt | Формировать фискальный чек (true / false) |
| TaxSystem | Система налогообложения: 1 (ОСН), 2 (УСН доход), 3 (УСН доход-расход), 4 (ЕНВД), 5 (ЕСН), 6 (Патент) |
| PaymentMode | Признак способа расчёта: full_prepayment, prepayment, advance, full_payment, partial_payment, credit, credit_payment |
| Currency | Валюта: RUB |
Конфигурация сервиса (appsettings.json)
| Параметр | Описание |
|---|---|
| IPWhiteList | Список разрешённых IP для callback. Доступ: отдел разработки |
API Endpoints
Создание платежа
| Среда | URL |
|---|---|
| Production | https://api.yookassa.ru/v3/payments |
Callback
URL для callback: https://cloud.shelter.ru/UKassa/Result
Аутентификация
YooKassa использует Basic Authentication:
Authorization: Basic base64(shopID:secretKey)Idempotence-Key: cashId_GUID— ключ идемпотентности
Алгоритм подписи
YooKassa не использует подпись запросов — аутентификация происходит через Basic Auth. Для проверки callback используется IP whitelist.
Процесс оплаты
- Клиент нажимает «Оплатить»
- Получение данных брони
- Формирование JSON-запроса на создание платежа
- POST на api.yookassa.ru/v3/payments
- Получение confirmation_token для виджета
- Клиент оплачивает через виджет YooKassa
- YooKassa отправляет callback (webhook)
- Проверка IP отправителя
- Запись платежа
Коды НДС (vat_code)
| Код | Описание |
|---|---|
| 1 | НДС 20% |
| 2 | НДС 10% |
| 3 | НДС 20/120 (расчётный) |
| 4 | НДС 10/110 (расчётный) |
| 5 | НДС 0% |
| 6 | Без НДС |
Поддерживаемые валюты
| Код | Валюта |
|---|---|
| RUB | Российский рубль |
Мониторинг (Zabbix)
Health check URL: https://cloud.shelter.ru/UKassa/
Логирование
Все события логируются в Graylog (channel: UKassa).
Примеры сообщений при callback
Получен callback:
Оплата: POST /UKassa/Result Data: {"type":"notification","event":"payment.succeeded","object":{"id":"pi_abc123","status":"succeeded","amount":{"value":"5000.00","currency":"RUB"},"metadata":{"cashId":100,"reservationId":200}}}
Успешная оплата:
Оплата успешно: 100 succeeded
Ошибка статуса:
Ошибка оплаты: неверный статус заказа
Заказ не оплачен:
Ошибка оплаты: заказ не оплачен
IP не в whitelist:
Ошибка оплаты: не допустимый ip адрес
Устранение неполадок
Ошибка 401 Unauthorized
Причина: Неверные ShopID или SecretKey.
Решение:
- Проверьте учётные данные в PrivateSettings
- Убедитесь, что SecretKey актуальный (не истёк)
Callback не приходит
Решение:
- Проверьте настройки webhook в личном кабинете YooKassa
- Убедитесь, что URL доступен из интернета
Ошибка IP validation
Решение:
- Проверьте IP whitelist в конфигурации
- Добавьте новые IP-адреса YooKassa