Дополнение подключает оплату заказов через Merchant API Яндекс Пэй и поддерживает несколько сценариев оплаты: обычную оплату, двухстадийную оплату, Яндекс Сплит и оплату по QR-коду.

После создания платежа покупатель перенаправляется на страницу оплаты Яндекс Пэй, а результат оплаты передаётся обратно на сайт через защищённый webhook. Статус заказа MiniShop3 автоматически обновляется в соответствии со статусом платежа.

Возможности

• Оплата через Яндекс Пэй — стандартная одностадийная схема оплаты.
• Двухстадийная оплата — сначала блокировка средств, затем подтверждение или отмена платежа.
• Яндекс Сплит — возможность оплатить покупку частями.
• Оплата по QR-коду — отдельный способ оплаты через Яндекс Пэй.
• Автоматическая обработка webhook — получение статусов платежей от Яндекс Пэй.
• Проверка подписи webhook с использованием JWKS и алгоритма ES256.
• Возвраты — поддержка полного и частичного возврата платежа.
• Кнопка оплаты на витрине — можно использовать сниппет mspYandexPayButton отдельно от стандартного процесса оформления заказа.
• Sandbox — возможность протестировать интеграцию до перехода в production.
• Production — переключение на рабочую среду после завершения тестирования.

Способы оплаты

После установки дополнения в MiniShop3 доступны следующие способы оплаты:

• Яндекс Пэй — одностадийная оплата;
• Яндекс Пэй (двухстадийная) — оплата с предварительной авторизацией;
• Яндекс Пэй + Сплит — оплата покупки частями;
• Яндекс Пэй QR — оплата по QR-коду.

Способы оплаты автоматически добавляются к доступным способам доставки MiniShop3. При необходимости их можно настроить отдельно для каждой доставки.

Безопасный webhook

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

Дополнение принимает JWT от Яндекс Пэй и проверяет его подпись по публичным ключам JWKS. Поддерживаются отдельные настройки для sandbox и production.

Callback URL имеет следующий вид:

https://ваш-домен.ru/assets/components/mspyandexpay/webhook.php

Через webhook обрабатываются изменения состояния заказа и операций. Благодаря этому статус заказа в MiniShop3 обновляется автоматически после изменения состояния платежа.

Двухстадийная оплата

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

После этого магазин может:

• подтвердить платёж и выполнить списание;
• отменить авторизацию.

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

Возвраты

Дополнение поддерживает возврат платежей через API Яндекс Пэй.

• полный возврат;
• частичный возврат.

После полного возврата можно автоматически перевести заказ MiniShop3 в указанный статус возврата.

Sandbox и тестирование

mspYandexPay поддерживает тестовую среду Яндекс Пэй.

Можно сначала настроить интеграцию, выполнить тестовую оплату и проверить обработку webhook, статусы заказа и возвраты, а затем переключиться на production.

Это позволяет проверить интеграцию с MiniShop3 до начала приёма реальных платежей.

Требования

• MODX Revolution — 3.0 и выше;
• PHP — 8.2 и выше;
• MiniShop3 — 1.0 и выше;
• HTTPS — обязателен для работы webhook и Checkout.

Необходимые PHP-зависимости входят в пакет. Отдельно устанавливать Composer на сайте не требуется.

Установка

1. Установите MiniShop3.
2. Установите пакет mspYandexPay через «Управление пакетами».
3. Очистите кэш MODX.
4. Укажите Merchant ID и API Key в системных настройках дополнения.
5. Выберите среду — Sandbox или Production.
6. Укажите Callback URL в кабинете Яндекс Пэй.
7. Проверьте доступные способы оплаты и их привязку к доставкам MiniShop3.

Что нужно получить в Яндекс Пэй

Для работы дополнения необходимо подключить магазин в Яндекс Пэй и получить данные Merchant API:

• Merchant ID;
• Ключ Merchant API.

Для тестирования можно использовать Sandbox, после чего переключиться на рабочую среду.

Интеграция с MiniShop3

Дополнение использует штатные механизмы MiniShop3 для работы с заказами, способами оплаты и статусами. Установка не требует изменения ядра MiniShop3.

В результате покупатель проходит обычный процесс оформления заказа MiniShop3, выбирает Яндекс Пэй, выполняет оплату на стороне сервиса и возвращается на сайт. Информация о результате платежа передаётся через webhook и используется для обновления заказа.

Для разработчиков

Дополнение построено вокруг Merchant API Яндекс Пэй и предоставляет отдельные компоненты для различных сценариев оплаты.

В состав входят:

• способы оплаты MiniShop3;
• webhook для обработки событий Яндекс Пэй;
• поддержка одностадийных и двухстадийных платежей;
• операции возврата;
• сниппет mspYandexPayButton;
• поддержка Sandbox и Production;
• настройки дополнения в пространстве имён mspyandexpay.