При підключенні сервісу Черепаха до 1С-Бітрікс розробники стикаються з типовими проблемами: нестабільне кешування OAuth-токена, розсинхронізація статусів замовлень через неправильну обробку вебхуків та відсутність механізму повернень. Кожна з цих помилок здатна паралізувати прийом платежів і призвести до втрати клієнтів. МТБанк видає токен з часом життя 3600 секунд — якщо кеш збивається, магазин перестає створювати замовлення. Вебхуки підписуються HMAC-SHA256, і будь-яка помилка в алгоритмі валідації призводить до відхилення сповіщень. Ми готуємо інтеграцію так, щоб ці граблі залишилися в пісочниці. Наприклад, один з наших клієнтів — інтернет-магазин з великим оборотом — втратив 15% замовлень через неправильне кешування. Після впровадження нашої інтеграції відмов не стало, а економія на комісіях за розстрочку стала значною. Отримайте консультацію щодо інтеграції — оцінимо обсяг робіт за 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, а наша інтеграція адаптується під версії Бітрікс. У довгостроковій перспективі кастомне рішення надійніше і дозволяє значно економити на комісіях за рахунок оптимізації. Додатково ми використовуємо 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 день.