YooKassa

Что это за документ

Этот документ нужен компании, которая хочет подключить YooKassa к Omnis и начать принимать онлайн-оплату в клиентской витрине, Telegram Mini App или Max мини-приложение.

Если говорить совсем просто, YooKassa в Omnis нужна для того, чтобы клиент мог:

• оформить заказ
• выбрать онлайн-оплату
• перейти на защищенную страницу оплаты
• оплатить заказ и вернуться обратно в приложение

Для бизнеса это означает:

• можно принимать оплату без отдельной разработки своей платежной страницы
• клиент получает привычный сценарий оплаты
• статус платежа и заказа можно отслеживать внутри Omnis

Что важно понять сразу

Для рабочего запуска онлайн-оплаты через YooKassa в Omnis обычно нужны четыре шага:

1. Получить Shop ID и Secret key в YooKassa.
2. Создать платежный аккаунт в Omnis и вставить Shop ID в поле Public key.
3. При необходимости настроить Webhook URL в кабинете YooKassa.
4. Привязать платежный аккаунт к приложению и включить онлайн-оплату в форме оформления заказа.

Пока не сделаны все эти шаги, онлайн-оплата может быть настроена только частично.

Например:

• если аккаунт создан, но не привязан к приложению, клиент не увидит рабочую онлайн-оплату
• если аккаунт привязан, но webhook не настроен, оплата может проходить, но статусы будут обновляться менее удобно

Релевантные разделы

• Платежные провайдеры - если нужно сначала создать платежный аккаунт в Omnis.
• Приложения - если аккаунт уже создан и его нужно назначить приложению.
• Блок страницы оформления заказа - если онлайн-оплата не показывается клиенту.
• Оплаты и возвраты - если нужно разбирать уже реальные оплаты и возвраты.

Что дает YooKassa компании

После подключения YooKassa компания получает:

• возможность принимать онлайн-оплату в витрине, Telegram Mini App или Max мини-приложении
• рабочий сценарий перехода на платежную страницу и возврата обратно
• автоматическую основу для учета попыток оплаты
• более понятный путь от корзины до оплаченного заказа

Это особенно полезно, если:

• компания продает онлайн и хочет принимать оплату сразу при оформлении заказа
• важно сокращать путь клиента до оплаты
• нужно разделять наличную и онлайн-оплату в одной форме оформления заказа

Что нужно подготовить заранее

До начала настройки полезно подготовить:

• доступ в Omnis
• доступ в кабинет YooKassa
• понимание, для какого приложения будет работать онлайн-оплата
• решение, хотите ли вы сначала проверить все на тестовом магазине

Если это первый запуск интеграции, безопаснее сначала использовать тестовый магазин YooKassa.

По официальной документации YooKassa тестовый режим доступен сразу после регистрации, а деньги в таком режиме не списываются по-настоящему.

Что именно брать, копировать и куда вставлять

Во всем процессе чаще всего используются четыре значения.

1. Где онлайн-оплата настраивается в Omnis

Для пользователя здесь важны три связанных места.

Место 1. Платежный аккаунт

Создается в разделе:

Система -> Настройки -> Платежные провайдеры

Именно здесь заводятся:

• Public key, куда вводят Shop ID из YooKassa
• Secret key
• Return URL
• Webhook URL

Место 2. Приложение компании

Настраивается в разделе:

Управление -> CMS -> Приложения

Именно здесь приложение связывается с конкретным платежным аккаунтом через поле:

• Платежный провайдер

Место 3. Экран оформления заказа

Настраивается в CMS-компоненте оформления заказа.

Именно здесь решается, увидит ли клиент онлайн-оплату как доступный способ оплаты.

Подробнее по этим связанным разделам:

• Платежные провайдеры
• Приложения
• Блок страницы оформления заказа

2. Что нужно создать в YooKassa до настройки Omnis

Для работы Omnis нужен магазин в YooKassa.

Если вы хотите сначала аккуратно проверить интеграцию, удобнее начать с тестового магазина.

По официальной документации YooKassa:

• тестовый магазин можно создать до боевого запуска
• тестовый режим позволяет проверять платежный сценарий без реального списания денег
• для тестового магазина используются свои Shop ID и Secret key

Это хороший вариант для первого подключения, если:

• команда делает интеграцию впервые
• нужно проверить возврат после оплаты
• нужно убедиться, что статусы платежа доходят до Omnis

3. Где взять Shop ID и Secret key

В кабинете YooKassa нужно получить:

• Shop ID
• Secret key

Именно эти два значения Omnis использует для связи с вашим магазином YooKassa.

Важно не путать названия полей: на стороне YooKassa значение называется Shop ID, а в карточке платежного аккаунта Omnis его нужно вставлять в поле Public key.

Практически правило простое:

• Shop ID из YooKassa показывает, какой магазин использовать
• Secret key подтверждает, что доступ к магазину разрешен

4. Как создать платежный аккаунт в Omnis

Откройте:

Система -> Настройки -> Платежные провайдеры

И создайте новую запись.

Для первого рабочего или тестового запуска обычно достаточно заполнить:

• Наименование
• Тип провайдера = YooKassa
• Public key
• Secret key

Дополнительно можно заполнить:

• Return URL

Также важно:

• оставить запись активной, если вы хотите использовать ее сразу
• в Режим подтверждения выбрать Redirect

В текущем рабочем сценарии Omnis поддерживает именно Redirect.

5. Что означают поля карточки YooKassa

Наименование

Это понятное рабочее название аккаунта в Omnis.

Хорошие примеры:

• YooKassa основной
• YooKassa тест
• YooKassa для Telegram Mini App или Max мини-приложения

Public key

Это поле Omnis для идентификатора магазина из YooKassa.

Сюда нужно вставить значение, которое в кабинете YooKassa называется Shop ID.

Без него Omnis не сможет создавать платежные сессии.

Secret key

Это секретный ключ магазина.

При создании новой записи он нужен обязательно.

Если аккаунт уже создан и вы просто редактируете другие поля, Secret key можно не вводить заново: Omnis сохранит уже существующее секретное значение.

Return URL

Это адрес, куда покупатель должен вернуться после оплаты.

Практически важно понимать так:

• при реальной оплате адрес возврата все равно нужен
• Omnis часто передает его автоматически из текущего клиентского сценария
• но заполнить Return URL в карточке полезно как запасной стабильный вариант

Режим подтверждения

Для текущего рабочего сценария нужен:

• Redirect

Это означает, что клиент оплачивает заказ на странице YooKassa и затем возвращается обратно в приложение.

Webhook token

Создается системой автоматически.

Вручную его вводить не нужно.

Webhook URL

Omnis показывает его автоматически в блоке Что куда копировать.

Именно этот адрес нужно перенести в кабинет YooKassa для входящих уведомлений.

6. Как настроить Webhook URL в YooKassa

После сохранения платежного аккаунта вернитесь в его карточку в Omnis и найдите:

• Webhook URL

Скопируйте его целиком.

Затем откройте кабинет YooKassa и настройте HTTP-уведомления.

По официальной документации YooKassa для решений с HTTP Basic Auth уведомления обычно настраиваются в личном кабинете в разделе:

• Интеграция -> HTTP-уведомления

Практически в этом сценарии вам нужно:

1. Вставить Webhook URL из Omnis.
2. Сохранить настройки уведомлений.

Если вы используете адрес, который сгенерировал Omnis, вручную его менять не нужно.

Зачем нужен webhook

Webhook нужен, чтобы Omnis автоматически узнавал о событиях оплаты и возврата.

На практике это особенно важно для:

• подтверждения успешной оплаты
• обработки отмены платежа
• обновления информации по возвратам

Если webhook не настроен, платежный сценарий может работать не так удобно:

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

7. Как привязать YooKassa к приложению

После создания платежного аккаунта его еще нужно назначить приложению.

Откройте:

Управление -> CMS -> Приложения

Затем:

1. Откройте нужное приложение.
2. Найдите поле Платежный провайдер.
3. Выберите созданный аккаунт YooKassa.
4. Сохраните приложение.

Пока эта привязка не сделана, клиентская витрина не сможет использовать именно этот платежный аккаунт.

8. Как сделать онлайн-оплату видимой в форме оформления заказа

Даже после привязки платежного аккаунта онлайн-оплата должна быть разрешена на экране оформления заказа.

Проверьте компонент оформления заказа:

• Онлайн-оплата должна быть включена

Если этот переключатель выключен, клиент не увидит онлайн-оплату как доступный вариант даже при полностью настроенной YooKassa.

9. Как проходит оплата для клиента

В текущем рабочем сценарии Omnis путь клиента выглядит так:

1. Клиент оформляет заказ.
2. Выбирает Онлайн-оплата.
3. Omnis создает заказ.
4. Omnis получает от YooKassa ссылку подтверждения оплаты.
5. Клиент переходит на страницу оплаты YooKassa.
6. После оплаты YooKassa возвращает клиента обратно.
7. Omnis обновляет информацию о платеже.

Для клиента это выглядит как привычный переход на защищенную страницу оплаты и возврат обратно в приложение после завершения операции.

10. Как лучше проверить интеграцию в первый раз

Если это первый запуск, удобнее использовать тестовый магазин YooKassa.

По официальной документации:

• в тестовом режиме можно проверить весь платежный сценарий
• деньги в таком режиме не переводятся по-настоящему
• для тестирования используются данные тестового магазина и специальные тестовые карты

Практический порядок проверки такой:

1. Создайте тестовый магазин в YooKassa.
2. Возьмите его Shop ID и Secret key.
3. Создайте тестовый платежный аккаунт в Omnis.
4. В поле Public key вставьте тестовый Shop ID.
5. При необходимости настройте Webhook URL.
6. Привяжите тестовый аккаунт к приложению.
7. Включите онлайн-оплату в форме оформления заказа.
8. Оформите тестовый заказ.
9. Проверьте переход на страницу оплаты и возврат обратно.

11. Что чаще всего делают неправильно

Ошибка 1. Создают платежный аккаунт, но не привязывают его к приложению

В этом случае витрина не знает, какой именно аккаунт использовать для онлайн-оплаты.

Ошибка 2. Привязывают аккаунт к приложению, но не включают онлайн-оплату в форме оформления заказа

Тогда клиент не увидит нужный способ оплаты на экране оформления заказа.

Ошибка 3. Не настраивают Webhook URL

Без webhook оплата может работать менее предсказуемо с точки зрения статусов и подтверждений.

Ошибка 4. Путают рабочий и тестовый магазин

Для тестирования нужно использовать Shop ID и Secret key именно тестового магазина, а не боевого.

Ошибка 5. Оставляют запись неактивной

Если платежный аккаунт деактивирован, приложение не должно предлагать его для онлайн-оплаты.

Ошибка 6. Ожидают, что Embedded или External заработают в стандартном сценарии

В текущем рабочем варианте Omnis ориентируется на Redirect.

12. Когда YooKassa особенно полезна бизнесу

YooKassa особенно полезна, если:

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

13. Короткий чек-лист подключения

• в YooKassa создан рабочий или тестовый магазин
• получены Shop ID и Secret key
• Shop ID внесен в поле Omnis Public key
• в Omnis создан платежный аккаунт YooKassa
• аккаунт активирован
• при необходимости в Omnis скопирован и настроен Webhook URL
• платежный аккаунт привязан к приложению
• в форме оформления заказа включена Онлайн-оплата
• выполнен тестовый заказ
• клиент уходит на страницу YooKassa и возвращается обратно без ошибок