Інтегрувати криптоплатежі в 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, і спрощує формування звітів.
| Критерій | PaymentTable (PS_PARAMS) | Окрема ORM-таблиця |
|---|---|---|
| Швидкість запису | Швидко (серіалізація) | Трохи повільніше (ORM) |
| Гнучкість запитів | Обмежена (JSON) | Повноцінний SQL/ORM |
| Звітність | Складно | Просто (агрегації) |
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().
Типові проблеми
Порядок подій. Бітрікс зберігає 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().
Порівняння платіжних шлюзів
| Характеристика | NOWPayments | CoinPayments |
|---|---|---|
| Підтримувані мережі | ETH, BSC, Polygon | BTC, LTC, ETH, TRX |
| Фіксування курсу | Так (15 хв) | Так (10 хв) |
| Комісія шлюзу | 0.5% | 0.5% + $0.05 |
| Webhook-підпис | HMAC SHA256 | HMAC SHA512 |
Вибір шлюзу залежить від валют та вимог до комісій. Економія на комісіях за рахунок використання криптоплатежів може досягати 3% від обороту.
Процес роботи
- Аналіз версії Бітрікс та поточної платіжної архітектури.
- Розробка модуля.
- Інтеграція з gateway (NOWPayments/CoinPayments або кастомний).
- Тестування на staging.
- Встановлення на production.
Терміни: 2-3 дні: день на модуль + webhook, день на тестування edge cases, день на production деплой та моніторинг перших транзакцій.
Що входить у роботу?
- Готовий модуль з обробником, webhook та ORM-таблицею
- Інтеграція з обраним криптошлюзом
- Кастомна сторінка оплати з QR та таймером
- Тестування на staging та production
- Документація зі встановлення та налаштування
- Навчання адміністратора
- Підтримка протягом 1 місяця після запуску
Гарантуємо працездатність модуля на версіях Бітрікс 20.0+ та PHP 7.4–8.2. Досвід понад 5 років у розробці на Бітрікс та 20+ інтеграцій криптоплатежів. Оцінимо ваш проєкт за 1 робочий день — зв'яжіться для консультації. Замовте інтеграцію, і ми підготуємо модуль під ваш проєкт. Отримайте консультацію щодо вашого проєкту.