Інтеграція 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');
}

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

Терміни