Integration of 1C-Bitrix with MTBank's online acquiring system (Belarus)

1C-Bitrix Integration with MTBank Internet Acquiring (Belarus)

MTBank is a Belarusian commercial bank actively operating in the retail and e-commerce segment. MTBank's internet acquiring is popular among Belarusian online retailers: the bank offers competitive rates and supports VISA, Mastercard, Belkart cards, as well as ERIP payments. Technically, MTBank's gateway is built on BSC (Belarusian Switch Company) processing with a redirect payment scheme.

Technical Workflow

MTBank uses the payment.mtbank.by gateway with a REST API. Key characteristics:

• Authentication — Basic Auth (merchantId:secretKey) or a token in the header
• Amount — in Belarusian kopecks (historically BYR, BYN since 2016 — always check current requirements in the bank's documentation)
• Notifications — POST to notificationUrl with a JSON payload
• ERIP support — a separate payment type with a QR code and ERIP code

Payment Registration

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'      => 'Order #' . $data['orderId'],
            'returnUrl'        => $data['returnUrl'],
            'failureUrl'       => $data['failureUrl'],
            'notificationUrl'  => $data['notificationUrl'],
            'language'         => 'ru',
            'paymentMethod'    => 'CARD',  // or '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);
    }
}

ERIP Payment

ERIP (Unified Settlement and Information Space) is the Belarusian payment system used through internet banking and terminals. MTBank allows generating an ERIP request and QR code:

$eripPayment = $gateway->createPayment([
    'orderId'         => $orderId,
    'amount'          => $amount,
    'paymentMethod'   => 'ERIP',
    'eripServiceCode' => '123456789', // service code in ERIP, issued by the bank
    'returnUrl'       => $returnUrl,
    'notificationUrl' => $notifyUrl,
]);

// The response will contain eripCode (for entry in banking app) and qrCode (base64 PNG)
$eripCode = $eripPayment['eripCode'];
$qrCodePng = base64_decode($eripPayment['qrCode']);

ERIP payments have deferred confirmation — the buyer can pay within several hours or days. Take this into account when configuring the order lifetime.

Handling Notifications

// Webhook handler
$rawBody = file_get_contents('php://input');
$event   = json_decode($rawBody, true);

// MTBank sends the signature in the X-Signature header
$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'];

// Card payments
if ($status === 'COMPLETED') {
    $payment->setPaid('Y');
}

// ERIP
if ($status === 'ERIP_PAID') {
    $payment->setPaid('Y');
}

MTBank payment statuses:

Timeline