Настройка возвратов для ЮKassa

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

Как устроен возврат в связке Битрикс и ЮKassa

В 1С-Битрикс возврат денег живёт внутри сущности оплаты (Payment) в модуле sale. Когда вы нажимаете «Вернуть оплату» на вкладке оплаты заказа, платёжный обработчик формирует запрос к API ЮKassa на создание возврата (refund). ЮKassa проверяет исходный платёж и, если возврат допустим, отправляет деньги покупателю тем же способом, которым он платил.

Важно понимать разделение ролей:

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

Настройка обработчика оплаты ЮKassa

Платёжная система настраивается в Магазин → Настройки → Платёжные системы (административный путь /bitrix/admin/sale_pay_system.php). Обработчик называется ЮKassa (в старых сборках — «Яндекс.Касса», внутренний код yandexcheckout). Для работы возвратов в бизнес-настройках обработчика должны быть заполнены:

• shopId — идентификатор магазина из личного кабинета ЮKassa;
• Секретный ключ — API-ключ, выпущенный в разделе «Интеграция → Ключи API»;
• соответствие статусов оплаты Битрикса статусам платежа ЮKassa.

Ключ должен быть именно секретным ключом магазина, а не токеном для тестовых запросов: возврат — это операция списания у магазина, и она требует прав на управление платежами. После смены ключа в кабинете ЮKassa обязательно обновите его в настройках обработчика, иначе запросы на возврат начнут возвращать ошибку авторизации.

Требования API ЮKassa к возврату

API ЮKassa разрешает возврат не для любого платежа. Ключевые условия, которые обработчик и оператор должны учитывать:

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

Полный возврат из админки заказа

Стандартный сценарий — ручной возврат оператором. Порядок действий:

1. Откройте заказ в Магазин → Заказы и перейдите на вкладку Оплата.
2. Найдите оплату, проведённую через ЮKassa (статус «Оплачено»).
3. Нажмите «Вернуть оплату» — Битрикс вызовет метод возврата обработчика и отправит запрос в API ЮKassa на полную сумму.
4. Дождитесь ответа: при успехе статус оплаты меняется на «Возвращено», а в истории заказа фиксируется операция.

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

Частичный возврат

ЮKassa поддерживает частичные возвраты, в том числе несколько по одному платежу, пока их сумма не превысит оплаченную. В Битрикс это применимо, когда покупатель возвращает часть товаров из заказа. Практическая схема:

• уменьшите состав или сумму заказа/оплаты на возвращаемую позицию;
• оформите возврат на сумму именно этой позиции, а не всего заказа;
• оставшаяся оплаченная часть продолжает числиться за заказом.

Здесь есть тонкость: базовая кнопка возврата в интерфейсе рассчитана прежде всего на полный возврат оплаты. Гибкий частичный возврат с точной суммой и корректным составом чека часто требует доработки обработчика или отдельного механизма, который формирует запрос refund с нужной суммой и позициями. Планируйте это заранее, если у вас частые частичные возвраты.

Чек возврата и 54-ФЗ

Если магазин работает по 54-ФЗ, каждый возврат денег должен сопровождаться чеком возврата прихода. За фискализацию отвечает модуль онлайн-касс (sale, раздел Магазин → Кассы ККМ / Онлайн-кассы), а не сам платёжный обработчик.

• При настроенной кассе Битрикс автоматически ставит в очередь чек возврата после успешного возврата оплаты;
• в составе чека возврата должны быть те же позиции (или их часть при частичном возврате), что были в чеке прихода;
• признак расчёта в таком чеке — «возврат прихода».

ЮKassa также умеет формировать чеки как ОФД-посредник — тогда объект receipt передаётся прямо в запросе платежа и возврата. Выберите одну схему фискализации (через свою кассу в Битрикс или через ЮKassa) и не дублируйте чеки: двойная фискализация одной операции — частая и болезненная ошибка.

Автоматизация и типовые ошибки

Помимо ручного возврата из админки, возвраты можно инициировать программно — из бизнес-процесса, обработчика события заказа или внешней CRM через API. Технически это вызов метода возврата платёжной системы для нужной оплаты; логику «когда и на сколько возвращать» вы задаёте сами.

Что чаще всего ломает возвраты на практике:

• Устаревший или неверный секретный ключ — запросы падают с ошибкой авторизации;
• Возврат платежа не в том статусе — попытка вернуть неподтверждённый или уже возвращённый платёж;
• Рассинхрон сумм между заказом, оплатой и чеком возврата;
• Отсутствие обработки ответа ЮKassa — возврат ушёл, а статус в Битрикс не обновился.

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

Итог

Возврат через ЮKassa в 1С-Битрикс складывается из трёх слоёв: корректно настроенного обработчика платёжной системы с актуальными shopId и секретным ключом, соблюдения требований API ЮKassa к статусу и сумме платежа, и правильной фискализации чека возврата по 54-ФЗ. Ручной полный возврат работает «из коробки», а частичные возвраты и автоматизацию обычно приходится доводить под конкретный магазин.

Мы в B2Bsite настраиваем и дорабатываем возвраты ЮKassa под реальные сценарии магазина — от частичных возвратов и корректных чеков до интеграции с CRM и учётной системой, — и берём такие связки на поддержку, чтобы деньги и фискальные документы всегда сходились.