Інтеграція 1С-Бітрікс із платіжною системою Stripe

Інтеграція 1С-Bitrix з платіжною системою Stripe

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

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

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

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

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

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

Архітектура модуля в Bitrix

Обробник платіжної системи — клас, унаслідуваний від \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 незалежно від поведінки браузера.

В Bitrix вебхук обробляється в 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 — оновлюємо статус у Bitrix. Stripe допускає кілька часткових повернень до повної суми транзакції.

Налаштування в адміністративній панелі Bitrix

У тестовому режимі використовуємо карту 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.

Терміни