msp3YooKassa - Интеграция с платежной системой ЮKassa

Встречайте msp3YooKassa — приём оплаты через ЮKassa для магазинов на MiniShop3 (MODX Revolution 3.x). Карты, кошельки и остальные способы из вашего договора с ЮKassa, входящие HTTP-уведомления (webhook) для актуализации заказа, по желанию — чеки 54-ФЗ. Внутри — официальный SDK yoomoney/yookassa-sdk-php и работа по API ЮKassa.

Зачем он нужен
Чтобы на MiniShop3 можно было принимать оплату через ЮKassa без самописных обвязок: один пакет, системные настройки с префиксом msp3yookassa_, два готовых способа оплаты (одно- и двухстадийная схема). Статусы платежа смотрите в кабинете ЮKassa. На сайте заказ обновляется после обработки webhook.

Для покупателя
Ничего отдельно в шаблоны подключать не нужно — используются стандартные сценарии оплаты MiniShop3. Покупатель выбирает способ «Оплата через ЮKassa» или двухстадийный вариант, уходит на сторону ЮKassa и возвращается по success/fail URL (при необходимости их можно задать в настройках компонента).

Для менеджера магазина
После установки в настройках MiniShop3 появляются два способа оплаты:

Оплата через ЮKassa — одностадийно, списание по правилам выбранного сценария ЮKassa.
Оплата через ЮKassa (двухстадийная) — холд средств на карте, затем в менеджере MODX вручную подтверждаете списание или отменяете платёж.

Минимум в Системные настройки (namespace msp3yookassa): msp3yookassa_shop_id и msp3yookassa_secret_key из личного кабинета ЮKassa. Дополнительно — чеки 54-ФЗ (msp3yookassa_payment_receipt), код НДС (msp3yookassa_vat_strong, значения 1–10 по справочнику ЮKassa), свои URL успеха и ошибки, отладочные логи (msp3yookassa_debug).

Для двухстадийного сценария после оплаты в ЮKassa статус платежа — waiting_for_capture. Подтверждение списания — процессор Msp3YooKassa\Processors\CaptureProcessor с параметром order_id.

HTTP-уведомления
В кабинете ЮKassa: Интеграция → HTTP-уведомления (настройки). URL для сайта, например:

ВАШ_ДОМЕН/assets/components/msp3yookassa/webhook.php

По требованиям ЮKassa адрес должен быть на HTTPS (TLS 1.2+). Компонент отвечает 200 OK после разбора JSON-уведомления.

Тестовый магазин и чеки
В ЮKassa есть тестовый магазин с отдельным shopId и ключом с префиксом test_ (обычно доступен после ИНН и технических настроек в кабинете). Подставьте их в настройки так же, как боевые — сценарий как в бою, деньги не списываются.

Боевые карты в тесте использовать нельзя.
Номера тестовых карт и правила 3-D Secure — в документации ЮKassa. Срок действия — любая дата позже текущей. CVC и код подтверждения можно вводить произвольными цифрами, как описано у ЮKassa.

Режим проверки чеков в тесте имитирует кассу, физический чек в ОФД не формируется — это нормально для отладки (раздел о тестировании). Для боя включите передачу данных чека и убедитесь, что в заказе есть email покупателя.

Для разработчика
Интеграция опирается на API MiniShop3 и обработчики платежей компонента. Термины одно- и двухстадийной оплаты совпадают с описанием процесса оплаты ЮKassa. Статусы объекта платежа — в справочнике API.

Подробная инструкция по установке и полям настроек — в документации на docs.modx.pro.

Установка и совместимость

MODX Revolution 3.0+
MiniShop3
PHP 8.2+
pdoTools 3.x

Быстрый старт

Установите транспортный пакет через Установщик → Управление пакетами.
В кабинете ЮKassa укажите URL webhook на …/assets/components/msp3yookassa/webhook.php.
В Системные настройки заполните msp3yookassa_shop_id и msp3yookassa_secret_key (боевые или test_).