Оплата ЮKassa для OpenCart 4

Оплата ЮKassa для OpenCart 4

Платёжное расширение для OpenCart 4.1.0.4: покупатель подтверждает заказ, переходит на защищённую страницу ЮKassa, оплачивает и возвращается в магазин. Способы оплаты — банковские карты, СБП, SberPay и другие — определяются договором магазина с ЮKassa. Модуль работает прямыми запросами к API ЮKassa v3, без SDK и без правок ядра.

Для кого

Для магазинов в России на OpenCart 4, которым нужен приём платежей через ЮKassa с холдированием, возвратами из панели и чеками по 54-ФЗ — для одного магазина, без агентских схем и сплитования.

Что умеет

• Платёж в рублях на странице ЮKassa: заказ в RUB уходит как есть, заказ в другой валюте пересчитывается по курсу RUB магазина.
• Холдирование (двухстадийная оплата): деньги замораживаются, списание или отмена — кнопкой в карточке заказа.
• Возвраты из карточки заказа на любую сумму в пределах остатка, с комментарием; полный возврат меняет статус заказа.
• Чеки 54-ФЗ в трёх режимах: без чеков; чек в запросе платежа («Чеки от ЮKassa» или касса «платёж и чек одновременно»); отдельный чек после оплаты и после возврата (своя онлайн-касса), с повтором кнопкой при ошибке кассы.
• Состав чека: позиции заказа и доставка услугой; коды НДС 1–12, система налогообложения, соответствие классов налога магазина ставкам НДС, признаки предмета и способа расчёта; сумма позиций всегда равна сумме платежа.
• Статусы заказа при создании платежа, холде, оплате, отмене и полном возврате — ставятся штатной историей заказа (письма и остатки работают как обычно), каждое состояние применяется один раз.
• HTTP-уведомления ЮKassa с проверкой подсетей отправителя; объект перечитывается из API, неизвестные платежи игнорируются.
• Панель «Платёж ЮKassa» в карточке заказа: платежи, чеки, возвраты, кнопки «Подтвердить (списать)», «Отменить холд», «Вернуть», «Отправить чек повторно», «Обновить статус».
• Кнопка «Проверить подключение» с введёнными ключами; журнал запросов к API без ключей на вкладке «Журнал».
• Страница «Оплата не завершена» с причиной отказа и кнопкой «Повторить оплату»; повторное нажатие в течение часа использует тот же платёж — без дублей.
• Минимальная сумма заказа, геозона по адресу оплаты, порядок сортировки; руководство вкладкой «Руководство».

Как платит покупатель

На шаге оплаты покупатель выбирает «Оплата через ЮKassa» и нажимает «Перейти к оплате». Модуль создаёт платёж и переводит на страницу ЮKassa. После оплаты — страница «Заказ оформлен» и статус заказа по настройке; при отказе банка или закрытой странице — «Оплата не завершена» с кнопками «Повторить оплату» и «Вернуться к оформлению», деньги не списаны.

Установка

1. «Расширения → Установщик» → «Загрузить» → файл yookassa_oc4.ocmod.zip (имя не менять: OpenCart 4 берёт из него код расширения) → «Установить».
2. «Расширения → Расширения», тип «Оплата» → «Установить» у «Оплата ЮKassa» → «Редактировать».
3. Введите shopId и секретный ключ из кабинета ЮKassa (Интеграция → Ключи API), нажмите «Проверить подключение», включите «Статус», сохраните.
4. В кабинете ЮKassa (Интеграция → HTTP-уведомления) укажите адрес со страницы расширения и события payment.succeeded, payment.waiting_for_capture, payment.canceled, refund.succeeded.

При установке создаются три таблицы (платежи, возвраты, журнал) и событие панели в карточке заказа; модификаторов нет. Валюта RUB должна быть заведена в «Система → Локализация → Валюты».

Обновление и удаление

Обновление — установка нового архива поверх прежних файлов через Установщик; настройки и ключи сохраняются. Удаление: «Расширения → Расширения → Оплата» → «Удалить», затем удалить пакет в Установщике. Таблицы платежей, возвратов и журнала остаются — это данные заказов.

Совместимость и ограничения

• OpenCart 4.1.0.4, PHP 8.2, тема Default — проверено; нужны расширение PHP cURL и валюта RUB в магазине.
• Другие версии OpenCart 4 и сторонние темы не проверялись.
• HTTP-уведомления ЮKassa приходят только на HTTPS; без них статус обновляется при возврате покупателя на сайт и кнопкой «Обновить статус».
• Частичное подтверждение холда, маркировка товаров, закрывающий чек при предоплате, виджет оплаты на сайте и рекуррентные платежи в эту версию не входят.

Расширение входит в состав бесплатной русской сборки OCM Store: там оно уже установлено и выключено до ввода ключей. Этот пакет — для обычного OpenCart 4.1.0.4.

Список изменений

1.0.0 — первая версия: оплата на странице ЮKassa, холдирование, возвраты из карточки заказа, чеки 54-ФЗ в трёх режимах, HTTP-уведомления с проверкой адресов, журнал запросов, панель «Платёж ЮKassa», проверка подключения, руководство вкладкой.