Интеграция ЮKassa в 1С-Битрикс: кастомные обработчики и 54-ФЗ

Прием платежей через ЮKassa в 1С-Битрикс

Представьте: клиент оформляет заказ, переходит на оплату — а после успешного платежа webhook не долетает, статус заказа не меняется, и деньги повисают в неизвестности. ЮKassa (бывший Яндекс.Касса) — один из самых популярных платежных агрегаторов в России, но стандартный модуль из Маркетплейса справляется не со всеми сценариями. Мы сталкивались с ситуациями, когда не приходили уведомления, возвраты падали с ошибкой, а фискализация выдавала невалидный чек. Согласно официальной документации ЮKassa, REST API версии 3 позволяет гибко управлять транзакциями, но требует аккуратной настройки. За пять лет мы выполнили более 50 интеграций — от простых магазинов до B2B-платформ с десятками тысяч транзакций ежемесячно. Ниже разберем технические детали и покажем, как избежать типовых ошибок.

Как работает ЮKassa технически

ЮKassa предоставляет REST API (api.yookassa.ru/v3/). Схема классического платежа:

1. Магазин отправляет POST /payments с суммой, валютой и confirmation.type=redirect — ЮKassa возвращает payment.id и confirmation.confirmation_url
2. Покупатель редиректируется на страницу оплаты ЮKassa
3. После оплаты ЮKassa отправляет webhook-уведомление на return_url магазина и POST на настроенный URL уведомлений
4. Магазин вызывает GET /payments/{id} для финальной проверки статуса

Аутентификация — HTTP Basic: shopId:secretKey или OAuth-токен.

Поддерживаемые методы оплаты: банковские карты, SBP, ЮMoney, SberPay, Тинькофф, QIWI (с ограничениями), наличные через терминалы. Метод передаётся в payment_method_type или выбирается покупателем на форме ЮKassa.

Почему стоит выбрать кастомную интеграцию

Официальный модуль ЮKassa для Битрикс доступен бесплатно и подходит для стандартных магазинов. Но он имеет ограничения: жёсткая привязка к стандартным компонентам, сложность кастомизации статусов заказов, отсутствие гибкой фискализации. Кастомный обработчик решает эти проблемы и позволяет интегрировать ЮKassa с любыми нестандартными сущностями. Наш опыт показывает, что кастомная интеграция в 2-3 раза быстрее справляется с нестандартными задачами по сравнению с доработкой готового модуля. Мы — сертифицированные специалисты с опытом более 5 лет, гарантируем корректную работу всех сценариев. Свяжитесь с нами для оценки вашего проекта — получите консультацию по интеграции и точные сроки для вашего случая.

Как настроить webhook для ЮKassa

ЮKassa отправляет POST на настроенный URL при каждой смене статуса платежа. В Битрикс стандартный URL обработчика: /bitrix/tools/sale_ps_result.php. Критически важные моменты:

• Проверяйте IP-адрес источника. ЮKassa публикует список своих IP: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35. Без фильтрации вы рискуете получить поддельные уведомления.
• Верифицируйте статус через API. Не доверяйте данным из webhook напрямую — сделайте GET /payments/{id} для двойной проверки.
• Обрабатывайте только терминальные статусы. pending и waiting_for_capture не требуют изменения заказа.

// Пример обработки $body = file_get_contents('php://input'); $notification = json_decode($body, true); $payment = $client->getPaymentInfo($notification['object']['id']); switch ($payment->getStatus()) { case 'succeeded': $bitrixPayment->setPaid('Y'); $bitrixPayment->save(); break; case 'canceled': // Записываем причину отмены break; } 

Ключевые параметры запроса

// Минимальный запрос на создание платежа через SDK use YooKassa\Client; $client = new Client(); $client->setAuth($shopId, $secretKey); $payment = $client->createPayment([ 'amount' => [ 'value' => number_format($order->getPrice(), 2, '.', ''), 'currency' => 'RUB', ], 'confirmation' => [ 'type' => 'redirect', 'return_url' => 'https://shop.ru/personal/order/detail/' . $order->getId() . '/', ], 'capture' => true, // false для двухстадийных платежей 'description' => 'Заказ №' . $order->getAccountNumber(), 'metadata' => ['bitrix_order_id' => $order->getId()], 'receipt' => $receiptData, // обязательно при подключённой кассе ], uniqid('', true)); // idempotency key 

capture: true — одностадийный платёж, деньги списываются сразу. capture: false — двухстадийный: ЮKassa холдирует сумму, магазин вызывает POST /payments/{id}/capture при отгрузке.

Ключ идемпотентности (третий параметр) — обязателен. Без него повторный запрос при сетевой ошибке создаст дублирующий платёж.

Фискализация (54-ФЗ) и почему она обязательна

Требования 54-ФЗ (о применении контрольно-кассовой техники) распространяются на все онлайн-платежи. ЮKassa выступает как фискальный регистратор, передавая данные в ОФД. Если в договоре с ЮKassa подключена передача чеков, объект receipt в запросе становится обязательным. Без него транзакция будет отклонена — это одна из самых частых проблем. Структура чека должна точно соответствовать требованиям 54-ФЗ. Мы используем проверенную схему с разбивкой по ставкам НДС и признакам предмета расчёта. Сумма всех позиций в чеке должна точно совпадать с суммой платежа — ЮKassa проверяет это на своей стороне. При возврате также необходим чек, зеркально отражающий позиции. В официальной документации ЮKassa приведены примеры структуры чека, но мы адаптируем их под вашу специфику.

Статусы платежа и возвраты

ЮKassa поддерживает частичный и полный возврат через POST /refunds. При подключённой кассе возврат без чека отклоняется. Чек возврата зеркально дублирует позиции оригинального чека с типом refund. Мы реализовали более 50 успешных интеграций с возвратами, гарантируем корректное отражение в бухгалтерии.

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

ЮKassa предоставляет тестовую среду с теми же endpoints. В тестовом режиме (shopId=test_...) платежи проходят с тестовыми картами:

• 5555555555554477 — успешная оплата
• 5555555555554444 — отказ

Обязательно протестируйте: успешный платёж, отмену, webhook с задержкой (покупатель закрыл браузер до редиректа), частичный возврат. Это поможет избежать проблем на боевом сайте.

Что входит в работу

• Аудит текущей конфигурации Битрикс и торгового каталога
• Разработка или доработка платёжного обработчика (с учётом 54-ФЗ)
• Настройка webhook и обработка уведомлений
• Тестирование всех сценариев в тестовой среде
• Документация по интеграции и инструкция для операторов
• Гарантийная поддержка 30 дней после ввода в эксплуатацию

Сроки и как начать

Свяжитесь с нами для оценки вашего проекта. Получите консультацию по интеграции и точные сроки для вашего случая. Более подробную информацию о платёжном API можно найти в официальной документации ЮKassa. О требованиях 54-ФЗ читайте в Википедии.