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

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

Stripe — платёжная платформа с REST API, покрывающая весь цикл: авторизация карты, захват средств, возвраты, подписки, 3D Secure. Документация полная, SDK для PHP официальный. Для интернет-магазинов на Битрикс это один из наиболее предсказуемых в интеграции платёжных шлюзов.

Stripe работает с картами Visa, Mastercard, AmEx, Apple Pay, Google Pay и рядом локальных методов (SEPA, iDEAL, Klarna и др.). Доступность зависит от страны регистрации аккаунта мерчанта.

Два подхода к интеграции

Stripe Checkout (hosted page). Покупатель перенаправляется на страницу Stripe или открывает её в модальном окне. Stripe берёт на себя все вопросы PCI DSS и 3D Secure. Минимум кода на стороне Битрикс — достаточно создать Checkout Session через API и отдать URL редиректа.

Stripe Elements / Payment Intents. Форма оплаты встроена прямо на страницу оформления заказа. Данные карты никогда не касаются сервера мерчанта — вводятся в iframe Stripe. Требует JavaScript на фронте и серверной логики для создания PaymentIntent. Дизайн полностью кастомизируется.

Для большинства магазинов на Битрикс рекомендуем Checkout: меньше кода, меньше точек отказа, Stripe обновляет 3DS-логику автоматически.

Архитектура модуля в Битрикс

Обработчик платёжной системы — класс, унаследованный от \Bitrix\Sale\PaySystem\ServiceHandler. Дополнительно реализуем \Bitrix\Sale\PaySystem\IRefund для возвратов.

Ключевые методы:

• initiatePay() — создаёт Checkout Session через stripe-php SDK, записывает session_id в b_sale_payment.PS_INVOICE_ID, возвращает URL для редиректа.
• processRequest() — обрабатывает вебхук checkout.session.completed или payment_intent.succeeded. Верифицирует подпись через \Stripe\Webhook::constructEvent() с STRIPE_WEBHOOK_SECRET.
• refund() — создаёт объект \Stripe\Refund по payment_intent из PS_INVOICE_ID.

Создание Checkout Session

\Stripe\Stripe::setApiKey($secretKey);

$session = \Stripe\Checkout\Session::create([
    'payment_method_types' => ['card'],
    'line_items' => [[
        'price_data' => [
            'currency'     => 'eur',
            'unit_amount'  => $amountInCents, // сумма в центах
            'product_data' => ['name' => 'Заказ №' . $orderId],
        ],
        'quantity' => 1,
    ]],
    'mode'        => 'payment',
    'success_url' => $successUrl . '?session_id={CHECKOUT_SESSION_ID}',
    'cancel_url'  => $cancelUrl,
    'metadata'    => ['bitrix_order_id' => $orderId],
]);

{CHECKOUT_SESSION_ID} — специальный плейсхолдер Stripe, он подставляет реальный ID на своей стороне. По нему в processRequest() сверяем, что сессия принадлежит нашему заказу.

Обработка вебхуков

Вебхуки важнее, чем success_url — покупатель может закрыть вкладку до редиректа. Stripe отправляет событие checkout.session.completed на наш endpoint независимо от поведения браузера.

В Битрикс вебхук обрабатывается в processRequest(). Обязательные проверки:

1. Верификация подписи через Stripe-Signature заголовок — без неё любой может имитировать платёж.
2. Идемпотентность — событие может прийти дважды. Перед сменой статуса заказа проверяем текущий статус в b_sale_order.
3. Ответ 200 OK в течение 3 секунд — иначе Stripe повторит доставку.

В панели Stripe Dashboard → Webhooks регистрируем endpoint и подписываемся на события: checkout.session.completed, payment_intent.payment_failed, charge.refunded.

Возвраты и частичные возвраты

$refund = \Stripe\Refund::create([
    'payment_intent' => $paymentIntentId,
    'amount'         => $refundAmountInCents, // не передавать для полного возврата
    'reason'         => 'requested_by_customer',
]);

После создания возврата приходит вебхук charge.refunded — обновляем статус в Битрикс. Stripe допускает несколько частичных возвратов до полной суммы транзакции.

Настройки в административной панели Битрикс

В тестовом режиме используем карту 4242 4242 4242 4242, любой срок, любой CVC. Для проверки отклонения — 4000 0000 0000 0002.

Apple Pay и Google Pay

При использовании Stripe Checkout оба метода включаются автоматически, если домен верифицирован в Stripe Dashboard → Payment methods → Apple Pay. Для Elements нужна дополнительная настройка Payment Request Button и верификация домена через файл .well-known/apple-developer-merchantid-domain-association.

Сроки