Integrating 1C-Bitrix with the Sberbank Online payment system

1C-Bitrix Integration with Sberbank Online Payment System

A common scenario: an online store on Bitrix is running, orders are coming in, but customers call asking to "send a Sber invoice" because they don't see the right button on the payment page. Connecting Sberbank Online to Bitrix solves that request and also surfaces several technical nuances that are not obvious at the "just install the module" stage.

How the Sberbank Payment Gateway Works

Sberbank Online operates via a REST API (securepayments.sberbank.ru/payment/rest/ for production, 3dsec.sberbank.ru/payment/rest/ for testing). The interaction flow:

1. The store calls register.do — registers the order with Sberbank and receives orderId and formUrl
2. The customer is redirected to formUrl — the Sberbank payment page
3. After payment, Sberbank redirects the customer to returnUrl and sends a notification to failUrl or fires a callback
4. The store calls getOrderStatus.do for a final status check

It is critical not to rely solely on returnUrl for payment confirmation — the customer may close the tab after paying without waiting for the redirect. A callback or periodic polling of getOrderStatus.do is always required.

Technical Integration with 1C-Bitrix

Within the Bitrix ecosystem, Sberbank Online is implemented as a payment system handler in the sale module. There are several approaches.

Ready-made marketplace module. The official Sberbank module (sberbank.ecom) is available on marketplace.1c-bitrix.ru. After installation, a new payment type appears in Shop → Settings → Payment Systems with fields for userName, password (or token for the new authentication scheme). The module registers the handler \Sale\Handlers\PaySystem\SberbankHandler and a webhook URL in the form /bitrix/tools/sale_ps_result.php.

Custom handler is needed when: a non-standard order structure is in use, 1C integration is required for automatic status changes, or the ready-made module conflicts with other components. It is placed in /local/php_interface/include/sale_payment/sberbank_custom/ with a standard Sale PaySystem structure.

Key Parameters for Order Registration

The register.do call requires mandatory parameters:

• orderNumber — unique identifier in the store system (typically BXORDER_{ID})
• amount — amount in kopecks (a common error is passing it in rubles)
• returnUrl — redirect URL after payment
• currency — currency code (643 for rubles per ISO 4217)

For fiscal compliance (54-FZ), an orderBundle object containing line items, VAT rates, and payment subject codes is added to the request. Without orderBundle, Sberbank's fiscal register will not generate a receipt — this is a frequent source of tax authority complaints against stores that "supposedly enabled the online cash register."

Notification Handling and Statuses

Sberbank sends a POST notification to checkUrl when the transaction status changes. The Bitrix callback handler must:

1. Accept the POST and parse mdOrder and orderNumber
2. Call getOrderStatus.do to retrieve the current status (do not trust callback data without verification)
3. On status 2 (paid), call $payment->setPaid('Y') and save the transaction
4. Return {"errorCode": 0} — otherwise Sberbank will keep retrying

getOrderStatus.do status codes:

Two-Stage Payment

For goods with deferred shipping (pre-orders, warehouse), the two-stage scheme is used: registerPreAuth.do places a hold on the card, and deposit.do charges it upon shipment. Sberbank provides both methods, but two-stage payment requires a separate enablement in the acquiring contract. In Bitrix, this is implemented by splitting the handler into two stages and adding a "Confirm Payment" button in the order admin panel.

Real-World Case: Duplicate Payment Issue

An electronics store on Bitrix 21. After switching from the test environment to production, roughly 3% of transactions were duplicated — the customer paid once but two payments were recorded against the order. Cause: the returnUrl handler and the callback arrived almost simultaneously, and both managed to call setPaid('Y'). Fix: add a check for $payment->isPaid() before confirming, and use a lock via \Bitrix\Main\Application::getConnection()->lock() during transaction processing.

Testing

The Sberbank test environment (3dsec.sberbank.ru) works with test cards from the documentation. Be sure to test:

• Successful payment confirmed via callback
• Cancellation on the payment page (customer clicks "Back")
• Session timeout (default is 1,200 seconds — Sberbank cancels unfinished orders)
• Correct receipt generation when the fiscal register is enabled

Integration timelines depend on the configuration: installing the ready-made module without fiscal compliance — 1–2 days. Full integration with 54-FZ, two-stage payment, and adaptation to a non-standard order structure — 3–7 working days.