Интеграция 1С-Битрикс с интернет-эквайрингом МТБанк (Беларусь)

Интеграция 1С-Битрикс с интернет-эквайрингом МТБанка (Беларусь)

МТБанк — белорусский коммерческий банк, активно работающий в розничном и e-commerce-сегменте. Интернет-эквайринг МТБанка популярен среди белорусских онлайн-ритейлеров: банк предоставляет конкурентные тарифы и поддерживает карты VISA, Mastercard, Белкарт, а также платёж через ЕРИП. Технически шлюз МТБанка построен на процессинге BSC (Belarusian Switch Company) с редиректной схемой оплаты.

Техническая схема работы

МТБанк использует шлюз payment.mtbank.by с REST API. Особенности:

• Аутентификация — Basic Auth (merchantId:secretKey) или токен в заголовке
• Сумма — в белорусских копейках (BYR исторически, BYN с 2016 года — всегда уточняйте актуальные требования в документации банка)
• Уведомления — POST на notificationUrl с JSON-payload
• Поддержка ЕРИП — отдельный тип платежа с QR-кодом и кодом ЕРИП

Регистрация платежа

class MTBankGateway
{
    private const API_BASE = 'https://payment.mtbank.by/v1/';
    private string $merchantId;
    private string $secretKey;

    public function createPayment(array $data): array
    {
        $payload = [
            'merchantOrderId'  => 'BX_' . $data['orderId'],
            'amount'           => (int)round($data['amount'] * 100),
            'currency'         => 'BYN',
            'description'      => 'Заказ №' . $data['orderId'],
            'returnUrl'        => $data['returnUrl'],
            'failureUrl'       => $data['failureUrl'],
            'notificationUrl'  => $data['notificationUrl'],
            'language'         => 'ru',
            'paymentMethod'    => 'CARD',  // или 'ERIP'
            'customer'         => [
                'email' => $data['email'] ?? null,
                'phone' => $data['phone'] ?? null,
            ],
        ];

        return $this->post('payments', $payload);
    }

    private function post(string $endpoint, array $data): array
    {
        $ch = curl_init(self::API_BASE . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => [
                'Content-Type: application/json',
                'Authorization: Basic ' . base64_encode($this->merchantId . ':' . $this->secretKey),
                'X-Request-ID: ' . \Ramsey\Uuid\Uuid::uuid4()->toString(),
            ],
            CURLOPT_SSL_VERIFYPEER => true,
        ]);
        $result = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new \RuntimeException("MTBank API error $httpCode: $result");
        }

        return json_decode($result, true);
    }
}

Платёж через ЕРИП

ЕРИП (Единое расчётное и информационное пространство) — белорусская система платежей через интернет-банкинги и терминалы. МТБанк позволяет генерировать ЕРИП-запрос и QR-код:

$eripPayment = $gateway->createPayment([
    'orderId'         => $orderId,
    'amount'          => $amount,
    'paymentMethod'   => 'ERIP',
    'eripServiceCode' => '123456789', // код услуги в ЕРИП, выдаётся банком
    'returnUrl'       => $returnUrl,
    'notificationUrl' => $notifyUrl,
]);

// В ответе будут eripCode (для ввода в банкинге) и qrCode (base64 PNG)
$eripCode = $eripPayment['eripCode'];
$qrCodePng = base64_decode($eripPayment['qrCode']);

ЕРИП-платежи имеют отложенное подтверждение — покупатель может оплатить в течение нескольких часов или дней. Учитывайте это при настройке времени жизни заказа.

Обработка уведомлений

// Обработчик webhook
$rawBody = file_get_contents('php://input');
$event   = json_decode($rawBody, true);

// МТБанк передаёт подпись в заголовке X-Signature
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $rawBody, $secretKey);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Signature mismatch');
}

$orderId = $event['merchantOrderId'];
$status  = $event['status'];

// Карты
if ($status === 'COMPLETED') {
    $payment->setPaid('Y');
}

// ЕРИП
if ($status === 'ERIP_PAID') {
    $payment->setPaid('Y');
}

Статусы платежа МТБанка:

Сроки