Приём платежей через ЮKassa

Что нужно подключить

В редакторе откройте «Данные → Интеграции» и подключите ЮKassa. Для уведомлений об оплате дополнительно подключите Telegram. Секретные ключи шифруются и не попадают в файлы сайта.

Перед подключением получите Shop ID и секретный ключ в кабинете ЮKassa. Не отправляйте их в чат и не добавляйте в .env или React-файлы проекта.

Обязательная настройка HTTP-уведомлений

После сохранения Shop ID и секретного ключа подключение ещё не закончено. Для обычного магазина ЮKassa не разрешает Vixy автоматически создавать вебхуки: API управления вебхуками доступно только партнёрским приложениям с OAuth.

Настройте уведомления вручную:

1. В карточке ЮKassa в Vixy скопируйте показанный URL обработчика.
2. Откройте личный кабинет ЮKassa.
3. Перейдите в «Интеграция → HTTP-уведомления».
4. Вставьте скопированный URL.
5. Включите события payment.succeeded и payment.canceled.
6. Сохраните настройки.

Используйте именно URL, показанный в карточке интеграции текущего окружения. Для production он выглядит так:

https://vixy.dev/api/integrations/yookassa/webhook

Локальный адрес localhost нельзя указать в ЮKassa: обработчик должен быть доступен из интернета по HTTPS. Поэтому полноценную проверку входящего уведомления выполняйте после деплоя или через отдельный публичный HTTPS-туннель.

Зелёная отметка в Vixy подтверждает только то, что Shop ID и секретный ключ проверены и сохранены. Она не подтверждает настройки в личном кабинете ЮKassa.

Таблица товаров

Платёжный сценарий использует таблицу products. У товара должны быть:

• id — идентификатор записи;
• name или title — название;
• price — цена в рублях числом, например 1490 или 1490.50;
• active — необязательный флаг доступности.

Поле price должно содержать число без символа валюты и пробелов. Значения "1 490 ₽" и "по запросу" не подходят для серверного расчёта.

Сайт передаёт серверу только идентификаторы товаров и количество. Итоговую сумму Vixy рассчитывает заново по данным таблицы — передать произвольную цену из браузера нельзя.

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

const checkoutId = crypto.randomUUID();
const { data, error } = await vixy.integrations.yookassa.createPayment({
  checkoutId,
  items: cart.map((item) => ({
    productId: item.id,
    quantity: item.quantity,
  })),
  returnUrl: window.location.href,
  customer: { name, email, phone },
});

if (error) throw new Error(error.message);
localStorage.setItem("vixy:lastOrderId", data.orderId);
window.location.assign(data.confirmationUrl);

checkoutId обеспечивает идемпотентность: повтор одного запроса не создаёт второй платёж.

Создавайте checkoutId один раз на попытку оформления и блокируйте кнопку, пока запрос выполняется. Если соединение оборвалось, повторите запрос с тем же идентификатором.

Проверка после возврата

const orderId = localStorage.getItem("vixy:lastOrderId");
const { data, error } = await vixy.integrations.yookassa.getPayment(orderId);

if (data?.status === "succeeded") {
  // Показать покупателю успешную оплату.
}

Статус читается не из параметров адресной строки, а повторно проверяется через API ЮKassa.

Обрабатывайте как минимум три состояния:

• succeeded — оплата подтверждена;
• pending — платёж ещё обрабатывается, можно повторить проверку;
• canceled — платёж отменён, предложите повторить оформление.

Сетевая ошибка не означает отмену или успех. Покажите нейтральное сообщение и разрешите повторную проверку по сохранённому orderId.

Что делает Vixy на сервере

1. Проверяет товары и рассчитывает сумму по БД проекта.
2. Создаёт идемпотентный платёж в ЮKassa.
3. Сохраняет заказ в изолированном хранилище проекта.
4. Принимает вебхук и повторно запрашивает платёж у ЮKassa.
5. Сверяет проект, заказ, идентификатор платежа, валюту и сумму.
6. Фиксирует подтверждённый статус.
7. Если подключён Telegram, отправляет уведомление об оплате.

AI не создаёт и не изменяет этот серверный код. Он только подключает интерфейс сайта к проверенному SDK Vixy.

Проверка перед публикацией

1. Создайте товар с небольшой тестовой ценой.
2. Проверьте, что URL и события сохранены в разделе HTTP-уведомлений кабинета ЮKassa.
3. Добавьте его в корзину и проверьте изменение количества.
4. Убедитесь, что двойное нажатие не создаёт два заказа.
5. Завершите оплату и дождитесь статуса succeeded.
6. Обновите страницу результата: успешный статус должен сохраниться.
7. Проверьте уведомление Telegram, если сервис подключён.
8. Выполните отменённый платёж и проверьте понятное сообщение покупателю.

Частые ошибки

«Сначала подключите ЮKassa» — откройте «Данные → Интеграции» и проверьте реквизиты.

Товар не найден — productId из корзины не совпадает с id записи в таблице products.

Некорректная цена — поле price отсутствует, содержит текст или товар отключён.

Страница результата всегда показывает успех — интерфейс доверяет URL вместо вызова getPayment(orderId).