Интеграция 1С-Битрикс с платежной системой ЮKassa

Интеграция 1С-Битрикс с платёжной системой ЮКасса

ЮКасса (бывший ЯндексКасса) — один из наиболее распространённых платёжных агрегаторов в российском e-commerce. За внешней простотой «подключите модуль из маркетплейса» скрывается несколько технических нюансов: работа с уведомлениями, фискализация по 54-ФЗ, обработка возвратов и подбор правильного режима подтверждения платежа. Разберём всё по порядку.

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

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

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

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

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

Варианты интеграции в 1С-Битрикс

Официальный модуль. ЮКасса предоставляет официальный модуль для Битрикс, доступный бесплатно через Маркетплейс (yoomoney.cms.bitrix) и на GitHub. Устанавливается через /bitrix/admin/update_system.php, настройки — в Магазин → Настройки → Платёжные системы. Модуль использует официальную PHP-библиотеку yoomoney/yookassa-sdk-php.

Кастомный обработчик требуется когда: нужна нестандартная логика статусов заказов, проект использует не стандартный модуль sale, или нужна кастомная фискализация. Размещается в /local/php_interface/include/sale_payment/yookassa_custom/.

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

// Минимальный запрос на создание платежа через 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 — двухстадийный: ЮКасса холдирует сумму, магазин вызывает POST /payments/{id}/capture при отгрузке.

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

Фискализация (54-ФЗ)

Если в договоре с ЮКассой подключена передача чеков, объект receipt в запросе становится обязательным. Без него транзакция будет отклонена. Структура:

$receiptData = [
    'customer' => [
        'email' => $buyer->getEmail(),
        'phone' => $buyer->getPersonalPhone(),  // хотя бы одно из двух
    ],
    'items' => [],
];

foreach ($basket->getOrderableItems() as $item) {
    $receiptData['items'][] = [
        'description'     => $item->getField('NAME'),
        'quantity'        => $item->getQuantity(),
        'amount'          => [
            'value'    => number_format($item->getPrice(), 2, '.', ''),
            'currency' => 'RUB',
        ],
        'vat_code'        => 1,  // 1=без НДС, 2=0%, 3=10%, 4=20%
        'payment_subject' => 'commodity',   // признак предмета расчёта
        'payment_mode'    => 'full_payment', // признак способа расчёта
    ];
}

// Не забыть доставку как отдельную позицию
if ($delivery->getPrice() > 0) {
    $receiptData['items'][] = [
        'description'     => 'Доставка',
        'quantity'        => 1,
        'amount'          => ['value' => number_format($delivery->getPrice(), 2, '.', ''), 'currency' => 'RUB'],
        'vat_code'        => 1,
        'payment_subject' => 'service',
        'payment_mode'    => 'full_payment',
    ];
}

Сумма всех позиций в чеке должна точно совпадать с суммой платежа — ЮКасса проверяет это и отклоняет несоответствия.

Обработка webhook-уведомлений

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

Критически важные вещи при обработке:

// 1. Проверяем IP-адрес источника (ЮКасса публикует список своих IP)
$allowedIPs = ['185.71.76.0/27', '185.71.77.0/27', '77.75.153.0/25', '77.75.156.11', '77.75.156.35'];

// 2. Читаем тело запроса
$body = file_get_contents('php://input');
$notification = json_decode($body, true);

// 3. Верифицируем через API (не доверяем данным из webhook напрямую)
$payment = $client->getPaymentInfo($notification['object']['id']);

// 4. Обрабатываем только терминальные статусы
switch ($payment->getStatus()) {
    case 'succeeded':
        $bitrixPayment->setPaid('Y');
        $bitrixPayment->save();
        break;
    case 'canceled':
        // Записываем причину отмены из $payment->getCancellationDetails()
        break;
}

Таблица статусов платежа ЮКассы:

Возвраты

ЮКасса поддерживает частичный и полный возврат через POST /refunds:

$refund = $client->createRefund([
    'payment_id' => $externalPaymentId,
    'amount'     => ['value' => $refundAmount, 'currency' => 'RUB'],
    'description' => 'Возврат по заказу №' . $orderNumber,
    'receipt'    => $refundReceiptData,  // обязателен при кассе
], uniqid('', true));

При подключённой кассе возврат без чека отклоняется. Чек возврата зеркально дублирует позиции оригинального чека с типом refund.

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

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

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

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

Сроки