Integration of 1C-Bitrix with the Belkart payment system (Belarus)

1C-Bitrix Integration with the Belkart Payment System (Belarus)

Belkart is the national payment system of the Republic of Belarus. If an online store operates in the Belarusian market and accepts only VISA/Mastercard, it loses part of its audience: a significant share of Belarusian buyers use Belkart or Belkart-Maestro as their primary card. Belkart integration differs from standard VISA/Mastercard acquiring: cards are processed through the Belarusian processing center (NKFO "ERIP"), and the technical protocol is different.

Architecture and Protocol

Belkart offers several integration options:

1. Through an acquiring bank — most Belarusian banks (Belarusbank, Priorbank, BelVEB, MTBank, etc.) support Belkart in their acquiring. In this case Belkart transactions are processed through the same gateway as VISA/Mastercard — no separate integration is required, just verify that Belkart is covered in your contract.

2. Direct integration via NKFO "ERIP" — for large merchants, connecting directly to Belkart processing. Protocol: ISO 8583 or NKFO ERIP REST API.

For most Bitrix online stores the first option is relevant — adding Belkart to an existing bank acquiring setup.

Belkart Protocol Specifics

When connecting directly via NKFO ERIP, a REST API with specific characteristics is used:

class BelkartGateway
{
    private const API_URL = 'https://gateway.belkart.by/api/v1/';
    private string $terminalId;
    private string $merchantKey;

    public function createOrder(array $data): array
    {
        $timestamp = date('YmdHis');
        $signature = $this->sign($data, $timestamp);

        $payload = [
            'TerminalID'  => $this->terminalId,
            'OrderID'     => 'BX' . $data['orderId'],
            'Amount'      => (int)($data['amount'] * 100), // BYN kopecks
            'Currency'    => '933', // BYN
            'Description' => 'Payment for order #' . $data['orderId'],
            'ReturnURL'   => $data['returnUrl'],
            'NotifyURL'   => $data['notifyUrl'],
            'Language'    => 'RU',
            'Timestamp'   => $timestamp,
            'Signature'   => $signature,
        ];

        return $this->request('orders', $payload);
    }

    private function sign(array $data, string $timestamp): string
    {
        // Concatenation of fields in a defined order + key
        $signString = $this->terminalId
            . $data['orderId']
            . (int)($data['amount'] * 100)
            . '933'
            . $timestamp
            . $this->merchantKey;

        return strtoupper(hash('sha256', $signString));
    }

    private function request(string $endpoint, array $data): array
    {
        $ch = curl_init(self::API_URL . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        ]);
        $result = curl_exec($ch);
        curl_close($ch);
        return json_decode($result, true);
    }
}

3D-Secure for Belkart

Belkart supports the 3D-Secure protocol (the national implementation is called "Belkart-3D"). After being redirected to the payment page, the buyer completes verification via SMS code or mobile banking. This is handled on the processing side; the store only receives the final notification — no involvement in the 3DS protocol is required.

Combined Payment Form (Multi-payment)

The recommended UX for Belarusian stores is a single form with multiple payment systems:

[VISA / Mastercard] [Belkart] [ERIP]

In 1C-Bitrix this is implemented via multiple payment systems in the sale module, or via a single handler with a paymentType parameter. When the buyer selects "Belkart", the form shows card fields with the Belkart logo; the rest of the flow is identical to VISA acquiring.

Handling Notifications

$body = file_get_contents('php://input');
$data = json_decode($body, true);

// Verify the response signature
$receivedSig = $data['Signature'] ?? '';
$expectedSig = strtoupper(hash('sha256',
    $data['TerminalID']
    . $data['OrderID']
    . $data['Amount']
    . $data['Currency']
    . $data['Status']
    . $merchantKey
));

if (!hash_equals($expectedSig, $receivedSig)) {
    http_response_code(403);
    exit;
}

if ($data['Status'] === 'APPROVED') {
    $payment->setPaid('Y');
    $payment->setField('PS_STATUS_CODE', $data['RespCode'] ?? '');
    $payment->save();
}

Testing

Belkart provides test cards through member banks. A test card is issued when connecting to the gateway test environment. It is critical to test:

• Successful payment with a Belkart card and 3D-Secure
• Decline due to a limit
• Cancellation on the payment page

Timeline