Интеграция криптоплатежей в 1С-Битрикс
1С-Битрикс — не самая удобная платформа для кастомных платёжных интеграций. Система обработчиков оплаты задокументирована частично, события в CEvent срабатывают непредсказуемо, а структура таблиц заказов менялась между версиями. Тем не менее, это реальный рабочий кейс: магазины на Битрикс, аудитория которых платит криптой — не редкость особенно в определённых нишах.
Архитектура платёжного обработчика
В Битрикс платёжные системы реализуются через класс-наследник \Bitrix\Sale\PaySystem\ServiceHandler. Это правильный путь — не хак через костыльные редиректы, а официальный API.
Структура модуля:
/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
{
// Тип обработчика: REDIRECT — пользователь идёт на внешний URL
const RETURN_URL = true;
public function initiatePay(Payment $payment, Request $request = null)
{
$orderId = $payment->getOrderId();
$amount = $payment->getSum();
$currency = $payment->getCurrencyCode(); // обычно RUB или USD
// Конвертируем в crypto через курс
$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),
]);
// Сохраняем external ID для reconciliation
$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(),
]);
}
}
Обработка webhook
sale_ps_interact.php — стандартный endpoint Битрикс для платёжных нотификаций. Обработчик получает управление через processRequest:
public function processRequest(Payment $payment, Request $request)
{
$invoiceId = $request->get('invoice_id');
$status = $request->get('status');
$signature = $request->get('signature');
// 1. Верификация подписи
if (!$this->verifyWebhookSignature($request->toArray(), $signature)) {
$logger->error('Invalid webhook signature', ['invoice' => $invoiceId]);
return ServiceResult::createError('INVALID_SIGNATURE');
}
// 2. Проверка суммы через API (не доверяем webhook-данным)
$invoiceData = $this->gateway->getInvoice($invoiceId);
if ($invoiceData['status'] !== 'confirmed') {
return ServiceResult::createSuccess(); // ждём
}
// 3. Проверяем что сумма совпадает
$expectedSum = $payment->getSum();
if (!$this->isAmountSufficient($invoiceData['received_amount'], $expectedSum)) {
return ServiceResult::createError('UNDERPAYMENT');
}
// 4. Подтверждаем оплату в Битрикс
$result = $payment->setField('PAID', 'Y');
if ($result->isSuccess()) {
$payment->save();
// Триггер события — отправит email, обновит статус заказа
\Bitrix\Sale\Order::load($payment->getOrderId())->save();
}
return ServiceResult::createSuccess();
}
Курсы валют
Нельзя показывать курс из произвольного источника без фиксации. Используйте официальный курс с 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 минут. Если пользователь оплачивает после истечения — создавайте новый инвойс с актуальным курсом.
Сохранение данных транзакции
Битрикс не имеет нативного хранилища для кастомных данных платежа. Варианты:
\Bitrix\Sale\Internals\PaymentTable — штатная таблица, через setExtraParams можно сохранять произвольные поля (сериализованные в PS_PARAMS).
Отдельная таблица — предпочтительно для объёмных данных и последующей аналитики:
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'), // USDT, BTC, ETH
new StringField('NETWORK'), // ethereum, tron, bitcoin
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-кодом адреса и таймером:
// В шаблоне компонента /local/templates/.../pay.php
$invoiceData = $arResult['PAY_SYSTEM_PARAMS'];
?>
<div class="crypto-payment">
<p>Переведите <strong><?= $invoiceData['amount'] ?> <?= $invoiceData['currency'] ?></strong></p>
<div class="qr-code">
<img src="https://api.qrserver.com/v1/create-qr-code/?data=<?=
urlencode($invoiceData['payment_uri']) ?>&size=200x200">
</div>
<code class="address"><?= $invoiceData['address'] ?></code>
<div class="timer" data-expires="<?= $invoiceData['expires_at'] ?>">
Оплатите в течение <span id="countdown"></span>
</div>
</div>
Payment URI для EVM: ethereum:0xADDRESS/transfer?address=0xTO&uint256=AMOUNT (EIP-681). Для BTC: bitcoin:ADDRESS?amount=0.001&label=Order123.
Тестирование
Битрикс не имеет sandbox для платёжных систем. Тестовый сценарий: создаёте тестовую платёжную систему, TYPE=BACK_URL_NOTIFY отправляете вручную через curl с тестовыми данными, проверяете статусы.
curl -X POST https://yourshop.ru/bitrix/tools/sale_ps_interact.php \
-d "TYPE=BACK_URL_NOTIFY&PAYMENT_ID=123&invoice_id=test_inv_001&status=confirmed&signature=..."
Типичные проблемы
Порядок событий. Битрикс сохраняет PAID=Y только если Order::save() вызван корректно — Payment::save() недостаточно. Тестируйте полный флоу с реальным заказом.
CSRF на webhook URL. sale_ps_interact.php обходит CSRF-защиту, но ваш кастомный webhook endpoint — нет. Если делаете отдельный endpoint, добавьте define('STOP_STATISTICS', true) и define('NO_KEEP_STATISTIC', 'Y') в начало файла.
Часовой пояс. Битрикс хранит даты в UTC, но выводит с учётом настроек сайта. При сравнении expires_at используйте \Bitrix\Main\Type\DateTime а не нативный PHP time().
Процесс работы
Анализ версии Битрикс и текущей платёжной архитектуры → разработка модуля → интеграция с gateway (NOWPayments/CoinPayments или кастомный) → тестирование на staging → установка на production.
Срок 2-3 дня: день на модуль + webhook, день на тестирование edge cases, день на production деплой и мониторинг первых транзакций.