YooKassa

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Платёжный аккаунт создаётся в группе Система, в разделе Настройки, на странице Платежные провайдеры.

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

• Shop ID из кабинета YooKassa
• Secret key
• Return URL
• Webhook URL

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

Приложение настраивается на странице Приложения в группе CMS.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Shop ID
• Secret key

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

Название поля совпадает в обоих сервисах: значение из Shop ID в YooKassa нужно вставить в поле Shop ID в Omniz.

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

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

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

В группе Система откройте раздел Настройки, затем страницу Платежные провайдеры.

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

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

• Наименование
• в поле Тип провайдера выбрать YooKassa
• Shop ID
• Secret key

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

• Return URL

Также важно:

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

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

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

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

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

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

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

Shop ID

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

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

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

Secret key

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

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

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

Return URL

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

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

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

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

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

• Redirect

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

Webhook token

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

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

Webhook URL

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

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

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

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

• Webhook URL

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

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

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

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

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

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

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

Зачем нужен webhook

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

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

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

При полном возврате Omniz дополнительно сверяет в ответе YooKassa исходный платеж, сумму и валюту. Заказ отменяется только после полного совпадения и успешного статуса возврата.

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

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

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

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

В группе CMS откройте страницу Приложения.

Затем:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Создайте тестовый магазин в YooKassa.
2. Возьмите его Shop ID и Secret key.
3. Создайте тестовый платежный аккаунт в Omniz.
4. В поле 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 заработают в стандартном сценарии

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

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

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

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

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

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