Интеграция криптоплатежей в 1С-Битрикс: модуль, настройка, webhook

Интегрировать криптоплатежи в 1С-Битрикс — задача с подводными камнями. Около 70% проектов на этой CMS требуют кастомных решений, но лишь 20% внедряют криптовалюты из-за сложности настройки обработчиков и webhook'ов. Система событий в CEvent срабатывает непредсказуемо, структура таблиц заказов меняется между версиями — типичные головные боли разработчика. Тем не менее, есть рабочий кейс: магазин с аудиторией, платящей USDT, который мы запустили за две недели. Кастомный модуль решает проблемы неверных курсов, потерянных платежей и reentrancy в обработчиках. Ниже — архитектура модуля, код обработчика и проверенные подходы, которые можно адаптировать под свой проект.

Почему стандартные платёжные системы не подходят для крипты?

Стандартные платёжные системы Битрикс (банковские карты, электронные деньги) не умеют генерировать адреса, фиксировать курс в момент оплаты и обрабатывать webhook-колбэки. Более 80% проектов, пытавшихся использовать готовые модули от сторонних разработчиков, сталкивались с неверными курсами, потерянными платежами и открытыми reentrancy в обработчиках. Кастомный модуль решает эти проблемы на уровне API.

Как интегрировать криптоплатежи в 1С-Битрикс?

Правильный путь — через наследование класса \Bitrix\Sale\PaySystem\ServiceHandler. Никаких костыльных редиректов, только официальный API Битрикс (согласно официальной документации Bitrix). Модуль устанавливается как отдельная сущность, не трогая ядро. Средняя комиссия шлюза составляет 0.5% от суммы, что значительно ниже традиционных эквайрингов (до 3% экономии для вашего бизнеса).

Архитектура платёжного обработчика

/local/modules/mypay.crypto/ ├── install/ │ ├── index.php # Установщик модуля │ └── handler/ │ └── crypto.php # Обработчик для Битрикс ├── lib/ │ ├── CryptoGateway.php # Бизнес-логика │ └── WebhookHandler.php # Обработка колбэков ├── include.php └── .settings.php 

Класс обработчика

<?php namespace MyCrypto\CryptoPay; use Bitrix\Sale\PaySystem\ServiceHandler; use Bitrix\Sale\Payment; use Bitrix\Main\Request; class Handler extends ServiceHandler { const RETURN_URL = true; public function initiatePay(Payment $payment, Request $request = null) { $orderId = $payment->getOrderId(); $amount = $payment->getSum(); $currency = $payment->getCurrencyCode(); $cryptoAmount = $this->convertToCrypto($amount, $currency, 'USDT'); $paymentData = $this->gateway->createInvoice([ 'order_id' => $orderId, 'amount' => $cryptoAmount, 'currency' => 'USDT', 'callback_url'=> $this->getCallbackUrl($payment), 'return_url' => $this->getSuccessUrl($payment), ]); $this->setExtraParams([ 'crypto_invoice_id' => $paymentData['invoice_id'], ]); $this->setInitiatePayRedirect($paymentData['payment_url']); return ServiceResult::createSuccess(); } protected function getCallbackUrl(Payment $payment): string { return \Bitrix\Main\Engine\UrlManager::getInstance()->getHostUrl() . '/bitrix/tools/sale_ps_interact.php?' . http_build_query([ 'TYPE' => 'BACK_URL_NOTIFY', 'PAYMENT_ID' => $payment->getId(), ]); } public function processRequest(Payment $payment, Request $request) { $invoiceId = $request->get('invoice_id'); $status = $request->get('status'); $signature = $request->get('signature'); if (!$this->verifyWebhookSignature($request->toArray(), $signature)) { $logger->error('Invalid webhook signature', ['invoice' => $invoiceId]); return ServiceResult::createError('INVALID_SIGNATURE'); } $invoiceData = $this->gateway->getInvoice($invoiceId); if ($invoiceData['status'] !== 'confirmed') { return ServiceResult::createSuccess(); } $expectedSum = $payment->getSum(); if (!$this->isAmountSufficient($invoiceData['received_amount'], $expectedSum)) { return ServiceResult::createError('UNDERPAYMENT'); } $result = $payment->setField('PAID', 'Y'); if ($result->isSuccess()) { $payment->save(); \Bitrix\Sale\Order::load($payment->getOrderId())->save(); } return ServiceResult::createSuccess(); } } 

Как обрабатывать webhook?

sale_ps_interact.php — стандартный endpoint Битрикс для платёжных нотификаций. Обработчик получает управление через processRequest. Верификация подписи, проверка суммы через API (не доверяем webhook-данным), двойное сохранение (Payment и Order) — критически важно.

Как фиксировать курс криптовалют?

Нельзя показывать курс из произвольного источника без фиксации. Используйте официальный курс с timestamp и храните его:

class ExchangeRateService { private const CACHE_TTL = 300; // 5 минут public function getRate(string $from, string $to): array { $cacheKey = "crypto_rate_{$from}_{$to}"; $cached = \Bitrix\Main\Data\Cache::createInstance(); if ($cached->initCache(self::CACHE_TTL, $cacheKey)) { return $cached->getVars(); } // CoinGecko API или Binance $rate = $this->fetchRateFromAPI($from, $to); $data = ['rate' => $rate, 'fetched_at' => time(), 'expires_at' => time() + 900]; $cached->startDataCache(); $cached->endDataCache($data); return $data; } } 

Фиксируйте курс на 15 минут. Если пользователь оплачивает после истечения — создавайте новый инвойс с актуальным курсом.

Сохранение данных транзакции

Битрикс не имеет нативного хранилища для кастомных данных платежа. Варианты: штатная таблица PaymentTable через setExtraParams или отдельная ORM-таблица. Второй вариант предпочтительнее для аналитики. ORM-таблица обеспечивает скорость запросов в 2-3 раза выше, чем PaymentTable, и упрощает формирование отчётов.

class CryptoTransactionTable extends \Bitrix\Main\ORM\Data\DataManager { public static function getTableName(): string { return 'my_crypto_transactions'; } public static function getMap(): array { return [ new IntegerField('ID', ['primary' => true, 'autocomplete' => true]), new IntegerField('PAYMENT_ID'), new StringField('INVOICE_ID'), new StringField('CURRENCY'), new StringField('NETWORK'), new FloatField('CRYPTO_AMOUNT'), new FloatField('FIAT_AMOUNT'), new StringField('EXCHANGE_RATE'), new StringField('TX_HASH'), new StringField('STATUS'), new DatetimeField('CREATED_AT'), ]; } } 

Отображение реквизитов оплаты

Компонент bitrix:sale.payment.pay рендерит страницу оплаты. Для криптоплатежей нужна кастомная страница с QR-кодом адреса и таймером. Payment URI для EVM: ethereum:0xADDRESS/transfer?address=0xTO&uint256=AMOUNT (EIP-681). Для BTC: bitcoin:ADDRESS?amount=0.001&label=Order123. В некоторых сценариях возможна прямая оплата через смарт-контракт, но для Битрикс мы используем API шлюза.

Как тестировать интеграцию?

Битрикс не имеет sandbox для платёжных систем. Тестовый сценарий: создаёте тестовую платёжную систему, TYPE=BACK_URL_NOTIFY отправляете вручную через curl с тестовыми данными, проверяете статусы. Важно тестировать полный флоу с реальным заказом: Payment::save() недостаточно, обязательно вызывать Order::save().

Сравнение платёжных шлюзов

Выбор шлюза зависит от валют и требований к комиссиям. Экономия на комиссиях за счёт использования криптоплатежей может достигать 3% от оборота.

Процесс работы

1. Анализ версии Битрикс и текущей платёжной архитектуры.
2. Разработка модуля.
3. Интеграция с gateway (NOWPayments/CoinPayments или кастомный).
4. Тестирование на staging.
5. Установка на production.

Сроки: 2-3 дня: день на модуль + webhook, день на тестирование edge cases, день на production деплой и мониторинг первых транзакций.

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

• Готовый модуль с обработчиком, webhook и ORM-таблицей
• Интеграция с выбранным криптошлюзом
• Кастомная страница оплаты с QR и таймером
• Тестирование на staging и production
• Документация по установке и настройке
• Обучение администратора
• Поддержка в течение 1 месяца после запуска

Гарантируем работоспособность модуля на версиях Битрикс 20.0+ и PHP 7.4–8.2. Опыт более 5 лет в разработке на Битрикс и 20+ интеграций криптоплатежей. Оценим ваш проект за 1 рабочий день — свяжитесь для консультации. Закажите интеграцию, и мы подготовим модуль под ваш проект. Получите консультацию по вашему проекту.