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

Ниже путь от установки пакета до первой оплаты в sandbox и выхода в production. Официальные материалы Yandex: регистрация, настройки магазина, тестирование, план интеграции. Кабинет: console.pay.yandex.ru.

Требования

Требование	Версия
MODX Revolution	3.0+
PHP	8.2+
MiniShop3	установлен
HTTPS	публичный URL сайта (webhook с localhost не дойдёт)
Кабинет Яндекс Пэй	организация и магазин в консоли

По умолчанию пакет работает в sandbox. В production вы переходите сами, когда sandbox уже проверен.

Шаг 1: Установка пакета

1. Убедитесь, что установлен MiniShop3.
2. Управление пакетами → установите mspYandexPay.
3. Управление → Очистить кэш.
4. Проверьте плагин mspyandexpay_bootstrap на событии OnMODXInit. Он должен быть включён, иначе классы MspYandexPay\ не загрузятся.

Шаг 2: Тестовые доступы в кабинете

Без одобренной заявки на сервис Merchant ID для API не появится. Это нормально: сначала организация, потом сервис, потом ключи.

1. Войдите в Яндекс ID и откройте анкету регистрации.
2. Добавьте организацию по ИНН или названию. Если её нет в списке, подождите: база обновляется около двух суток после появления юрлица или ИП в реестре.
3. Подтвердите контакты. После этого откроется кабинет, вы станете владельцем организации.
4. Подайте заявку на Яндекс Пэй и Сплит (онлайн-магазин + API):
   • первый раз: раздел Сервисы
   • следующие магазины: Магазины → Подключить магазин
   • формат Онлайн: название, сайт, вид деятельности, БИК и расчётный счёт, контактное лицо → Подключить
5. Дождитесь звонка поддержки и одобрения. Статус смотрите на главной, в Сервисы и в почте.
6. Выберите нужный магазин в селекторе кабинета.
7. Откройте Настройки и включите Тестовые данные (переключатель тестового контура в правом верхнем углу раздела).
8. Скопируйте Merchant ID: Настройки → Merchant ID.
9. В sandbox ключ Merchant API = Merchant ID. Отдельный ключ выпускать не нужно. В поле ключа должно стоять то же значение, что и Merchant ID.

Merchant ID, API Key и Callback для sandbox и production разные. Смотрите тестовые значения только при включённых Тестовых данных.

Шаг 3: Ключи sandbox в MODX

1. Настройки → Системные настройки, фильтр mspyandexpay.
2. Заполните:

Настройка	Значение
mspyandexpay_environment	sandbox
mspyandexpay_merchant_id	Merchant ID из кабинета (тестовый контур)
mspyandexpay_api_key	тот же Merchant ID
mspyandexpay_debug	Да на время отладки

Полный список ключей: Системные настройки.

Шаг 4: Callback URL для sandbox

Без webhook заказ в MODX сам в «оплачен» не перейдёт, даже если покупатель успешно заплатил в форме Yandex.

1. В кабинете при включённых Тестовых данных укажите Callback URL:

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

1. URL должен быть HTTPS и доступен с интернета. Локальный localhost Yandex не достучится.
2. В кабинете URL для теста и боя хранятся отдельно. Переключили контур — проверьте, что Callback всё ещё заполнен для текущего режима.

Как компонент разбирает JWT: Интеграция, webhook.

Шаг 5: Способ оплаты в MiniShop3

При установке резолвер создаёт четыре способа:

Название	Класс	По умолчанию
Яндекс Пэй	MspYandexPay\Payment\YandexPayPayment	active
Яндекс Пэй (двухстадийная)	MspYandexPay\Payment\YandexPayTwoStagePayment	active
Яндекс Пэй + Сплит	MspYandexPay\Payment\YandexPaySplitPayment	active
Яндекс Пэй QR	MspYandexPay\Payment\YandexPayQrPayment	inactive

1. MiniShop3 → Настройки → Оплаты.
2. Включите нужный способ (Активен).
3. Проверьте привязку к доставкам. Резолвер сам линкует активные оплаты ко всем активным доставкам. Если способа нет на чекауте, откройте доставку и отметьте «Яндекс Пэй*» вручную.
4. Убедитесь, что способ виден на странице оформления заказа.

Для первого прогона хватит способа Яндекс Пэй. Split, двухстадийную и QR подключайте после того, как one-stage в sandbox отработал.

Шаг 6: Первая оплата в sandbox

1. Создайте заказ в MiniShop3 и выберите Яндекс Пэй (или «+ Сплит» / «Двухстадийная», если уже проверяете их).
2. Откройте paymentUrl. В адресе должен быть префикс sandbox, например https://sandbox.pay.ya.ru/l/... или .../o/.... Если префикса нет, вы уже не в тестовом контуре.
3. Войдите реальным Яндекс ID покупателя (телефон + SMS). Боевую карту не вводите: форма sandbox сама подставляет список тестовых карт.
4. Выберите карту и сценарий из таблицы ниже.
5. Дождитесь редиректа (onSuccess / onError) и webhook. В error log MODX ищите строки с [mspYandexPay].

Официально про эмуляцию: Тестирование Yandex.

Тестовые карты и суммы

Номер карты (PAN) вручную не набирают. После входа Яндекс ID форма показывает готовые тестовые карты: МИР, VISA и другие.

Результат	Как воспроизвести	Статус в API
Оплата прошла	Сумма любая, кроме 10001 и 10002 ₽ → карта МИР	CAPTURED (one-stage)
Оплата не прошла	Сумма 10001.00 ₽ → МИР	FAILED
Недостаточно средств	Сумма 10002.00 ₽ → МИР	ошибка в форме, можно сменить карту
Карта не подходит	в форме выберите VISA	ошибка в форме, можно сменить карту

У Yandex бывает пометка, что эмуляции временно недоступны. Если заказы на 10001 / 10002 проходят как обычный успех, смотрите UI формы и ответ GET /orders/{orderId}, а не только сумму.

Что прогнать в sandbox

Пройдите сценарии по очереди:

1. One-stage CARD — способ «Яндекс Пэй», сумма не 10001/10002, МИР → CAPTURED, заказ MS3 в статусе paid.
2. Fail — заказ на 10001.00, МИР → FAILED, редирект на ошибку.
3. Split — способ «Яндекс Пэй + Сплит», в форме оплата «частями», МИР → успех.
4. Two-stage — способ «Двухстадийная», МИР → AUTHORIZED (заказ ещё не paid). Затем capture через connector. Two-stage на sandbox часто включают через поддержку Yandex.
5. Refund — после CAPTURED полный или частичный возврат через connector.

Capture и refund (нужна сессия менеджера MODX):

assets/components/mspyandexpay/connector.php?action=capture&order_id=<id>&ctx=mgr
assets/components/mspyandexpay/connector.php?action=refund&order_id=<id>&ctx=mgr
assets/components/mspyandexpay/connector.php?action=refund&order_id=<id>&amount=10.00&ctx=mgr

Подробности: Интеграция, возврат.

Webhook приходит только на Callback URL вашего Merchant ID. Публичный demo Merchant ID из примеров Yandex на ваш сайт ничего не шлёт.

Base URL sandbox: https://sandbox.pay.yandex.ru/api/merchant/v1 (refund — v2). JWKS: https://sandbox.pay.yandex.ru/api/jwks.

Шаг 7: Выход в production

Выходите в бой после успешного sandbox и уведомления Yandex о подключении сервиса. Пока mspyandexpay_environment не равен production, пакет остаётся на sandbox (любое другое значение тоже считается sandbox).

Боевые доступы в кабинете

1. Дождитесь письма или статуса в кабинете о подключении сервиса. Без этого боевой контур может быть закрыт.
2. Выберите нужный магазин в селекторе.
3. Откройте Настройки и выключите Тестовые данные. Боевые Merchant ID, ключ и Callback смотрите только в этом режиме.
4. Скопируйте боевой Merchant ID. Не оставляйте sandbox-значение, если кабинет показывает другой идентификатор.
5. Выпустите ключ: Настройки → Выпустить ключ Merchant API. Полную строку показывают один раз. Скопируйте сразу: повторно открыть уже созданный ключ нельзя.
6. Если ключ потеряли: Ключ Merchant API → Выпустить еще ключ. На магазин одновременно не больше трёх ключей. Новый ключ сразу запишите в MODX.
7. В бою в mspyandexpay_api_key указывайте выпущенный ключ. Подставить Merchant ID вместо ключа можно только в sandbox.
8. Задайте боевой Callback URL (тот же путь webhook.php на боевом домене):

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

1. Если используете Yandex Checkout, укажите боевые URL того же домена:

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

1. Двухстадийные платежи в кабинете Yandex включите отдельно, если они нужны на проде.

Настройка в MODX

Настройка	Значение
mspyandexpay_environment	production
mspyandexpay_merchant_id	боевой Merchant ID
mspyandexpay_api_key	выпущенный ключ Merchant API
mspyandexpay_debug	Нет после проверки

Меняйте environment, merchant_id и api_key вместе.

Пустой api_key компонент подставит из Merchant ID. Этого хватает только sandbox. production с sandbox-ключом даёт ошибки авторизации. sandbox с боевым ключом всё равно ходит на sandbox.pay.yandex.ru.

Если заданы mspyandexpay_success_url и mspyandexpay_fail_url, на проде это должны быть HTTPS-адреса боевого домена.

Ставьте production вручную в системных настройках, когда ключи, Callback и HTTPS уже боевые. Не переключайте среду деплоем, скриптом или «значением по умолчанию» в коде.

Проверка на боевом сайте

1. Создайте заказ на боевом сайте, выберите Яндекс Пэй.
2. Откройте paymentUrl. В адресе не должно быть префикса sandbox (в тесте это как раз https://sandbox.pay.ya.ru/...).
3. Оплатите реальной картой на минимальную сумму. Деньги спишутся.
4. Проверьте webhook и смену статуса заказа. В логе ищите [mspYandexPay]. Ответ webhook 401 чаще всего значит, что environment и JWKS не совпадают с контуром кабинета.
5. Capture и refund на проде проверяйте на живом платеже и сразу возвращайте деньги покупателю.

Base URL production: https://pay.yandex.ru/api/merchant/v1 (refund — v2). JWKS: https://pay.yandex.ru/api/jwks.

Фискализацию после выхода в бой настраиваете в кабинете Yandex или своим ОФД: Фискализация. Компонент чек 54-ФЗ в Merchant API не собирает.

Типовые сбои при смене контура: FAQ.

Что дальше

• Системные настройки: методы оплаты, URL возврата, QR, статус после возврата
• Интеграция и сценарии: webhook JWT, capture, Split, кнопка на витрине
• FAQ: webhook 401, статусы, повторный send