Integrating 1C-Bitrix with Sberbank Online Payment System
We often encounter a common issue: an online store on Bitrix works perfectly, and orders flow in. However, buyers frequently call requesting to 'issue an invoice via Sber' — they don't see the payment button on the checkout page. Connecting Sberbank Online to Bitrix addresses this request and reveals several technical nuances not obvious at the 'just install the module' stage. In our practice, every third client comes with this pain: the absence of a payment method used by 60% of buyers. We have completed over 50 payment system integrations, so let's examine all the pitfalls.
Why the ready-made module doesn't always solve the problem?
The official sberbank.ecom module covers 80% of standard scenarios, but when non-standard logic is needed — for example, integration with 1C for automatic status changes or two-stage payment for pre-orders — the ready-made solution becomes a bottleneck. Comparison: the ready-made module is installed in 30 minutes, while a custom one requires 3–5 days but gives full control over payment processing. The speed-to-flexibility ratio is roughly 10:1, but custom development is 3 times more flexible.
How Sberbank's payment gateway works
Sberbank Online operates via the REST API of acquiring (securepayments.sberbank.ru/payment/rest/ for production, 3dsec.sberbank.ru/payment/rest/ for test). Interaction scheme:
- The store calls
register.do— registers the order in Sberbank's system, receivesorderIdandformUrl - The buyer is redirected to
formUrl— Sberbank's payment page - After payment, Sberbank redirects the buyer to
returnUrland sends a notification tofailUrlor performs a callback - The store calls
getOrderStatus.dofor final status verification
It is critically important not to rely solely on returnUrl for payment confirmation — the buyer may close the tab after payment without waiting for the redirect. A callback or periodic polling of getOrderStatus.do is always needed. Source: Sberbank Acquiring documentation
When is custom integration needed?
In the Bitrix ecosystem, Sberbank Online is implemented as a payment system handler of the sale module. There are two paths.
Ready-made module from the Marketplace. The official module from Sberbank (sberbank.ecom) is available on marketplace.1c-bitrix.ru. After installation, in the section Store → Settings → Payment Systems, a new type appears with fields userName, password (or token for the new authentication scheme). The module registers the handler \Sale\Handlers\PaySystem\SberbankHandler and a webhook URL like /bitrix/tools/sale_ps_result.php.
Custom handler is needed when: a non-standard order scheme is used, integration with 1C for automatic status changes is required, or the ready-made module conflicts with other components. It is placed in /local/php_interface/include/sale_payment/sberbank_custom/, with standard structure for Sale PaySystem.
Key parameters when registering an order
The register.do call requires mandatory parameters:
| Parameter | Description | Type |
|---|---|---|
orderNumber |
Unique number in the store's system (usually BXORDER_{ID}) |
string |
amount |
Amount in kopecks (common mistake — passing in rubles) | integer |
returnUrl |
Return URL after payment | string |
currency |
Currency code (643 for rubles per ISO 4217) | integer |
For fiscalization (54-FZ), the request includes an orderBundle object with product items, VAT rates, and payment object signs. Without orderBundle, Sberbank's cash register will not generate a receipt — this is a common reason for tax authority claims against stores that 'supposedly connected an online cash register'. More details on requirements — on Wikipedia.
Notification handling and statuses
Sberbank sends a POST notification to checkUrl when the transaction status changes. In Bitrix, the callback handler must:
- Accept POST, parse
mdOrderandorderNumber - Call
getOrderStatus.doto obtain the actual status (do not trust callback data without verification) - On status
2(paid), call$payment->setPaid('Y')and save the transaction - Return response
{"errorCode": 0}— otherwise Sberbank will retry
Status table for getOrderStatus.do:
| Code | Value | Action |
|---|---|---|
| 0 | Order registered | Wait |
| 1 | Amount pre-authorized | For two-stage payments |
| 2 | Paid | Confirm in Bitrix |
| 3 | Authorization cancelled | Cancel order |
| 4 | Refund completed | Update status |
| 6 | Authorization declined | Notify buyer |
Two-stage payment
What is two-stage payment and when is it needed?
For goods with deferred shipment (pre-order, warehouse), a two-stage scheme is used: registerPreAuth.do blocks the amount on the card, deposit.do debits upon shipment. Two-stage payment reduces chargeback risk by up to 50%. Sberbank provides both methods, but two-stage requires separate activation in the acquiring agreement. In Bitrix, this is implemented by splitting the handler into two stages and adding an extra 'Confirm payment' button in the order admin section. More details on implementation — in Bitrix documentation.
How to avoid duplicate payments?
From our practice: an electronics online store on a modern Bitrix version. After switching from test to production environment, about 3% of transactions were duplicated — the buyer paid once, but two payments were recorded in the order. Cause: the returnUrl handler and callback arrived almost simultaneously, both succeeded in calling setPaid('Y'). Solution — add a check $payment->isPaid() before confirmation and use locking via \Bitrix\Main\Application::getConnection()->lock() during transaction processing.
Testing
Sberbank's test environment (3dsec.sberbank.ru) works with test cards from the documentation. Be sure to check:
- Successful payment with callback confirmation
- Cancellation on the payment page (buyer clicked 'Back')
- Session timeout (default 1200 seconds — Sberbank cancels unfinished orders)
- Correct receipt generation when fiscalization is enabled
What is included in the work?
- Audit of current Bitrix configuration and payment methods
- Setting up the ready-made module or developing a custom handler
- Integration with fiscalization (54-FZ) and cash register
- Testing all scenarios: success, failure, timeout, duplication
- Documentation (installation guide, API parameters, troubleshooting)
- Access to test environment for 30 days
- Training session (1 hour) for your team
- 30 days of post-launch support
Timeline and cost
Integration timeline depends on the configuration: installing a ready-made module without a cash register — from 1 to 2 days. Custom integration with 54-FZ, two-stage payment, and adaptation to non-standard order structure — from 3 to 7 business days. Prices: ready-made module installation from $200; custom integration from $800; full integration with fiscalization from $1,200. 80% of our clients choose custom integration for flexibility. We have been working with Bitrix for over 5 years and have implemented 50+ payment system integrations — this allows us to guarantee quality. Contact us to discuss the details of your integration. We will prepare a solution tailored to your business and take into account all the specifics.