Интеграция Ю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-ФЗ читайте в Википедии.