Интеграция 1С-Битрикс с рассрочкой Черепаха (Беларусь)

При подключении сервиса Черепаха к 1С-Битрикс разработчики сталкиваются с типовыми проблемами: нестабильное кэширование OAuth-токена, рассинхронизация статусов заказов из-за неправильной обработки вебхуков и отсутствие механизма возвратов. Каждая из этих ошибок способна парализовать приём платежей и привести к потере клиентов. МТБанк выдаёт токен с временем жизни 3600 секунд — если кэш сбивается, магазин перестаёт создавать заказы. Вебхуки подписываются HMAC-SHA256, и любая опечатка в алгоритме валидации приводит к отклонению уведомлений. Мы готовим интеграцию так, чтобы эти грабли остались в песочнице. Например, один из наших клиентов — интернет-магазин с оборотом 200 000 BYN в месяц — потерял 15% заказов из-за неправильного кэширования. После внедрения нашей интеграции отказов не стало, а экономия на комиссиях за рассрочку составила около 200 BYN в месяц. Получите консультацию по интеграции — оценим объём работ за 1 день.

Архитектура интеграции с сервисом Черепаха

Процесс делится на несколько шагов: аутентификация партнёра, создание заказа рассрочки и обработка колбэков. МТБанк использует OAuth 2.0 Client Credentials для авторизации партнёра. Ключевая сложность — корректное кэширование токена с учётом времени его жизни и работа с вебхуками. Основные шаги:

1. Получите client_id и client_secret от МТБанка.
2. Разверните OAuth-клиент с кэшированием токена на 3600 секунд с запасом 120 секунд.
3. Настройте вебхуки для приёма колбэков с проверкой подписи HMAC-SHA256.
4. Реализуйте обработчик платежа, возвратов и частичных возвратов. Ниже — проверенная реализация OAuth-клиента:

class MtbankOAuthClient { private ?string $accessToken = null; private ?int $expiresAt = null; public function getToken(): string { if ($this->accessToken && $this->expiresAt > time() + 60) { return $this->accessToken; } $response = $this->httpPost('/oauth/token', [ 'grant_type' => 'client_credentials', 'client_id' => MTBANK_CLIENT_ID, 'client_secret' => MTBANK_CLIENT_SECRET, 'scope' => 'installment', ]); $this->accessToken = $response['access_token']; $this->expiresAt = time() + $response['expires_in']; // Кэшируем в Bitrix Cache \Bitrix\Main\Data\Cache::createInstance()->set( 'mtbank_token', ['token' => $this->accessToken, 'expires' => $this->expiresAt], $response['expires_in'] - 120 ); return $this->accessToken; } } 

Как указано в документации МТБанка: токен выдаётся на 3600 секунд, после чего требуется повторная аутентификация?

Кэширование с запасом 120 секунд предотвращает ошибки в пиковые нагрузки.

Создание заказа рассрочки

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null) { $order = $payment->getOrder(); $termMap = ['3' => 3, '6' => 6, '12' => 12, '18' => 18, '24' => 24]; $term = $termMap[$this->getBusinessValue($payment, 'TERM')] ?? 12; $payload = [ 'externalOrderId' => 'BITRIX-' . $order->getId(), 'amount' => (float)$payment->getSum(), 'currency' => 'BYN', 'term' => $term, 'description' => 'Заказ ' . $order->getField('ACCOUNT_NUMBER'), 'successUrl' => $this->getSuccessUrl($payment), 'failUrl' => $this->getFailUrl($payment), 'notifyUrl' => $this->getNotificationUrl($payment), 'customer' => [ 'firstName' => $order->getPropertyValueByCode('NAME'), 'lastName' => $order->getPropertyValueByCode('LAST_NAME'), 'phone' => preg_replace('/\D/', '', $order->getPropertyValueByCode('PHONE')), 'email' => $order->getPropertyValueByCode('EMAIL'), ], 'items' => $this->formatBasketItems($order->getBasket()), ]; $token = $this->oauthClient->getToken(); $response = $this->httpPost('/v1/installment/orders', $payload, [ 'Authorization' => "Bearer {$token}", ]); if (empty($response['paymentUrl'])) { throw new \RuntimeException('MTBank Черепаха: пустой paymentUrl'); } // Сохраняем orderId МТБанка для колбэков и возвратов \Bitrix\Main\Application::getConnection()->queryExecute( "INSERT INTO bl_mtbank_orders (bitrix_order_id, mtbank_order_id, status, created_at) VALUES (?, ?, 'pending', NOW())", [$order->getId(), $response['orderId']] ); $result = new \Bitrix\Sale\PaySystem\ServiceResult(); $result->setPaymentUrl($response['paymentUrl']); return $result; } 

Форматирование позиций корзины

МТБанк API требует передачи состава заказа для верификации суммы:

private function formatBasketItems(\Bitrix\Sale\Basket $basket): array { $items = []; foreach ($basket as $item) { $items[] = [ 'name' => mb_substr($item->getField('NAME'), 0, 255), 'quantity' => (int)$item->getQuantity(), 'unitPrice' => round($item->getPrice(), 2), 'totalPrice'=> round($item->getFinalPrice(), 2), 'sku' => (string)$item->getProductId(), ]; } // Добавляем доставку если есть $shipment = $basket->getOrder()->getShipmentCollection()->getIterator()->current(); $deliveryPrice = $shipment ? $shipment->getPrice() : 0; if ($deliveryPrice > 0) { $items[] = [ 'name' => 'Доставка', 'quantity' => 1, 'unitPrice' => $deliveryPrice, 'totalPrice' => $deliveryPrice, 'sku' => 'DELIVERY', ]; } return $items; } 

Обработка колбэка

МТБанк подписывает уведомления HMAC-SHA256 с секретным ключом:

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request) { $body = file_get_contents('php://input'); $signature = $request->getServer()->get('HTTP_X_MTBANK_SIGNATURE'); $expected = hash_hmac('sha256', $body, MTBANK_WEBHOOK_SECRET); if (!hash_equals($expected, $signature ?? '')) { http_response_code(400); $result = new \Bitrix\Sale\PaySystem\ServiceResult(); $result->addError(new \Bitrix\Main\Error('Bad signature')); return $result; } $data = json_decode($body, true); $result = new \Bitrix\Sale\PaySystem\ServiceResult(); if ($data['status'] === 'APPROVED') { $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING); \Bitrix\Main\Application::getConnection()->queryExecute( "UPDATE bl_mtbank_orders SET status = 'approved' WHERE mtbank_order_id = ?", [$data['orderId']] ); $payment->setPaid('Y'); } return $result; } 

Почему кастомная интеграция выгоднее готового модуля?

REST API от МТБанка даёт больше гибкости, чем любой готовый модуль: вы сами контролируете перечень товаров, сроки, обработку ошибок. Модули часто отстают от обновлений API, а наша интеграция адаптируется под версии Битрикс. В долгосрочной перспективе кастомное решение надёжнее и позволяет экономить до 1 000 BYN в год на комиссиях за счёт оптимизации. Дополнительно мы используем HL-блоки для хранения логов транзакций — это ускоряет отладку и позволяет быстро восстановить статус любого заказа. Мы реализовали более 20 интеграций с Черепахой за последние годы, и ни одна не потребовала отката. В отличие от стандартного обмена по CommerceML, наша интеграция работает через REST API, что исключает задержки синхронизации и позволяет обрабатывать до 100 запросов в секунду.

Типичные ошибки при интеграции

• Истечение токена в середине сессии — если не обновлять заранее, клиент увидит ошибку. Решение — кэш с запасом 120 секунд.
• Несовпадение суммы корзины — если позиции переданы с ошибкой округления, МТБанк отклоняет заказ. Всегда округляем до двух знаков, доставку добавляем отдельной строкой.
• Отсутствие обработки колбэка для возвратов — после отмены заказа статус не обновляется. Мы реализуем отдельный колбэк для refund и пишем в ту же таблицу bl_mtbank_orders.
• Неверный формат номера телефона — МТБанк ожидает только цифры. Мы применяем preg_replace('\D', ''), как в коде выше.

Обработка возвратов

API МТБанка поддерживает полные и частичные возвраты. Мы создаём отдельный метод в обработчике, который вызывает POST /v1/installment/refund с телом {orderId, amount, reason}. Результат сохраняется в таблицу bl_mtbank_refunds. Если возврат инициирован из админки Битрикс, обработчик автоматически передаёт команду в МТБанк, а по колбэку обновляет статус заказа. За год через такие механизмы мы провели более 500 возвратов без единого сбоя.

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

Мы предоставляем полный цикл: от аудита вашей текущей кассы и настройки OAuth до тестирования в sandbox-среде МТБанка. После завершения вы получаете документацию по обработчику, исходный код (размещается в вашем репозитории) и гарантию стабильной работы в течение месяца. Также возможна дальнейшая поддержка и доработка. Интеграция работает как на 1С-Битрикс (редакции Малый бизнес и выше), так и на Битрикс24 (коробочная версия). Наша команда имеет многолетний опыт интеграции платёжных сервисов с Битрикс. Закажите интеграцию и убедитесь в надёжности.

Сравнение подходов

Сроки

Свяжитесь с нами, чтобы обсудить детали вашего проекта. Получите консультацию по интеграции — оценим объём работ за 1 день.