Інтеграція 1С-Бітрікс з розстрочкою Черепаха (Білорусь)

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