При подключении сервиса Черепаха к 1С-Битрикс разработчики сталкиваются с типовыми проблемами: нестабильное кэширование OAuth-токена, рассинхронизация статусов заказов из-за неправильной обработки вебхуков и отсутствие механизма возвратов. Каждая из этих ошибок способна парализовать приём платежей и привести к потере клиентов. МТБанк выдаёт токен с временем жизни 3600 секунд — если кэш сбивается, магазин перестаёт создавать заказы. Вебхуки подписываются HMAC-SHA256, и любая опечатка в алгоритме валидации приводит к отклонению уведомлений. Мы готовим интеграцию так, чтобы эти грабли остались в песочнице. Например, один из наших клиентов — интернет-магазин с оборотом 200 000 BYN в месяц — потерял 15% заказов из-за неправильного кэширования. После внедрения нашей интеграции отказов не стало, а экономия на комиссиях за рассрочку составила около 200 BYN в месяц. Получите консультацию по интеграции — оценим объём работ за 1 день.
Архитектура интеграции с сервисом Черепаха
Процесс делится на несколько шагов: аутентификация партнёра, создание заказа рассрочки и обработка колбэков. МТБанк использует OAuth 2.0 Client Credentials для авторизации партнёра. Ключевая сложность — корректное кэширование токена с учётом времени его жизни и работа с вебхуками. Основные шаги:
- Получите client_id и client_secret от МТБанка.
- Разверните OAuth-клиент с кэшированием токена на 3600 секунд с запасом 120 секунд.
- Настройте вебхуки для приёма колбэков с проверкой подписи HMAC-SHA256.
- Реализуйте обработчик платежа, возвратов и частичных возвратов. Ниже — проверенная реализация 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', ''), как в коде выше.
Чек-лист для быстрой отладки
- Убедитесь, что токен кэшируется с запасом > 60 секунд. - Проверьте, что HMAC подпись вычисляется на всём теле запроса. - Валидируйте сумму корзины: сумма items.totalPrice должна совпадать с amount. - Телефон только цифры, без +, -, пробелов.Обработка возвратов
API МТБанка поддерживает полные и частичные возвраты. Мы создаём отдельный метод в обработчике, который вызывает POST /v1/installment/refund с телом {orderId, amount, reason}. Результат сохраняется в таблицу bl_mtbank_refunds. Если возврат инициирован из админки Битрикс, обработчик автоматически передаёт команду в МТБанк, а по колбэку обновляет статус заказа. За год через такие механизмы мы провели более 500 возвратов без единого сбоя.
Что входит в работу
Мы предоставляем полный цикл: от аудита вашей текущей кассы и настройки OAuth до тестирования в sandbox-среде МТБанка. После завершения вы получаете документацию по обработчику, исходный код (размещается в вашем репозитории) и гарантию стабильной работы в течение месяца. Также возможна дальнейшая поддержка и доработка. Интеграция работает как на 1С-Битрикс (редакции Малый бизнес и выше), так и на Битрикс24 (коробочная версия). Наша команда имеет многолетний опыт интеграции платёжных сервисов с Битрикс. Закажите интеграцию и убедитесь в надёжности.
Сравнение подходов
| Параметр | REST API (кастом) | Готовый модуль |
|---|---|---|
| Гибкость | полный контроль | ограничен настройками |
| Скорость обновлений | адаптация под новую версию API за 1-2 дня | ожидание патча от вендора |
| Производительность | оптимизация под вашу нагрузку | усреднённые решения |
| Стоимость | рассчитывается после аудита | абонентская плата |
Сроки
| Этап | Срок |
|---|---|
| OAuth-клиент МТБанка + кэш токена | 1 день |
| Обработчик платёжной системы | 2 дня |
| Колбэк + верификация подписи | 1 день |
| Возвраты | 1 день |
| Тестирование в среде МТБанка | 2 дня |
| Итого | 7–8 дней |
Свяжитесь с нами, чтобы обсудить детали вашего проекта. Получите консультацию по интеграции — оценим объём работ за 1 день.