Integration of 1C-Bitrix with the Assist Belarus payment system

1C-Bitrix Integration with Assist Belarus Payment Gateway

Assist Belarus is a Belarusian processing payment gateway that aggregates multiple payment methods: Visa/Mastercard/Belkart cards, ERIP, and others. For Belarusian online stores it is a convenient option: a single connection covers card acquiring and ERIP without the need to work with each bank separately. Technically, the integration is built on the Assist REST API, which is architecturally similar to Russian gateways but has its own specifics.

How Assist Belarus Works

Assist acts as an aggregator: the store connects to a single gateway, and the actual processing (Belkart, Visa, ERIP) happens on the Assist side. The interaction flow:

1. The store sends a request to the Assist API (https://payments.assist.by/) with the order parameters
2. Assist returns an orderId and the URL of the payment page
3. The customer selects a payment method and pays on the Assist page
4. Assist sends a POST notification to the store's callback_url
5. The store verifies the data and confirms the order

The API operates over HTTPS POST with parameters in the request body (application/x-www-form-urlencoded) or JSON, depending on the API version.

Configuring the Handler in 1C-Bitrix

Assist Belarus has no official module in the Bitrix Marketplace, so the integration is implemented as a custom payment system handler in the sale module.

Placement: /local/php_interface/include/sale_payment/assist_belarus/

Key settings (.settings.php):

return [
    'MERCHANT_ID'   => ['NAME' => 'Merchant ID',       'SORT' => 100],
    'LOGIN'         => ['NAME' => 'Assist Login',       'SORT' => 200],
    'PASSWORD'      => ['NAME' => 'Password',           'SORT' => 300],
    'TEST_MODE'     => ['NAME' => 'Test mode',          'SORT' => 400],
    'CURRENCY'      => ['NAME' => 'Currency (BYN/USD)', 'SORT' => 500],
];

The initiatePay method builds the invoice creation request:

$params = [
    'Merchant_ID'  => $this->getParam('MERCHANT_ID'),
    'OrderNumber'  => $order->getField('ACCOUNT_NUMBER'),
    'OrderAmount'  => number_format($payment->getSum(), 2, '.', ''),
    'OrderCurrency'=> $this->getParam('CURRENCY'),
    'URL_RETURN'   => $returnUrl,
    'URL_RETURN_NO'=> $failUrl,
    'callbackType' => 'server',
    'callbackURL'  => $callbackUrl,
    'Language'     => 'RU',
];

Notification Verification

Assist passes the signature via the Signature parameter — MD5 or SHA256 of the concatenation of Merchant_ID, OrderNumber, OrderAmount, OrderCurrency, and the secret key. The field order is fixed and specified in the documentation.

Notification handling in processRequest:

$expectedSign = md5(
    $merchantId . $orderNumber . $orderAmount . $currency . $secretKey
);
if ($expectedSign !== strtolower($_POST['Signature'])) {
    throw new \Exception('Invalid signature');
}

$status = $_POST['OrderState'];
if ($status === 'Approved') {
    $payment->setPaid('Y');
    $payment->save();
}

Assist statuses: Approved (paid), Declined (declined), Cancelled (cancelled), Pending (awaiting).

Currency Operations

Assist Belarus supports transactions in BYN, USD, and EUR. If prices in the store are in BYN but the customer wants to pay by card in USD, Assist performs the conversion at the National Bank rate at the time of the transaction. In 1C-Bitrix it is important to pass the correct currency code — ISO 4217 (BYN, USD, EUR), not symbolic designations (р., $).

Working with ERIP via Assist

When ERIP is connected through the Assist aggregator, the customer is offered a choice on the payment page: "Card" or "ERIP". When ERIP is selected, Assist returns the payment details — the ERIP number and a QR code. The store receives the notification the same way as for a card payment.

The advantage of the aggregator model is that you do not need to register separately in the ERIP service tree: Assist handles this under the terms of the contract. However, the service code in the tree will be tied to Assist, not directly to your company.

Real Case: Double Charge

A Belarusian cosmetics store discovered that several customers were charged twice. Log analysis revealed: a customer clicked "Pay", the page hung for a few seconds (slow hosting), the customer clicked again — two requests were sent to Assist with different OrderNumber values (1C-Bitrix created two payments for one order). The fix: disable the button with disabled after the first click at the JavaScript level, and add a server-side check in 1C-Bitrix — do not create a new payment if the order already has an active unprocessed one.

Timeline

Assist Belarus provides test access within 1–3 days of submitting an application. Handler development and testing takes 2–4 business days. Full activation of the live account after site review takes 3–7 business days.