Оплата ЮKassa
Приём платежей через ЮKassa для OpenCart 4: оплата на защищённой странице ЮKassa (карты, СБП, SberPay и другие способы по настройкам вашего магазина в ЮKassa), холдирование, возвраты из карточки заказа, чеки 54-ФЗ, HTTP-уведомления и журнал запросов.
Назначение и совместимость
Расширение добавляет способ оплаты «Оплата через ЮKassa» (банковские карты, СБП, SberPay и другие способы — по договору магазина с ЮKassa). Покупатель подтверждает заказ, переходит на страницу ЮKassa, оплачивает и возвращается в магазин. Статус заказа ставится автоматически: при возврате покупателя на сайт, по HTTP-уведомлению ЮKassa или кнопкой «Обновить статус» в заказе.
Проверено на OpenCart 4.1.0.4 и PHP 8.2 (нужно расширение PHP cURL). Другие версии OpenCart 4 не проверялись.
Установка
- Расширения → Установщик → «Загрузить», файл
yookassa_oc4.ocmod.zip(имя не менять: OpenCart 4 берёт из него код расширения), затем зелёная кнопка «Установить» в строке «Оплата ЮKassa». - Расширения → Расширения, тип «Оплата» → «Установить» у «Оплата ЮKassa», затем «Редактировать».
- Введите shopId и секретный ключ, нажмите «Проверить подключение», включите статус и сохраните.
- Укажите адрес для HTTP-уведомлений в личном кабинете ЮKassa (раздел ниже).
При установке создаются три таблицы (yookassa_payment, yookassa_refund, yookassa_log) и событие панели в карточке заказа. Права получает группа пользователя, который нажал «Установить»; другим группам — Система → Пользователи → Группы пользователей, маршрут extension/yookassa_oc4/payment/yookassa.
Ключи магазина и проверка
Ключи берутся в личном кабинете ЮKassa: Интеграция → Ключи API. У тестового магазина свои shopId и ключ — так проверяют интеграцию без реальных денег (тестовые карты описаны в документации ЮKassa).
- shopId — идентификатор магазина.
- Секретный ключ — хранится только в настройках магазина, в форме не показывается; пустое поле при сохранении оставляет прежний ключ. В журнал ключ не записывается.
- Проверить подключение — запрос к ЮKassa с введёнными ключами без сохранения: показывает идентификатор магазина, его статус, признак тестового магазина и включены ли «Чеки от ЮKassa».
Настройки
Расширения → Расширения → Оплата → Оплата ЮKassa → Редактировать, вкладка «Настройки».
| Настройка | По умолчанию | Смысл |
|---|---|---|
| Статус | выключено | Выключенный способ покупатели не видят. Включить можно только с введёнными ключами |
| Тестовый режим | включён | Подсказка покупателю о тестовой карте на шаге подтверждения |
| Холдирование | выключено | Двухстадийная оплата: деньги замораживаются, списание — кнопкой в заказе (до 7 дней) |
| Статусы заказа | см. ниже | Какой статус ставить при создании платежа, холде, оплате, отмене и полном возврате |
| Уведомлять покупателя | да | Письмо покупателю при смене статуса заказа платежом (штатная история заказа) |
| Минимальная сумма заказа | 0 | В основной валюте магазина; ниже неё способ не предлагается |
| Географическая зона | все зоны | Ограничение по адресу оплаты (действует, если в настройках магазина включён адрес оплаты) |
| Порядок сортировки | 1 | Место в списке способов оплаты |
| Проверять IP-адрес уведомлений | да | Уведомления принимаются только с подсетей ЮKassa; выключать только для отладки |
| Журнал запросов к API | да | Запросы и ответы во вкладке «Журнал»; уведомления записываются всегда |
Статусы заказа и холд
| Событие | Статус по умолчанию | Пояснение |
|---|---|---|
| Платёж создан, покупатель ушёл на страницу ЮKassa | не менять | Заказ остаётся без статуса (в списке «потерянных») до оплаты — как у штатных способов оплаты. Если задать статус, заказ появится в списке сразу |
| Холд: деньги заморожены | Ожидание | Нужно подтвердить или отменить списание в карточке заказа |
| Оплачен | В обработке | Деньги списаны |
| Платёж отменён | Отменён | Отказ банка, истечение срока, отмена холда магазином. У заказа без статуса статус не меняется |
| Возвращён полностью | Возврат средств | После возврата всей суммы из карточки заказа или по уведомлению ЮKassa |
Статус ставится только через штатную историю заказа — поэтому срабатывают письма, пересчёт остатков и другие расширения, как при ручной смене статуса. Каждое состояние платежа применяется один раз: повторные уведомления и повторные возвраты покупателя на сайт историю не дублируют.
Чеки 54-ФЗ
Вкладка «Чеки 54-ФЗ». Режим выбирается по тому, как фискализация подключена в вашем кабинете ЮKassa:
- Без чеков — кассы нет, или чеки формирует другая система (учётная программа, касса при выдаче).
- Чек в запросе платежа — для «Чеков от ЮKassa» и касс в режиме «платёж и чек одновременно»: данные чека уходят вместе с платежом и вместе с возвратом.
- Сначала платёж, потом чек — для своей онлайн-кассы, подключённой к ЮKassa в этом сценарии: отдельный чек прихода отправляется после успешной оплаты, чек возврата — после возврата. При ошибке кассы чек можно отправить повторно кнопкой в заказе.
Состав чека: позиции заказа (название, количество, цена с налогом, если налог начислен в заказе) и доставка отдельной позицией «Услуга». Сумма позиций всегда равна сумме платежа: разница из-за скидок уровня заказа или округлений распределяется по позициям. Покупателю чек уходит на e-mail и телефон из заказа (телефон приводится к формату 79000000000).
| Настройка | Смысл |
|---|---|
| Система налогообложения | Код СНО в чеке. Для «Чеков от ЮKassa» не нужна, для своей кассы — если систем несколько |
| НДС по умолчанию | Ставка для товаров без соответствия классу налога и для доставки без своей ставки. Коды 1–12: без НДС, 0 %, 10 %, 20 %, 10/110, 20/120, 5 %, 7 %, 5/105, 7/107, 22 %, 22/122 |
| НДС доставки | Отдельная ставка для позиции доставки |
| Соответствие классов налога | Класс налога товара в OpenCart → код НДС в чеке |
| Признак предмета расчёта | Товар, услуга, работа, платёж, иной — для позиций товаров; доставка всегда «услуга» |
| Признак способа расчёта | Полный расчёт или предоплата 100 % |
HTTP-уведомления
Адрес показан на вкладке «Настройки» (…/index.php?route=extension/yookassa_oc4/payment/yookassa.callback). Укажите его в кабинете ЮKassa: Интеграция → HTTP-уведомления, события payment.succeeded, payment.waiting_for_capture, payment.canceled, refund.succeeded.
- ЮKassa отправляет уведомления только на адреса HTTPS. Без них статус всё равно обновится при возврате покупателя в магазин и по кнопке «Обновить статус» в заказе.
- Телу уведомления расширение не доверяет: платёж перечитывается из API ЮKassa, неизвестные платежи игнорируются.
- Уведомления с адресов вне подсетей ЮKassa отклоняются (ответ 403), пока включена проверка IP. Если сайт за прокси или CDN, укажите доверенные прокси в настройках сервера OpenCart, иначе выключите проверку.
- Возврат, сделанный в кабинете ЮKassa, по уведомлению
refund.succeededпоявится в карточке заказа; при полном возврате изменится статус заказа.
Как платит покупатель
- На шаге оплаты выбирает «Оплата через ЮKassa» и нажимает «Перейти к оплате».
- Расширение создаёт платёж в ЮKassa и переводит покупателя на страницу оплаты. Если покупатель вернётся и нажмёт кнопку ещё раз в течение часа, тот же платёж используется повторно — дублей не будет.
- После оплаты покупатель возвращается в магазин: при успехе — страница «Заказ оформлен»; при отказе банка или незавершённой оплате — страница «Оплата не завершена» с причиной и кнопками «Повторить оплату» и «Вернуться к оформлению». Деньги в этом случае не списаны.
Панель в карточке заказа
Продажи → Заказы → заказ: над блоком «История» появляется панель «Платёж ЮKassa» со списком платежей заказа (идентификатор, сумма, состояние, способ оплаты, чек, возвраты).
- Подтвердить (списать) и Отменить холд — для платежа в состоянии холда.
- Вернуть — возврат на любую сумму в пределах остатка с комментарием; при полном возврате меняется статус заказа.
- Отправить чек повторно — в режиме «сначала платёж, потом чек», если касса вернула ошибку.
- Обновить статус — перечитать платёж из ЮKassa (например, если уведомления не настроены).
Кнопки с подтверждением срабатывают со второго нажатия в течение пяти секунд. После действия статус заказа ставится через штатную форму истории под панелью — она отправляется автоматически, запись появляется в истории заказа.
Журнал
Вкладка «Журнал» показывает последние 50 записей: запросы к API (метод, путь, код ответа, тело запроса и ответа без ключей) и входящие уведомления с результатом обработки. Кнопка «Очистить журнал» удаляет все записи. Если запросы к API в журнале не нужны, выключите «Журнал запросов к API» — уведомления записываются всё равно.
В сборке OCM Store
В русской сборке OCM Store расширение уже установлено и выключено: откройте Расширения → Расширения → Оплата → Оплата ЮKassa, введите ключи, включите статус и укажите адрес уведомлений в кабинете ЮKassa. Пакета в Установщике нет — файлы расширения входят в сборку.
Удаление
Расширения → Расширения → Оплата → «Удалить» у «Оплата ЮKassa», затем в Установщике — удалить пакет. Настройки и событие удаляются; таблицы платежей, возвратов и журнала остаются (это данные заказов). Повторная установка сохраняет прежние ключи и статусы, если настройки ещё есть.
Типовые вопросы
Способа оплаты нет на шаге оплаты. Проверьте: статус включён, введены оба ключа, в магазине заведена валюта RUB, сумма заказа не ниже минимальной, геозона подходит адресу, в корзине нет подписок.
Покупатель оплатил, а статус заказа не изменился. Нажмите «Обновить статус» в карточке заказа. Проверьте адрес уведомлений в кабинете ЮKassa (нужен HTTPS) и журнал: отклонённые уведомления записываются с кодом 403.
«ЮKassa не приняла платёж». Текст ошибки — из ответа API, подробности в журнале. Чаще всего — неверные ключи или чек с нулевой позицией.
Нужны ли агентские чеки и сплитование? Нет: это расширение для одного магазина, продавцов и площадок нет.