Подключение ЮKassa (v.17.6.0+): инструкция

Начиная с редакции 17.6.0 модуля «Интернет-магазин» в 1С-Битрикс появился отдельный штатный обработчик ЮKassa (тогда — Яндекс.Касса) с поддержкой API и фискализации по 54-ФЗ. Он заменяет устаревшую схему на MD5-подписи и настраивается полностью из административной панели, без правки файлов.

Чем обработчик 17.6.0 отличается от старого

До версии 17.6.0 приём платежей через Яндекс-сервисы в Битриксе строился на обработчике yandex со связкой shopId + scid + shopPassword и подписью MD5. Он работал по протоколу платёжных уведомлений (aviso) и не умел передавать в кассу состав чека.

Новый штатный обработчик (внутреннее имя yandex_checkout) работает по HTTP API ЮKassa и решает три задачи сразу:

• создаёт платёж через API и получает ссылку на платёжную страницу;
• принимает уведомления о смене статуса (webhook), а не только редирект покупателя;
• формирует и отправляет фискальный чек по 54-ФЗ, если у вас подключена онлайн-касса на стороне ЮKassa.

Что нужно подготовить в кабинете ЮKassa

Настройка в Битриксе бесполезна без данных из личного кабинета ЮKassa. До входа в админку соберите:

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

Создание платёжной системы в админке

В административной панели откройте Магазин → Настройки → Платёжные системы (страница /bitrix/admin/sale_pay_system.php) и нажмите «Добавить платёжную систему». Заполните шапку:

1. Название и код — например, «Оплата картой (ЮKassa)», код латиницей;
2. Обработчик — выберите из списка «ЮKassa» (или «Яндекс.Касса» в ранних сборках 17.6.x);
3. Типы плательщиков — отметьте те, кому доступна оплата (обычно «Физическое лицо»);
4. Активность — «Да».

После выбора обработчика форма перерисуется и покажет его собственные поля. Именно они отвечают за связь с API ЮKassa, поэтому заполнять их нужно внимательно.

Если магазин многосайтовый, платёжную систему создают на нужном сайте: код обработчика и настройки хранятся отдельно для каждого. Для разных типов плательщиков (например, физлицо и юрлицо) удобно завести отдельные платёжные системы с одним и тем же обработчиком, но разными параметрами чека и НДС.

Параметры обработчика: shopId, ключ, чек

В блоке настроек обработчика заполните ключевые поля:

• Идентификатор магазина — значение shopId из кабинета;
• Секретный ключ — тот самый ключ API;
• Тип платежа / способ оплаты — «Банковская карта», «ЮMoney», СБП или «Виджет» (единая платёжная страница). Виджет даёт пользователю выбор способа уже на стороне ЮKassa;
• Сумма заказа — обычно берётся из свойства заказа PAYMENT, не меняйте без необходимости.

Если подключена онлайн-касса, включите передачу чека и задайте параметры фискализации:

• Ставка НДС по умолчанию для позиций заказа;
• Признак способа расчёта и признак предмета расчёта (полный расчёт, товар/услуга);
• E-mail / телефон покупателя — привяжите к свойствам заказа, иначе чек не пробьётся.

Уведомления и возврат покупателя на сайт

Обработчик 17.6.0 полагается на два канала обратной связи. Redirect возвращает покупателя на страницу результата заказа, а webhook сообщает магазину реальный статус платежа.

В кабинете ЮKassa в разделе HTTP-уведомлений укажите адрес обработчика результата вида https://ваш-домен/bitrix/tools/sale_ps_result.php и подпишитесь на события payment.succeeded, payment.canceled и refund.succeeded. Именно уведомление, а не возврат браузером, переводит заказ в статус «Оплачен» через свойство PAYED.

Убедитесь, что путь к обработчику результата открыт снаружи и не закрыт HTTP-авторизацией или правилами веб-сервера. Уведомления ЮKassa приходят серверным запросом от шлюза, без сессии покупателя, поэтому любая защита по кукам или капче на этом URL молча сломает автоматическую отметку об оплате.

Тестирование и типовые ошибки

Перед запуском проверьте связку на тестовом магазине ЮKassa (отдельные shopId и ключ с пометкой «test»). Оформите заказ, оплатите тестовой картой и убедитесь, что заказ перешёл в «Оплачен» автоматически.

Что чаще всего ломает приём платежей:

• 401 при создании платежа — неверный или тестовый ключ на боевом магазине, либо магазин не активирован;
• Заказ висит «не оплачен» — не настроен или заблокирован URL уведомлений; проверьте доступность sale_ps_result.php и журнал в Магазин → Настройки → Журнал ошибок;
• Платёж прошёл, чека нет — не заданы признаки расчёта или контакт покупателя;
• Расхождение суммы — конфликт с округлением или скидками; сверьте итог заказа и сумму в API.

Итог

Штатный обработчик ЮKassa из редакции 17.6.0 закрывает приём карт, ЮMoney и СБП и передаёт фискальные чеки без единой строки кода — достаточно корректно перенести shopId и секретный ключ, настроить webhook и параметры чека. Главное — проверять оплату и фискализацию раздельно и не доверять статусу только по redirect.

Если нужно подключить ЮKassa под 54-ФЗ, увязать чеки с обменом «1С — сайт» или доработать нестандартную логику оплаты, мы в B2Bsite настраиваем это под ключ и берём магазин на сопровождение.